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?

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 could literally rebuild every single pre-existing json+PNG volume from their original data and put them into zarrs. It's nearly impossible this format exists anywhere else outside of Allen. (except that strangely, the OpenCell data set is strikingly similar).

Either way, this is a legacy data format and vol-e should make as few concessions as possible to handle it. The stuff in this module can not influence vol-e 👿

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.)

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.

Yeah, the imageInfo data structure is an old metadata spec totally invented by me for the json+PNG precomputed volume data. It could be replaced by the standard OME data model, or some better thing that suits vol-e better, or nothing at all?

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

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.

triple equals

@toloudis toloudis left a comment

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.

This is looking really nice now. I had lots of comments/questions but my main concern is just the handling of single channels vs arrays of channels, whether that allows for good performance.

const spec = { ...volume.loadSpec, ...loadSpecOverride };
return this.loadRawChannelData(volume.imageInfo.imageInfo, spec, onUpdateMetadata, onChannelData);
}
updateFetchOptions(options: Partial<ZarrLoaderFetchOptions>): void;

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.

needs docstring now?

Comment thread src/View3d.ts
/**
* @deprecated Will be removed in the next major version.
* Use `Volume.addEventListener("loadError", (event) => { ... }) instead.
*/

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.

hmm, should errors be events like everything else? just a tiny code smell, for me. I guess if we were passing in an error handler before, then it makes sense.

Comment thread src/View3d.ts
volume.addEventListener("loadChannel", this.onVolumeData);
volume.addEventListener("loadError", this.onVolumeLoadError);
volume.addEventListener("channelAdded", this.onVolumeChannelAdded);
volume.addEventListener("channelRemoved", this.onVolumeChannelRemoved);

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.

this pattern looks like it breaks the multi-volume nature of the View3D api. do each of the mapped listeners check that the current volume matches volume ?

Comment thread src/View3d.ts

// channels is an array of channel indices for which new data just arrived.
onVolumeData(volume: Volume, channels: number[]): void {
onVolumeData({ volume, channelIndex }: VolumeEvents["loadChannel"]): void {

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.

I guess this should do a sanity check that this.image.volume === volume? or some equivalent check...

Comment thread src/Volume.ts
loadEnd: VolumeEvent;
loadError: VolumeEvent<{ error: unknown }>;
channelAdded: VolumeEvent<{ channelIndex: number }>;
channelRemoved: VolumeEvent<{ channelIndex: number }>;

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.

I think in a previous review I recommended that this be the place where each event gets its documentation/description of what it means.

Also, might it make sense to have loadChannel potentially send an array of channels that all arrived at the same time? The handler of loadChannel might incur some relatively heavy UI updates and they might happen in rapid succession causing redraws. Testing would reveal this

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.

Yeah, the imageInfo data structure is an old metadata spec totally invented by me for the json+PNG precomputed volume data. It could be replaced by the standard OME data model, or some better thing that suits vol-e better, or nothing at all?

Comment thread src/Volume.ts
} catch (e) {
this.volumeDataObservers.forEach((observer) => observer.onVolumeLoadError(this, e));
throw e;
await this.loader?.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.

Question: does this await force us to wait for all channels to be loaded, ie. does it prevent incremental loading, say, per-channel? is this Volume.load the main api for causing volume data to be loaded?

Comment thread src/VolumeDrawable.ts
if (channelOptions.isosurfaceEnabled) {
this.meshVolume.destroyIsosurface(idx);
const { isovalue, isosurfaceOpacity } = channelOptions;
this.meshVolume.createIsosurface(idx, this.channelColors[idx], isovalue, isosurfaceOpacity);

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.

just curious, where did the onChannelDataReadyCalback go? was it doing anything ?

}

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.

We could literally rebuild every single pre-existing json+PNG volume from their original data and put them into zarrs. It's nearly impossible this format exists anywhere else outside of Allen. (except that strangely, the OpenCell data set is strikingly similar).

Either way, this is a legacy data format and vol-e should make as few concessions as possible to handle it. The stuff in this module can not influence vol-e 👿

Comment thread public/index.ts
volume.channelLoadCallback = onChannelDataArrived;
loader.loadVolumeData(volume, { ...volume.loadSpec, channels });
volume.addEventListener("loadChannel", ({ channelIndex }) => onChannelDataArrived(volume, channelIndex));
volume.load();

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.

just looking at this, it feels scary to just call "load" on a new volume like this. what is going to be loaded? was that all set up inside of onVolumeCreated? That must be where the initial loadSpec is set up. Maybe it would be more instructive/educational to see it more explicit in this function.

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.

4 participants