gaussian-splat-lite 1.2.2 → 1.3.1

package/dist/types/loaders/stream/sog-stream/SogStreamScheduler.d.cts

@@ -1,86 +1,107 @@
-import { StreamSchedulerOptions, StreamStats } from '../streamOptions.cjs';
-import { SogStreamLoaderOptions } from './SogStreamLoader.cjs';
-import * as THREE from "three";
-export type SogStreamSchedulerOptions = SogStreamLoaderOptions & StreamSchedulerOptions;
+import type * as THREE from "three";
+import type { StreamSchedulerOptions, StreamStats } from "../streamOptions.cjs";
+import type { SogStreamLoaderOptions } from "./SogStreamLoader.cjs";
+import type { SogBudgetMode } from "./sogLod.cjs";
+export type SogStreamSchedulerOptions = SogStreamLoaderOptions &
+  StreamSchedulerOptions & {
+    /** Defaults to "target". "limit" caps detail at the configured distance bands. */
+    splatBudgetMode?: SogBudgetMode;
+    /** Base LOD distance in world units for "limit" mode; defaults to 100. Must be finite and positive. */
+    lodBaseDistance?: number;
+    /** Distance multiplier between LOD levels in both modes; defaults to 2. Must be finite and at least 1. */
+    lodMultiplier?: number;
+  };
 export type SogStreamStats = StreamStats & {
-    visibleRegions: number;
+  visibleRegions: number;
 };
 /** Camera-driven Streamed SOG loading with per-chunk sources and region fades. */
 export declare class SogStreamScheduler {
-    readonly group: THREE.Group;
-    readonly initialized: Promise<this>;
-    readonly firstRenderable: Promise<this>;
-    readonly cooldownMs: number;
-    readonly fadeDurationMs: number;
-    readonly maxConcurrentLoads: number;
-    private _splatBudget;
-    private readonly options;
-    private readonly loader;
-    private readonly abort;
-    private readonly streamCameras;
-    private manifest?;
-    private readonly lodLeaves;
-    private view?;
-    private lastRequestedKey;
-    private selecting;
-    private selection;
-    private chunks;
-    /** Chunks with a batch, cached source or in-flight load. */
-    private readonly activeChunks;
-    private environment?;
-    private leaves;
-    private wanted;
-    private readonly fades;
-    private shown;
-    private disposed;
-    private resolveFirst;
-    private rejectFirst;
-    constructor(options: SogStreamSchedulerOptions);
-    /** Visible-point target, including the environment. Reassign to reselect LODs. */
-    get splatBudget(): number;
-    set splatBudget(value: number);
-    get stats(): SogStreamStats;
-    /** Group-local bounds from the index; available after initialized resolves. */
-    getBoundingBox(): THREE.Box3;
-    private initialize;
-    /** Cameras that select detail, in registration order. */
-    get cameras(): readonly THREE.Camera[];
-    hasCamera(camera: THREE.Camera): boolean;
-    /**
-     * Select detail for this camera on each update. Detail follows distance,
-     * so it needs no resolution. For WebXR register renderer.xr.getCamera(): it
-     * selects the greatest detail needed by any eye that sees the region. Returns whether the camera was
-     * newly added.
-     */
-    setCamera(camera: THREE.Camera): boolean;
-    /** Stop selecting detail for this camera. Returns whether it was registered. */
-    deleteCamera(camera: THREE.Camera): boolean;
-    /**
-     * Call before rendering. Returns whether the displayed data changed. Each
-     * leaf uses the distance of the nearest registered camera that sees it.
-     */
-    update(): boolean;
-    private requestSelection;
-    private updateRequests;
-    private selectRegions;
-    private leafState;
-    private chunkFor;
-    private applySelection;
-    private updateRegionVisibility;
-    private attachPendingRegions;
-    private queueExtractions;
-    private addBatchRange;
-    private fadeRegion;
-    private updateFades;
-    private extract;
-    private releaseUnused;
-    private pump;
-    private load;
-    private pruneChunk;
-    private releaseRegion;
-    private changed;
-    private failed;
-    private readonly retryTimer;
-    private rejectFirstIfUnavailable;
-    dispose(): void;
+  readonly group: THREE.Group;
+  readonly initialized: Promise<this>;
+  readonly firstRenderable: Promise<this>;
+  readonly cooldownMs: number;
+  readonly fadeDurationMs: number;
+  readonly maxConcurrentLoads: number;
+  private _splatBudget;
+  private _splatBudgetMode;
+  private _lodBaseDistance;
+  private _lodMultiplier;
+  private readonly options;
+  private readonly loader;
+  private readonly abort;
+  private readonly streamCameras;
+  private manifest?;
+  private readonly lodLeaves;
+  private view?;
+  private lastRequestedKey;
+  private selecting;
+  private selection;
+  private chunks;
+  /** Chunks with a batch, cached source or in-flight load. */
+  private readonly activeChunks;
+  private environment?;
+  private leaves;
+  private wanted;
+  private readonly fades;
+  private shown;
+  private disposed;
+  private resolveFirst;
+  private rejectFirst;
+  constructor(options: SogStreamSchedulerOptions);
+  /** Visible-point budget, including the environment. Reassign to reselect LODs. */
+  get splatBudget(): number;
+  set splatBudget(value: number);
+  /** Fill the budget, or limit detail to the configured distance bands. */
+  get splatBudgetMode(): SogBudgetMode;
+  set splatBudgetMode(value: SogBudgetMode);
+  /** Base LOD distance in world units for limit mode. Higher retains more detail. */
+  get lodBaseDistance(): number;
+  set lodBaseDistance(value: number);
+  /** Distance multiplier between LOD levels; affects both budget modes. */
+  get lodMultiplier(): number;
+  set lodMultiplier(value: number);
+  get stats(): SogStreamStats;
+  /** Group-local bounds from the index; available after initialized resolves. */
+  getBoundingBox(): THREE.Box3;
+  private initialize;
+  /** Cameras that select detail, in registration order. */
+  get cameras(): readonly THREE.Camera[];
+  hasCamera(camera: THREE.Camera): boolean;
+  /**
+   * Select detail for this camera on each update. Detail follows distance,
+   * so it needs no resolution. For WebXR register renderer.xr.getCamera(): it
+   * selects the greatest detail needed by any eye that sees the region. Returns whether the camera was
+   * newly added.
+   */
+  setCamera(camera: THREE.Camera): boolean;
+  /** Stop selecting detail for this camera. Returns whether it was registered. */
+  deleteCamera(camera: THREE.Camera): boolean;
+  /**
+   * Call before rendering. Returns whether the displayed data changed. Each
+   * leaf uses the distance of the nearest registered camera that sees it.
+   */
+  update(): boolean;
+  private requestSelection;
+  private updateRequests;
+  private selectRegions;
+  private leafState;
+  private chunkFor;
+  private applySelection;
+  private updateRegionVisibility;
+  private attachPendingRegions;
+  private queueExtractions;
+  private addBatchRange;
+  private fadeRegion;
+  private updateFades;
+  private extract;
+  private releaseUnused;
+  private pump;
+  private load;
+  private pruneChunk;
+  private releaseRegion;
+  private changed;
+  private failed;
+  private readonly retryTimer;
+  private rejectFirstIfUnavailable;
+  dispose(): void;
 }

package/dist/types/loaders/stream/sog-stream/SogStreamScheduler.d.ts

@@ -1,86 +1,107 @@
-import { StreamSchedulerOptions, StreamStats } from '../streamOptions';
-import { SogStreamLoaderOptions } from './SogStreamLoader';
-import * as THREE from "three";
-export type SogStreamSchedulerOptions = SogStreamLoaderOptions & StreamSchedulerOptions;
+import type * as THREE from "three";
+import type { StreamSchedulerOptions, StreamStats } from "../streamOptions.js";
+import type { SogStreamLoaderOptions } from "./SogStreamLoader.js";
+import type { SogBudgetMode } from "./sogLod.js";
+export type SogStreamSchedulerOptions = SogStreamLoaderOptions &
+  StreamSchedulerOptions & {
+    /** Defaults to "target". "limit" caps detail at the configured distance bands. */
+    splatBudgetMode?: SogBudgetMode;
+    /** Base LOD distance in world units for "limit" mode; defaults to 100. Must be finite and positive. */
+    lodBaseDistance?: number;
+    /** Distance multiplier between LOD levels in both modes; defaults to 2. Must be finite and at least 1. */
+    lodMultiplier?: number;
+  };
 export type SogStreamStats = StreamStats & {
-    visibleRegions: number;
+  visibleRegions: number;
 };
 /** Camera-driven Streamed SOG loading with per-chunk sources and region fades. */
 export declare class SogStreamScheduler {
-    readonly group: THREE.Group;
-    readonly initialized: Promise<this>;
-    readonly firstRenderable: Promise<this>;
-    readonly cooldownMs: number;
-    readonly fadeDurationMs: number;
-    readonly maxConcurrentLoads: number;
-    private _splatBudget;
-    private readonly options;
-    private readonly loader;
-    private readonly abort;
-    private readonly streamCameras;
-    private manifest?;
-    private readonly lodLeaves;
-    private view?;
-    private lastRequestedKey;
-    private selecting;
-    private selection;
-    private chunks;
-    /** Chunks with a batch, cached source or in-flight load. */
-    private readonly activeChunks;
-    private environment?;
-    private leaves;
-    private wanted;
-    private readonly fades;
-    private shown;
-    private disposed;
-    private resolveFirst;
-    private rejectFirst;
-    constructor(options: SogStreamSchedulerOptions);
-    /** Visible-point target, including the environment. Reassign to reselect LODs. */
-    get splatBudget(): number;
-    set splatBudget(value: number);
-    get stats(): SogStreamStats;
-    /** Group-local bounds from the index; available after initialized resolves. */
-    getBoundingBox(): THREE.Box3;
-    private initialize;
-    /** Cameras that select detail, in registration order. */
-    get cameras(): readonly THREE.Camera[];
-    hasCamera(camera: THREE.Camera): boolean;
-    /**
-     * Select detail for this camera on each update. Detail follows distance,
-     * so it needs no resolution. For WebXR register renderer.xr.getCamera(): it
-     * selects the greatest detail needed by any eye that sees the region. Returns whether the camera was
-     * newly added.
-     */
-    setCamera(camera: THREE.Camera): boolean;
-    /** Stop selecting detail for this camera. Returns whether it was registered. */
-    deleteCamera(camera: THREE.Camera): boolean;
-    /**
-     * Call before rendering. Returns whether the displayed data changed. Each
-     * leaf uses the distance of the nearest registered camera that sees it.
-     */
-    update(): boolean;
-    private requestSelection;
-    private updateRequests;
-    private selectRegions;
-    private leafState;
-    private chunkFor;
-    private applySelection;
-    private updateRegionVisibility;
-    private attachPendingRegions;
-    private queueExtractions;
-    private addBatchRange;
-    private fadeRegion;
-    private updateFades;
-    private extract;
-    private releaseUnused;
-    private pump;
-    private load;
-    private pruneChunk;
-    private releaseRegion;
-    private changed;
-    private failed;
-    private readonly retryTimer;
-    private rejectFirstIfUnavailable;
-    dispose(): void;
+  readonly group: THREE.Group;
+  readonly initialized: Promise<this>;
+  readonly firstRenderable: Promise<this>;
+  readonly cooldownMs: number;
+  readonly fadeDurationMs: number;
+  readonly maxConcurrentLoads: number;
+  private _splatBudget;
+  private _splatBudgetMode;
+  private _lodBaseDistance;
+  private _lodMultiplier;
+  private readonly options;
+  private readonly loader;
+  private readonly abort;
+  private readonly streamCameras;
+  private manifest?;
+  private readonly lodLeaves;
+  private view?;
+  private lastRequestedKey;
+  private selecting;
+  private selection;
+  private chunks;
+  /** Chunks with a batch, cached source or in-flight load. */
+  private readonly activeChunks;
+  private environment?;
+  private leaves;
+  private wanted;
+  private readonly fades;
+  private shown;
+  private disposed;
+  private resolveFirst;
+  private rejectFirst;
+  constructor(options: SogStreamSchedulerOptions);
+  /** Visible-point budget, including the environment. Reassign to reselect LODs. */
+  get splatBudget(): number;
+  set splatBudget(value: number);
+  /** Fill the budget, or limit detail to the configured distance bands. */
+  get splatBudgetMode(): SogBudgetMode;
+  set splatBudgetMode(value: SogBudgetMode);
+  /** Base LOD distance in world units for limit mode. Higher retains more detail. */
+  get lodBaseDistance(): number;
+  set lodBaseDistance(value: number);
+  /** Distance multiplier between LOD levels; affects both budget modes. */
+  get lodMultiplier(): number;
+  set lodMultiplier(value: number);
+  get stats(): SogStreamStats;
+  /** Group-local bounds from the index; available after initialized resolves. */
+  getBoundingBox(): THREE.Box3;
+  private initialize;
+  /** Cameras that select detail, in registration order. */
+  get cameras(): readonly THREE.Camera[];
+  hasCamera(camera: THREE.Camera): boolean;
+  /**
+   * Select detail for this camera on each update. Detail follows distance,
+   * so it needs no resolution. For WebXR register renderer.xr.getCamera(): it
+   * selects the greatest detail needed by any eye that sees the region. Returns whether the camera was
+   * newly added.
+   */
+  setCamera(camera: THREE.Camera): boolean;
+  /** Stop selecting detail for this camera. Returns whether it was registered. */
+  deleteCamera(camera: THREE.Camera): boolean;
+  /**
+   * Call before rendering. Returns whether the displayed data changed. Each
+   * leaf uses the distance of the nearest registered camera that sees it.
+   */
+  update(): boolean;
+  private requestSelection;
+  private updateRequests;
+  private selectRegions;
+  private leafState;
+  private chunkFor;
+  private applySelection;
+  private updateRegionVisibility;
+  private attachPendingRegions;
+  private queueExtractions;
+  private addBatchRange;
+  private fadeRegion;
+  private updateFades;
+  private extract;
+  private releaseUnused;
+  private pump;
+  private load;
+  private pruneChunk;
+  private releaseRegion;
+  private changed;
+  private failed;
+  private readonly retryTimer;
+  private rejectFirstIfUnavailable;
+  dispose(): void;
 }

package/dist/types/loaders/stream/sog-stream/SogStreamWorker.d.cts

@@ -1,6 +1,6 @@
-import { WorkerRpc } from '../../../runtime/WorkerRpc.cjs';
-import { SogStreamRpcHandlers } from './worker.cjs';
+import { WorkerRpc } from "../../../runtime/WorkerRpc.cjs";
+import type { SogStreamRpcHandlers } from "./worker.cjs";
 /** Worker assigned either LOD traversal or retained chunk decoding. */
 export declare class SogStreamWorker extends WorkerRpc<SogStreamRpcHandlers> {
-    constructor(onDispose?: () => void);
+  constructor(onDispose?: () => void);
 }

package/dist/types/loaders/stream/sog-stream/SogStreamWorker.d.ts

@@ -1,6 +1,6 @@
-import { WorkerRpc } from '../../../runtime/WorkerRpc';
-import { SogStreamRpcHandlers } from './worker';
+import { WorkerRpc } from "../../../runtime/WorkerRpc.js";
+import type { SogStreamRpcHandlers } from "./worker.js";
 /** Worker assigned either LOD traversal or retained chunk decoding. */
 export declare class SogStreamWorker extends WorkerRpc<SogStreamRpcHandlers> {
-    constructor(onDispose?: () => void);
+  constructor(onDispose?: () => void);
 }

package/dist/types/loaders/stream/sog-stream/sogLod.d.cts

@@ -1,70 +1,91 @@
-import { Box3 } from 'three';
+import type { Box3 } from "three";
 export type SogLodRange = {
-    leaf: number;
-    level: number;
-    /** -1 for an empty LOD, which has no backing file. */
-    file: number;
-    offset: number;
-    count: number;
+  leaf: number;
+  level: number;
+  /** -1 for an empty LOD, which has no backing file. */
+  file: number;
+  offset: number;
+  count: number;
 };
 export type SogLodLeaf = {
-    id: number;
-    /** Coarse to fine, with strictly increasing counts and decreasing levels. */
-    lods: SogLodRange[];
+  id: number;
+  /** Coarse to fine, with strictly decreasing levels. */
+  lods: SogLodRange[];
 };
 export type SogLodNode = {
-    bound: Box3;
-    children?: SogLodNode[];
-    leaf?: SogLodLeaf;
+  bound: Box3;
+  children?: SogLodNode[];
+  leaf?: SogLodLeaf;
 };
 export type SogLodFile = {
-    url: string;
-    count: number;
-    ranges: SogLodRange[];
+  url: string;
+  count: number;
+  ranges: SogLodRange[];
 };
 export type SogLodManifest = {
-    tree: SogLodNode;
-    leaves: SogLodLeaf[];
-    /** Flattened in leaf/LOD order; each leaf's first entry is unused. */
-    upgradeRatios: number[];
-    files: SogLodFile[];
-    environment?: string;
+  tree: SogLodNode;
+  leaves: SogLodLeaf[];
+  lodLevels: number;
+  files: SogLodFile[];
+  environment?: string;
 };
 export declare const SOG_LOD_STRIDE = 4;
 /** Packed worker index. Float64 preserves source bounds and safe-integer counts. */
 export type SogLodIndex = {
-    /** Preorder nodes: min XYZ, max XYZ, next index after the subtree, leaf ID (-1 for interiors). */
-    nodes: Float64Array;
-    leafOffsets: Uint32Array;
-    /** Per level: level, file, offset, count. */
-    lods: Float64Array;
-    /** Best reachable distance-error reduction per added splat, in LOD order. */
-    upgradeRatios: Float32Array;
-    urls: string[];
-    counts: Float64Array;
-    environment?: string;
+  /** Preorder nodes: min XYZ, max XYZ, next index after the subtree, leaf ID (-1 for interiors). */
+  nodes: Float64Array;
+  leafOffsets: Uint32Array;
+  /** Per level: level, file, offset, count. */
+  lods: Float64Array;
+  lodLevels: number;
+  urls: string[];
+  counts: Float64Array;
+  environment?: string;
 };
 /** Scheduler metadata; the complete spatial tree stays in the LOD worker. */
-export type SogLodMetadata = Omit<SogLodIndex, "nodes" | "upgradeRatios"> & {
-    /** Root min XYZ and max XYZ. */
-    bounds: Float64Array;
+export type SogLodMetadata = Omit<SogLodIndex, "nodes" | "lodLevels"> & {
+  /** Root min XYZ and max XYZ. */
+  bounds: Float64Array;
 };
 /** Flatten the tree and ranges into transferable typed arrays. */
 export declare function packSogLodIndex(manifest: SogLodManifest): SogLodIndex;
 /** Materialize only leaves visited by the camera, preserving stable range identities. */
-export declare function readSogLodLeaf(index: Pick<SogLodIndex, "leafOffsets" | "lods">, id: number): SogLodLeaf;
+export declare function readSogLodLeaf(
+  index: Pick<SogLodIndex, "leafOffsets" | "lods">,
+  id: number,
+): SogLodLeaf;
 /** Streamed SOG v1, including the earlier unversioned manifests. */
-export declare function parseSogLodManifest(value: unknown, baseUrl: string): SogLodManifest;
+export declare function parseSogLodManifest(
+  value: unknown,
+  baseUrl: string,
+): SogLodManifest;
 export type SogVisibleLeaf = {
-    leaf: SogLodLeaf;
-    weight: number;
+  leaf: SogLodLeaf;
+  /** World-space distance to the region, compensated for the camera's field of view. */
+  distance: number;
+};
+export type SogBudgetMode = "target" | "limit";
+export type SogLodOptions = {
+  budget: number;
+  splatBudgetMode: SogBudgetMode;
+  lodBaseDistance: number;
+  lodMultiplier: number;
 };
 /** Reuse cached refinements up to the target, then split gaps of four or more. */
-export declare function resolveSogLod(leaf: SogLodLeaf, target: SogLodRange, current: SogLodRange | undefined, isLoaded: (range: SogLodRange) => boolean): {
-    range: SogLodRange | undefined;
-    load?: SogLodRange;
-    /** Wait until range is attached before requesting the next LOD. */
-    refinement?: boolean;
+export declare function resolveSogLod(
+  leaf: SogLodLeaf,
+  target: SogLodRange,
+  current: SogLodRange | undefined,
+  isLoaded: (range: SogLodRange) => boolean,
+): {
+  range: SogLodRange | undefined;
+  load?: SogLodRange;
+  /** Wait until range is attached before requesting the next LOD. */
+  refinement?: boolean;
 };
-/** Distance bands within a splat budget, using a small heap. */
-export declare function selectSogLods(visible: SogVisibleLeaf[], budget: number, manifest: Pick<SogLodIndex, "leafOffsets" | "upgradeRatios">): Map<number, SogLodRange>;
+/** Select distance bands, fitting their common base distance to the splat budget. */
+export declare function selectSogLods(
+  visible: SogVisibleLeaf[],
+  lodLevels: number,
+  options: SogLodOptions,
+): Map<number, SogLodRange>;