Class SceneDimsManager

Initializes the scene-level dimension state from metadata embedded in the scene.

This method searches through the THREE.js scene hierarchy to find nD objects with embedded dimension metadata, then establishes the shared dimensional coordinate system for the entire scene.

Search strategy:

1. Check scene.userData.sceneDimensions first (direct attachment)
2. Recursively search scene children for embedded metadata
3. Use the first valid dimension metadata found

Initialization logic:

• Parse metadata into standardized DimensionMetadata format
• Establish ranges from metadata or sensible defaults
• Set non-displayed dimensions to their minimum values
• Identify which dimensions should be displayed (max 3)

Provides read-only access to the current dimension state.

This is the primary interface for components that need to access the current slice positions, displayed dimensions, and metadata.

Gets the navigable bounds for each dimension.

These ranges define the valid navigation space and are used by UI components (sliders, keyboard handlers) to constrain user input and calculate appropriate step sizes.

Updates the position in a specific dimension and triggers re-slicing.

This is the central method for dimension navigation, handling both user input validation and observer notification. It ensures all dimension changes are properly constrained and communicated.

Value processing:

1. Validate dimension index bounds
2. Clamp value to valid range for this dimension
3. Quantize discrete dimensions to their step size
4. Update internal state
5. Notify all observers (triggers UI updates and re-slicing)

Reset every dimension back to its initial default position (same policy as initFromScene) and notify listeners — sliders, slicing, and status displays all refresh reactively. Used by the rail Home popover's "Reset dimensions" action. No-op before initialization.

Registers a callback to be invoked whenever dimension state changes.

This implements the observer pattern, allowing UI components and visualization objects to react automatically to navigation events. Typical subscribers include sliders, points, and status displays.

Callbacks can be async — their completion can be awaited via waitForUpdate().

Unregisters a dimension change callback.

Important for preventing memory leaks when components are destroyed.

Returns a promise that resolves when all pending listener updates complete.

Used by animation systems to wait for data loading before advancing frames. Returns immediately resolved promise if no update is in progress.

Provides access to the complete dimension metadata array.

Used by UI components that need detailed information about dimension properties like names, units, discreteness, etc.

Reset the dimension manager to initial state

Extracts human-readable names for all dimensions.

Provides fallback names when metadata doesn't specify custom names. Used by UI components for labeling sliders and status displays.

Extracts physical units for all dimensions.

Used by UI components to display appropriate unit labels next to numeric values (e.g., "μm", "s", "nm").

Determines if the dataset has navigable dimensions beyond the displayed 3D view.

This is used by UI components to decide whether to show dimension navigation controls (sliders, keyboard hints). If all dimensions are displayed in 3D, no additional navigation UI is needed.