Class PointsSpatialIndexLoader

Loader implementation that uses spatial indices for efficient nD queries.

Key features:

Queries spatial index to find visible point ranges
Loads all attributes with identical ranges (fixes alignment bug)
Projects nD points to 3D display space
Real-time monitoring and performance tracking

Implements

Constructors

constructor

new PointsSpatialIndexLoader(
    zarrLocation: Location<Readable>,
    node: SceneNode,
    refRegistry?: ArrayRefRegistry,
    zarrStore?: Readable,
    l0Cache?: DecompressedChunkCache,
    prefetcher?: ChunkPrefetcher,
    sliceCache?: SliceCache,
): PointsSpatialIndexLoader
Parameters
- zarrLocation: Location<Readable>
- node: SceneNode
- OptionalrefRegistry: ArrayRefRegistry
- OptionalzarrStore: Readable
- Optionall0Cache: DecompressedChunkCache
- Optionalprefetcher: ChunkPrefetcher
- OptionalsliceCache: SliceCache
Returns PointsSpatialIndexLoader
- Defined in src/data/points/points-spatial-index-loader.ts:184

Properties

`Private`chunkIndex

chunkIndex: PointsChunkIndex | null = null

`Private`totalPointsNoIndex

totalPointsNoIndex: number = 0

`Private`_effectiveRadiusConfig

_effectiveRadiusConfig: EffectiveRadiusConfig | null = null

`Private`zarrLocation

zarrLocation: Location<Readable>

`Private`node

node: SceneNode

`Private`_onceInit

_onceInit: OnceInit = ...

`Private`arrays

arrays: {
    positions?: Array<DataType, Readable>;
    colors?: Array<DataType, Readable>;
    radii?: Array<DataType, Readable>;
    sharpness?: Array<DataType, Readable>;
    scalars?: Array<DataType, Readable>;
} = {}

Type Declaration

Optionalpositions?: Array<DataType, Readable>
Optionalcolors?: Array<DataType, Readable>
Optionalradii?: Array<DataType, Readable>
Optionalsharpness?: Array<DataType, Readable>
Optionalscalars?: Array<DataType, Readable>

optional scalars array for colormap lookup.

`Private`rangeLoader

rangeLoader: RangeLoader

`Private`_accumulator

_accumulator: LoadedPointsDataAccumulator | null = null

`Private`_accumulatorConfig

_accumulatorConfig:
| { capacity: number; ndim: number; totalPoints: number }
| null = null

`Private`colorComponents

colorComponents: 3 | 4 = 3

Components per color item, learned from the zarr colors shape at open time: 3 = RGB, 4 = RGBA (alpha = per-point opacity). Strides the accumulator buffers and the projection compaction. Mirrors GSplatsSpatialIndexLoader.colorComponents.

`Private` `Readonly`events

events: LoaderEventEmitter = ...

`Private` `Readonly`metrics

metrics: LoaderMetrics

`Private` `Readonly`activeQueries

activeQueries: Map<string, QueryInfo> = ...

`Private`nextQueryId

nextQueryId: number = 0

`Private` `Readonly`facadeCtx

facadeCtx: SpatialFacadeCtx

`Private`totalQueryCells

totalQueryCells: number = 0

`Private`zarrStore

zarrStore: Readable | null = null

`Private`l0Cache

l0Cache: DecompressedChunkCache | null = null

`Private`_activeProbe

_activeProbe: ResidencyAccumulator | null = null

`Private`_activeSignal

_activeSignal: AbortSignal | null = null

`Private`prefetcher

prefetcher: ChunkPrefetcher | null = null

`Private`sliceCache

sliceCache: SliceCache | null = null

`Private`_initialLoadDone

_initialLoadDone: boolean = false

Accessors

`Private`attrs

get attrs(): PointsMetadata
Get node attributes with proper PointsMetadata typing. This provides type-safe access to point node attributes.

Returns PointsMetadata
- Defined in src/data/points/points-spatial-index-loader.ts:180

Methods

`Private`registerBounds

registerBounds(arrayName: string, array: Array<DataType, Readable>): void
Register array shape with the prefetcher for upper-bounds checking. Thin wrapper around the shared registerPointsArrayBounds helper so the three call sites in initialize() keep their compact form.
Parameters
- arrayName: string
- array: Array<DataType, Readable>
Returns void
- Defined in src/data/points/points-spatial-index-loader.ts:221

initialize

initialize(): Promise<void>
Initialize the loader by loading spatial index and opening arrays

Returns Promise<void>
- Defined in src/data/points/points-spatial-index-loader.ts:228

loadPoints

loadPoints(
viewState: ViewState,
session?: UpdateSession,
): Promise<LoadedPointsData>
Load points data for the given view state
Parameters
- viewState: ViewState
  Current view state
- Optionalsession: UpdateSession
  Optional profiler session for nested timing
Returns Promise<LoadedPointsData>
Implementation of DataLoader.loadPoints
- Defined in src/data/points/points-spatial-index-loader.ts:509

`Private`loadPointsInternal

loadPointsInternal(
    viewState: ViewState,
    session: UpdateSession | undefined,
    queryId: string,
    startTime: number,
): Promise<LoadedPointsData>
Parameters
- viewState: ViewState
- session: UpdateSession | undefined
- queryId: string
- startTime: number
Returns Promise<LoadedPointsData>
- Defined in src/data/points/points-spatial-index-loader.ts:520

updateView

updateView(
    viewState: ViewState,
    session?: UpdateSession,
    signal?: AbortSignal,
): Promise<LoadedPointsData>
Update view for a new slice position.

The spatial index makes each reload proportional to the visible ranges, so re-querying those ranges is the canonical update path for now. This keeps buffer ownership and range-cache behavior deterministic.
Parameters
- viewState: ViewState
  Current view state
- Optionalsession: UpdateSession
  Optional profiler session for nested timing
- Optionalsignal: AbortSignal
Returns Promise<LoadedPointsData>
Implementation of DataLoader.updateView
- Defined in src/data/points/points-spatial-index-loader.ts:795

updateViewWithResidency

updateViewWithResidency(
    viewState: ViewState,
    session?: UpdateSession,
    signal?: AbortSignal,
): Promise<{ data: LoadedPointsData; allResident: boolean }>
Like updateView but also reports whether the load was served entirely from cache (see runWithResidencyProbe).
Parameters
- viewState: ViewState
- Optionalsession: UpdateSession
- Optionalsignal: AbortSignal
Returns Promise<{ data: LoadedPointsData; allResident: boolean }>
- Defined in src/data/points/points-spatial-index-loader.ts:818

prefetchChunks

prefetchChunks(viewState: ViewState): Promise<void>
Warm the cache for the given viewState without producing geometry.

Mirrors GSplatsSpatialIndexLoader.prefetchChunks so the dimension animation controller can fire prefetchChunks(nextSlice) while the current frame renders, hiding network latency. The returned typed arrays are discarded — only the L0 + L1 + L2 caches and the prefetch queue's seen/parsed-cache get populated as a side-effect.
Parameters
- viewState: ViewState
Returns Promise<void>
- Defined in src/data/points/points-spatial-index-loader.ts:838

prefetchChunkBoundary

prefetchChunkBoundary(current: ViewState, predicted: ViewState): Promise<void>
Parameters
- current: ViewState
- predicted: ViewState
Returns Promise<void>
- Defined in src/data/points/points-spatial-index-loader.ts:857

`Private`prefetchArrays

prefetchArrays(): Array<DataType, Readable>[]
Returns Array<DataType, Readable>[]
- Defined in src/data/points/points-spatial-index-loader.ts:875

`Private`queryVisiblePointRanges

queryVisiblePointRanges(viewState: ViewState): Promise<PointRange[]>
Query spatial index for visible point ranges.

Tolerance is computed by the points-specific calculateSpatialQueryTolerance (EffectiveRadiusConfig-aware) and passed to the canonical SpatialQueryBuilder via its tolerance option. Falls back to a uniform tolerance derived from viewState.tolerance/maxRadius for nodes without an EffectiveRadiusConfig.

The builder also handles the extend_to_all short-circuit; we only emit the defensive metadata-missing warning ourselves.
Parameters
- viewState: ViewState
Returns Promise<PointRange[]>
- Defined in src/data/points/points-spatial-index-loader.ts:897

`Private`allocateOutputBuffer

allocateOutputBuffer(
    totalElements: number,
    isEncoded: boolean,
    dtype: string,
):
    | Uint8Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | Float16Array<ArrayBufferLike>
Allocate output buffer for decoded data. For encoded arrays, always use Float32Array (decoder output). For direct arrays, match the source dtype.
Parameters
- totalElements: number
- isEncoded: boolean
- dtype: string
Returns
    | Uint8Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | Float16Array<ArrayBufferLike>
- Defined in src/data/points/points-spatial-index-loader.ts:1012

`Private`loadArrayRefRanges

loadArrayRefRanges(
    attrs: ArrayMetadata,
    ranges: LoadRange[],
    output: Float32Array,
    totalPoints: number,
    actualElementsPerPoint: number,
): Promise<number>
Load an array_ref attribute. Delegates to the shared RangeLoader.loadRangesResolvingRef helper, which opens the target, recomputes per-item element count from the target's shape, and runs RangeLoader.loadRanges against it.

actualElementsPerPoint is passed as the non-ref hint; when an array_ref is in play it's ignored in favour of the target's shape.
Parameters
- attrs: ArrayMetadata
- ranges: LoadRange[]
- output: Float32Array
- totalPoints: number
- actualElementsPerPoint: number
Returns Promise<number>
- Defined in src/data/points/points-spatial-index-loader.ts:1050

`Private`loadColorRanges

loadColorRanges(
    ranges: PointRange[],
): Promise<
    | Uint8Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | null,
>
Load color ranges with multi-type support (preserves original_dtype).

Delegates to the shared color-attribute helper used by the lines and gsplats facades. Handles direct (uint8/uint16/float32 native), encoded (quantized / LUT / broadcasted decoded to Float32 then cast back to original_dtype), and array_ref dispatch in one call.

Kept separate from loadRanges (used for positions / radii / sharpness) because:
- Colors hard-code RGB (3 channels per item) — the shared helper does too.
- Positions / scalars need Float16 preservation that the shared helper's Float32-only direct path would silently widen.
Parameters
- ranges: PointRange[]
Returns Promise<
    | Uint8Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | null,
>
- Defined in src/data/points/points-spatial-index-loader.ts:1089

`Private`loadRanges

loadRanges(
    arrayName: string,
    ranges: PointRange[],
): Promise<
    | Uint8Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | Float16Array<ArrayBufferLike>
    | null,
>
Load array data for specified point ranges.

This method handles multiple encoding strategies:
- Broadcasted: Load once, replicate
- Quantized: Load ranges, dequantize
- LUT: Load indices, decode with lookup table
- Array Reference: Resolve target, dispatch based on target encoding
- Generic Encoded: Decode full array, extract ranges
- Direct: Load ranges directly
Parameters
- arrayName: string
  Name of the array to load (positions, radii, sharpness). For colors, use loadColorRanges which delegates to the shared color-attribute helper.
- ranges: PointRange[]
  Point ranges to load
Returns Promise<
    | Uint8Array<ArrayBufferLike>
    | Float32Array<ArrayBufferLike>
    | Uint16Array<ArrayBufferLike>
    | Float16Array<ArrayBufferLike>
    | null,
>
Typed array with loaded data, or null if array doesn't exist
- Defined in src/data/points/points-spatial-index-loader.ts:1123

`Private`buildProjectionContext

buildProjectionContext(): ProjectionContext
Build a ProjectionContext from instance fields. Done per-call so the helpers in point-loader/projection.ts can stay pure with respect to the loader.

Returns ProjectionContext
- Defined in src/data/points/points-spatial-index-loader.ts:1289

`Private`projectTo3D

projectTo3D(
    wasm: WasmModule,
    positions:
        | Uint8Array<ArrayBufferLike>
        | Float32Array<ArrayBufferLike>
        | Uint16Array<ArrayBufferLike>
        | Float16Array<ArrayBufferLike>
        | null,
    colors:
        | Uint8Array<ArrayBufferLike>
        | Float32Array<ArrayBufferLike>
        | Uint16Array<ArrayBufferLike>
        | Float16Array<ArrayBufferLike>
        | null,
    radii:
        | Uint8Array<ArrayBufferLike>
        | Float32Array<ArrayBufferLike>
        | Uint16Array<ArrayBufferLike>
        | Float16Array<ArrayBufferLike>
        | null,
    sharpness:
        | Uint8Array<ArrayBufferLike>
        | Float32Array<ArrayBufferLike>
        | Uint16Array<ArrayBufferLike>
        | Float16Array<ArrayBufferLike>
        | null,
    viewState: ViewState,
    ranges: PointRange[],
    targetBuffers?: ProjectionTargetBuffers | null,
    scalars?:
        | Uint8Array<ArrayBufferLike>
        | Float32Array<ArrayBufferLike>
        | Uint16Array<ArrayBufferLike>
        | Float16Array<ArrayBufferLike>
        | null,
): LoadedPointsData
Main-thread, WASM-accelerated nD → 3D projection. Thin delegate to projectPointsTo3D in point-loader/projection.ts. The wasm backend (compiled or TS-reference fallback) is resolved by the caller via getPointsBackend(ndim).
Parameters
- wasm: WasmModule
- positions:
      | Uint8Array<ArrayBufferLike>
      | Float32Array<ArrayBufferLike>
      | Uint16Array<ArrayBufferLike>
      | Float16Array<ArrayBufferLike>
      | null
- colors:
      | Uint8Array<ArrayBufferLike>
      | Float32Array<ArrayBufferLike>
      | Uint16Array<ArrayBufferLike>
      | Float16Array<ArrayBufferLike>
      | null
- radii:
      | Uint8Array<ArrayBufferLike>
      | Float32Array<ArrayBufferLike>
      | Uint16Array<ArrayBufferLike>
      | Float16Array<ArrayBufferLike>
      | null
- sharpness:
      | Uint8Array<ArrayBufferLike>
      | Float32Array<ArrayBufferLike>
      | Uint16Array<ArrayBufferLike>
      | Float16Array<ArrayBufferLike>
      | null
- viewState: ViewState
- ranges: PointRange[]
- OptionaltargetBuffers: ProjectionTargetBuffers | null
- Optionalscalars:
      | Uint8Array<ArrayBufferLike>
      | Float32Array<ArrayBufferLike>
      | Uint16Array<ArrayBufferLike>
      | Float16Array<ArrayBufferLike>
      | null
Returns LoadedPointsData
- Defined in src/data/points/points-spatial-index-loader.ts:1304

`Private`createEmptyPointsData

createEmptyPointsData(viewState: ViewState): LoadedPointsData
Empty-points payload for the "no visible points" branches. Thin delegate to createEmptyPointsData in point-loader/projection.ts.
Parameters
- viewState: ViewState
Returns LoadedPointsData
- Defined in src/data/points/points-spatial-index-loader.ts:1334

addEventListener

addEventListener(listener: MonitorEventListener): void
Add event listener
Parameters
- listener: MonitorEventListener
Returns void
Implementation of LoaderMonitor.addEventListener
- Defined in src/data/points/points-spatial-index-loader.ts:1343

removeEventListener

removeEventListener(listener: MonitorEventListener): void
Remove event listener
Parameters
- listener: MonitorEventListener
Returns void
Implementation of LoaderMonitor.removeEventListener
- Defined in src/data/points/points-spatial-index-loader.ts:1350

getMetrics

getMetrics(): LoaderMetrics
Get current metrics

Returns LoaderMetrics
Implementation of LoaderMonitor.getMetrics
- Defined in src/data/points/points-spatial-index-loader.ts:1357

getActiveQueries

getActiveQueries(): QueryInfo[]
Get active queries

Returns QueryInfo[]
Implementation of LoaderMonitor.getActiveQueries
- Defined in src/data/points/points-spatial-index-loader.ts:1375

`Private`emitEvent

emitEvent(event: MonitorEvent): void
Emit event to listeners. Thin wrapper around LoaderEventEmitter.emit so the three call sites in this file keep their this.emitEvent(...) shape; per-listener error isolation lives in the emitter.
Parameters
- event: MonitorEvent
Returns void
- Defined in src/data/points/points-spatial-index-loader.ts:1384

`Private`loadSpatialExtendDimsFromSceneDimensions

loadSpatialExtendDimsFromSceneDimensions(): Promise<boolean[] | null>
Load spatial_extend_dims from scene_dimensions stored in root zarr attributes.

This derives the spatial extension flags from the scene_dimensions which is the single source of truth for dimension configuration. Each dimension has a spatial flag indicating whether points physically extend through it.

For displayed dimensions, we always treat them as spatial (they're in the view plane). For non-displayed dimensions:
- spatial=true: Points extend as hyperspheres (use effective radius)
- spatial=false: Categorical/discrete dimension (exact match required)
Returns Promise<boolean[] | null>
Array of booleans indicating spatial extension per dimension, or null if unavailable
- Defined in src/data/points/points-spatial-index-loader.ts:1402

getAccumulatorStats

getAccumulatorStats(): AccumulatorStats | null
Get accumulator stats for memory monitoring

Returns AccumulatorStats | null
- Defined in src/data/points/points-spatial-index-loader.ts:1457

releaseAccumulator

releaseAccumulator(): void
Release pooled decoded buffers after a progressive parent has copied them. Earlier payloads remain valid because dispose() replaces the accumulator buffers rather than clearing their old arrays. This deliberately gives up pooling across view changes to release the progressive ladder's second copy.

Returns void
- Defined in src/data/points/points-spatial-index-loader.ts:1467

dispose

dispose(): void
Clean up resources

Returns void
Implementation of DataLoader.dispose
- Defined in src/data/points/points-spatial-index-loader.ts:1477

Class PointsSpatialIndexLoader

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns PointsSpatialIndexLoader

Properties

PrivatechunkIndex

PrivatetotalPointsNoIndex

Private_effectiveRadiusConfig

PrivatezarrLocation

Privatenode

Private_onceInit

Privatearrays

Type Declaration

Optionalpositions?: Array<DataType, Readable>

Optionalcolors?: Array<DataType, Readable>

Optionalradii?: Array<DataType, Readable>

Optionalsharpness?: Array<DataType, Readable>

Optionalscalars?: Array<DataType, Readable>

PrivaterangeLoader

Private_accumulator

Private_accumulatorConfig

PrivatecolorComponents

Private Readonlyevents

Private Readonlymetrics

Private ReadonlyactiveQueries

PrivatenextQueryId

Private ReadonlyfacadeCtx

PrivatetotalQueryCells

PrivatezarrStore

Privatel0Cache

Private_activeProbe

Private_activeSignal

Privateprefetcher

PrivatesliceCache

Private_initialLoadDone

Accessors

Privateattrs

Returns PointsMetadata

Methods

PrivateregisterBounds

Parameters

Returns void

initialize

Returns Promise<void>

loadPoints

Parameters

Returns Promise<LoadedPointsData>

PrivateloadPointsInternal

Parameters

Returns Promise<LoadedPointsData>

updateView

Parameters

Returns Promise<LoadedPointsData>

updateViewWithResidency

Parameters

Returns Promise<{ data: LoadedPointsData; allResident: boolean }>

prefetchChunks

Parameters

Returns Promise<void>

prefetchChunkBoundary

Parameters

Returns Promise<void>

PrivateprefetchArrays

Returns Array<DataType, Readable>[]

PrivatequeryVisiblePointRanges

Parameters

Returns Promise<PointRange[]>

PrivateallocateOutputBuffer

Parameters

Returns | Uint8Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Float16Array<ArrayBufferLike>

PrivateloadArrayRefRanges

Parameters

Returns Promise<number>

`Private`chunkIndex

`Private`totalPointsNoIndex

`Private`_effectiveRadiusConfig

`Private`zarrLocation

`Private`node

`Private`_onceInit

`Private`arrays

`Optional`positions?: Array<DataType, Readable>

`Optional`colors?: Array<DataType, Readable>

`Optional`radii?: Array<DataType, Readable>

`Optional`sharpness?: Array<DataType, Readable>

`Optional`scalars?: Array<DataType, Readable>

`Private`rangeLoader

`Private`_accumulator

`Private`_accumulatorConfig

`Private`colorComponents

`Private` `Readonly`events

`Private` `Readonly`metrics

`Private` `Readonly`activeQueries

`Private`nextQueryId

`Private` `Readonly`facadeCtx

`Private`totalQueryCells

`Private`zarrStore

`Private`l0Cache

`Private`_activeProbe

`Private`_activeSignal

`Private`prefetcher

`Private`sliceCache

`Private`_initialLoadDone

`Private`attrs

`Private`registerBounds

`Private`loadPointsInternal

`Private`prefetchArrays

`Private`queryVisiblePointRanges

`Private`allocateOutputBuffer

Returns
| Uint8Array<ArrayBufferLike>
| Float32Array<ArrayBufferLike>
| Uint16Array<ArrayBufferLike>
| Float16Array<ArrayBufferLike>

`Private`loadArrayRefRanges

`Private`loadColorRanges

Returns Promise<
| Uint8Array<ArrayBufferLike>
| Float32Array<ArrayBufferLike>
| Uint16Array<ArrayBufferLike>
| null,
>

`Private`loadRanges

Returns Promise<
| Uint8Array<ArrayBufferLike>
| Float32Array<ArrayBufferLike>
| Uint16Array<ArrayBufferLike>
| Float16Array<ArrayBufferLike>
| null,
>

`Private`buildProjectionContext

`Private`projectTo3D

`Private`createEmptyPointsData

`Private`emitEvent

`Private`loadSpatialExtendDimsFromSceneDimensions