Skip to content

Volume load cycle events - #504

Open
frasercl wants to merge 20 commits into
refactor/sync-meta-loadfrom
feature/load-events
Open

frasercl wants to merge 20 commits into
refactor/sync-meta-loadfrom
feature/load-events

Conversation

@frasercl

@frasercl frasercl commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Review time: medium (~30min)

This PR takes the final step in this stack's aim to make our new event model (#448) the preferred way to observe the volume lifecycle.

It contains several semi-related refactors:

  • Remove loadVolumeData from the VolumeLoader abstract class. This method called the lower-level loadRawChannelData method, then put the data in the passed Volume. With this gone, VolumeLoader is philosophically more like a file system handle: it retrieves metadata about the data it points to synchronously and retrieves data asynchronously, but does not take any action with that data on its own. It also contains no meaningful behavior to justify being an abstract class rather than an interface, so now it's just an interface.
  • Adds events to Volume: loadChannel, loadEnd, loadError, channelAdded, channelRemoved. These should be how client code responds to the volume's load cycle going forward, rather than initiating loads themselves via a VolumeLoader and passing a callback.
  • Reorgs Volume a bit to be more of a container/controller of a VolumeLoader. Accordingly, it gets a new public setLoader and reworked load method with a simpler interface.
  • The above events entirely cover a couple of current APIs. Namely, VolumeDataObserver, currently only used to inform View3d of load events; and setLoadErrorHandler, used to listen for and respond to errors. The latter is now marked deprecated; the former is removed entirely.

Potential future work:

  • I would love for VolumeLoader.loadData to return a promise rather than relying on its current callback interface. Alas, I wasn't able to fully purge its callbacky-ness on this iteration.
  • I also wanted to further refactor Volume to remove the public methods setChannelDataFromAtlas and setChannelDataFromVolume (in favor, again, of VolumeLoaders being the single interface to volume data). This would have allowed these implementation-simple but interface-verbose methods to be brought inside other functions and simplified the code flow for loading data a bit further.
  • My plan above was thwarted by VolumeMaker, a class full of utility functions for generating procedural volumes, which is currently the only way we ever generate data to feed to either of the above methods. I think building a VolumeLoader that accepts SDFs and uses them to generate volume channels would be great, and would allow the refactor above to proceed, but it's a slightly larger project than this PR.

@frasercl
frasercl added this pull request to stack #500 October 23, 2026 03:12
@frasercl
frasercl requested a review from a team as a code owner October 23, 2026 03:12
}

async loadRawChannelData(
async loadData(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this API surfaced to external clients? Do you have plans to make any kind of migration guide from v4 to v5?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is, though the idea of this batch of work is that external clients ought to not call it at all anymore. Which is an even larger change and an even bigger migration effort! I'm not certain where a migration guide would go though. As a .md built on our docs page?

import { VolumeDims } from "../VolumeDims.js";
import { CreateLoaderOptions, PrefetchDirection, VolumeFileFormat, pathToFileType } from "../loaders/index.js";
import { VolumeLoader, LoadSpec, RawChannelDataCallback, LoadedVolumeInfo } from "../loaders/VolumeLoader.js";
import type { VolumeLoader, LoadSpec, RawChannelDataCallback, LoadedVolumeInfo } from "../loaders/VolumeLoader.js";

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should really install some plugins to do this for us...

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've really been feeling this repo's lack of import sorting and type-import validation lately. Might track you down for help putting those things in place later.

Comment thread src/Volume.ts Outdated
Comment on lines +280 to +281
// TODO pass in load specs here?
const { loadSpec, imageInfo } = loader.getImageInfo(infoSpec);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does the TODO here mean? Is it still relevant?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I... have no idea. Looks like I added this whole function in one commit, so best guess it was a note I left for myself while I was working on that? I'll get rid of it.

Comment thread src/Volume.ts
this.loader = loader;
// TODO pass in load specs here?
const { loadSpec, imageInfo } = loader.getImageInfo(infoSpec);
this.imageInfo.imageInfo = imageInfo;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: slightly unfortunate variable + property naming here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I'm not a huge fan of this, but that's how CImageInfo works right now.

(I do think, someday soon, we gotta kill CImageInfo.)

Comment thread src/Volume.ts Resolved
Comment thread src/View3d.ts Resolved
Comment thread public/index.ts Resolved
Comment thread public/index.ts Resolved
@frasercl
frasercl force-pushed the feature/load-events branch from 83318e6 to 09e674e Compare November 11, 2026 01:24
Comment thread public/index.ts
}

function playTimeSeries(onNewFrameCallback: () => void) {
if (myState.isPlaying) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I remember my youth, when myState.isPlaying == true

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants