Repository navigation
Conversation
68b6442 to
6be158f
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Event documentation misstates callback timing, load completion scope, and payload guarantees, while the loadEnd typing example produces a TypeScript error.
4 open issues
What changed in this PR
This PR addresses #471 by documenting the events exposed by View3d and Volume, helping vole-core consumers discover subscriptions and payload types.
Changes:
- Adds event descriptions, payload documentation, and type lookup examples.
- Expands
View3ddocumentation with canvas setup and volume usage guidance. - Exports
View3dEventsandEventDispatcherthrough the package entry point.
| File | Description |
|---|---|
src/Volume.ts |
Documents volume events and their payloads. |
src/View3d.ts |
Documents viewer setup and rendering events; exports View3dEvents. |
src/index.ts |
Exposes View3dEvents and EventDispatcher to package consumers. |
Review effort: Balanced
| * `View3d` is an {@linkcode EventDispatcher}. It fires the following events in response to canvas renders: | ||
| * - `render` is fired when the canvas re-renders for any reason, including camera moves, settings changes, data loads, | ||
| * etc. It has no payload. | ||
| * - `renderIteration` is fired when the canvas renders in response to *either a render mode change or a new iteration | ||
| * of the progressive path trace renderer*. It is useful for tracking the current path trace iteration count. Its | ||
| * payload contains the following properties: |
There was a problem hiding this comment.
I sort of agree with the ai review here -- if nothing else, for clarity and accuracy. I wouldn't specifically say on resets to 0 but I'd describe anything that causes the pathtrace to reset, such as camera moves or lighting changes or any appearance change.
| /** | ||
| * The map of all events fired by {@linkcode Volume}. See its documentation for details of event behavior. | ||
| * | ||
| * Retrieve the payload of a specific event using brackets and the event name, like so: `View3dEvents["loadEnd"]`. |
| * {@linkcode load} or automatic loads triggered by settings changes like time point, enabled channels, etc. | ||
| * - `loadChannel` is fired when a specific channel has finished loading. Its payload contains the numeric property | ||
| * `channelIndex` that indicates the specific channel to which it applies. | ||
| * - `loadEnd` is fired when all channels in the `Volume` have finished loading. |
| * In addition to any payload specified above, all events include the property `volume`, which points to the `Volume` | ||
| * that fired the event. |
toloudis
left a comment
There was a problem hiding this comment.
I recommend some shuffling and if the ai review is correct, then need to make a few of the comments be a bit more accurate to what the implementation does.
| * | ||
| * Once you've created a `View3d`, use {@linkcode addVolume}/{@linkcode removeVolume} to add/remove an image to render. | ||
| * | ||
| * Most other methods on `View3d` set rendering options or options on the current image. |
There was a problem hiding this comment.
maybe instead of "current" image, the "specified" image, since on all these methods, you pass a Volume in, right?
| * `View3d` is an {@linkcode EventDispatcher}. It fires the following events in response to canvas renders: | ||
| * - `render` is fired when the canvas re-renders for any reason, including camera moves, settings changes, data loads, | ||
| * etc. It has no payload. | ||
| * - `renderIteration` is fired when the canvas renders in response to *either a render mode change or a new iteration | ||
| * of the progressive path trace renderer*. It is useful for tracking the current path trace iteration count. Its | ||
| * payload contains the following properties: |
There was a problem hiding this comment.
I sort of agree with the ai review here -- if nothing else, for clarity and accuracy. I wouldn't specifically say on resets to 0 but I'd describe anything that causes the pathtrace to reset, such as camera moves or lighting changes or any appearance change.
| * etc. It has no payload. | ||
| * - `renderIteration` is fired when the canvas renders in response to *either a render mode change or a new iteration | ||
| * of the progressive path trace renderer*. It is useful for tracking the current path trace iteration count. Its | ||
| * payload contains the following properties: |
There was a problem hiding this comment.
I suggest moving the descriptions of these events up to the type where they are defined, View3dEvents, as comments above each event type's name
| * - `channelAdded` is fired when a new channel is added to the `Volume`. Its payload contains the property | ||
| * `channelIndex` containing the numeric index of the added channel. | ||
| * - `channelRemoved` is fired when a channel is removed from the `Volume`. Its payload contains the property | ||
| * `channelIndex` containing the numeric index of the removed channel. |
There was a problem hiding this comment.
move these descriptions up to their respective rows in VolumeEvents and refer to VolumeEvents in this comment?
| * In addition to any payload specified above, all events include the property `volume`, which points to the `Volume` | ||
| * that fired the event. |

Resolves #471: documents all the events fired by
View3d/Volume. Docs include links where relevant.