@nebula-spatial/cad-loader 0.1.0

package/dist/core/parser/bin-group-reader.d.ts

@@ -0,0 +1,9 @@
+import type { GeoGeometryChunk, GroupLayerEncoding, InsertRuntimeGeometry } from './types';
+export declare const STREAM_VERTEX_WINDOW = 4096;
+export declare function captureGroupSnapshot(buf: ArrayBuffer, startOffset: number, endOffset: number, count: number, groupLayerEncoding?: GroupLayerEncoding): InsertRuntimeGeometry;
+export declare function groupLayerEncodingForV3Minor(versionMinor: number): GroupLayerEncoding;
+export declare function readGroup(buf: ArrayBuffer, view: DataView, startOffset: number, count: number, endOffset?: number, groupLayerEncoding?: GroupLayerEncoding): {
+    chunk: GeoGeometryChunk;
+    offset: number;
+};
+export declare function streamGroupChunks(buf: ArrayBuffer, view: DataView, startOffset: number, count: number, groupLayerEncoding?: GroupLayerEncoding): Generator<GeoGeometryChunk, number, void>;

package/dist/core/parser/bin-parser.d.ts

@@ -0,0 +1,65 @@
+import type { BlockInstanceBBox, ExternalAnnotationsManifest, ExternalBlockVariantManifestEntry, GeoMeta, GeoGroup } from '../types';
+import type { GeoChunk, GeoGeometryChunk, GroupLayerEncoding, ParsedHeader, InsertRuntimeGeometry } from './types';
+import { type DecodedAnnotationSidecar } from './dxbs-sidecar';
+export type ParseBinOptions = {
+    hiddenInstanceIds?: ReadonlySet<number>;
+    keepTextsForHiddenInstances?: boolean;
+    loadBlocks?: boolean;
+    suppressExpandedInsertGeometry?: boolean;
+    maxExpandedInstanceVertices?: number;
+    externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
+    requiredExternalVariantIds?: ReadonlySet<number>;
+    externalVariantDeltaOnly?: boolean;
+    deferExternalVariantGeometry?: boolean;
+};
+export interface ExternalVariantDependencyPlan {
+    readonly manifest: readonly ExternalBlockVariantManifestEntry[];
+    readonly requiredVariantIds: readonly number[];
+    readonly requiredNormalBytes: number;
+    readonly totalManifestBytes: number;
+    readonly skippedVariantIds: readonly number[];
+    readonly viewport?: BlockInstanceBBox | null;
+    readonly includedSceneInstanceIds?: readonly number[];
+}
+export interface ExternalVariantDependencyOptions {
+    readonly loadBlocks?: boolean;
+    readonly hiddenInstanceIds?: ReadonlySet<number>;
+    readonly viewport?: BlockInstanceBBox | null;
+    readonly viewportPaddingRatio?: number;
+    readonly worldUnitsPerPixel?: number;
+    readonly minViewportPixelSize?: number;
+}
+export declare function readExternalVariantManifest(buf: ArrayBuffer): readonly ExternalBlockVariantManifestEntry[];
+export declare function readExternalVariantDependencyPlan(buf: ArrayBuffer, options?: ExternalVariantDependencyOptions): ExternalVariantDependencyPlan;
+export declare function readExternalAnnotationManifest(buf: ArrayBuffer): ExternalAnnotationsManifest | null;
+export declare function readExternalVariantGeometrySidecar(entry: ExternalBlockVariantManifestEntry, sidecar: ArrayBuffer, fallbackGroupLayerEncoding?: GroupLayerEncoding): {
+    line: {
+        chunk: GeoGeometryChunk;
+        snapshot: InsertRuntimeGeometry;
+    };
+    fill: {
+        chunk: GeoGeometryChunk;
+        snapshot: InsertRuntimeGeometry;
+    };
+    dot: {
+        chunk: GeoGeometryChunk;
+        snapshot: InsertRuntimeGeometry;
+    };
+};
+export declare function readExternalBlockAnnotations(buf: ArrayBuffer, options?: {
+    externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
+    hiddenInstanceIds?: ReadonlySet<number>;
+}): DecodedAnnotationSidecar | null;
+export declare function parseBinStreaming(buf: ArrayBuffer, options?: ParseBinOptions): {
+    header: ParsedHeader;
+    chunks: Generator<GeoChunk, void, void>;
+};
+export declare function parseBinBounds(buf: ArrayBuffer): ParsedHeader['bounds'];
+export declare function parseBinToChunks(buf: ArrayBuffer, options?: ParseBinOptions): Generator<GeoChunk, ParsedHeader, void>;
+export declare function parseBinPayload(buf: ArrayBuffer, options?: ParseBinOptions): {
+    meta: GeoMeta;
+    line: GeoGroup;
+    fill: GeoGroup;
+    dot: GeoGroup;
+    rawBytes: number;
+};

package/dist/core/parser/dxbs-sidecar.d.ts

@@ -0,0 +1,24 @@
+import type { TextEntity } from '../types';
+import type { GeoGeometryChunk } from './types';
+export type DxbsSectionEntry = {
+    type: number;
+    flags: number;
+    offset: number;
+    length: number;
+};
+export type DxbsContainer = {
+    versionMajor: number;
+    versionMinor: number;
+    sections: ReadonlyMap<number, DxbsSectionEntry>;
+};
+export declare function isDxbsPayload(buf: ArrayBuffer): boolean;
+export declare function readDxbsContainer(buf: ArrayBuffer): DxbsContainer;
+export declare function getDxbsSection(container: DxbsContainer, type: number, name: string): DxbsSectionEntry;
+export type DecodedAnnotationSidecar = {
+    line: GeoGeometryChunk;
+    fill: GeoGeometryChunk;
+    dot: GeoGeometryChunk;
+    texts: readonly TextEntity[];
+};
+export declare function readSceneAnnotationSidecar(buf: ArrayBuffer): DecodedAnnotationSidecar;
+export declare function readBlockAnnotationSidecar(buf: ArrayBuffer): DecodedAnnotationSidecar;

package/dist/core/parser/geometry-segments.d.ts

@@ -0,0 +1,20 @@
+import type { GeoGeometryChunk, GeoGeometrySegment } from './types';
+export interface GeometrySegmentSource {
+    readonly pos: Float32Array;
+    readonly col?: Uint8Array;
+    readonly lay?: Uint8Array | Uint16Array;
+    readonly count: number;
+    readonly segments?: readonly GeoGeometrySegment[];
+}
+export interface ExpandedGeometryMetadata {
+    /** Live references when expanded metadata already exists; newly allocated arrays when derived from segments. */
+    readonly col: Uint8Array;
+    readonly lay: Uint8Array | Uint16Array;
+}
+export declare function emptyGeometryChunk(): GeoGeometryChunk;
+export declare function normalizeGeometrySegments(chunk: GeometrySegmentSource): readonly GeoGeometrySegment[];
+export declare function expandGeometryChunkMetadata(chunk: GeometrySegmentSource): ExpandedGeometryMetadata;
+export declare function offsetGeometrySegments(segments: readonly GeoGeometrySegment[], vertexOffset: number): GeoGeometrySegment[];
+export declare function remapGeometrySegmentLayers(segments: readonly GeoGeometrySegment[], remap: (layerIndex: number) => number): GeoGeometrySegment[];
+export declare function sliceGeometrySegments(segments: readonly GeoGeometrySegment[], startVertex: number, vertexCount: number): GeoGeometrySegment[];
+export declare function mergeAdjacentSegments(segments: readonly GeoGeometrySegment[]): GeoGeometrySegment[];

package/dist/core/parser/text-roundtrip.d.ts

@@ -0,0 +1,4 @@
+import type { TextEntity } from '../types';
+export declare function isStrictTextRoundtripEnabled(): boolean;
+export declare function shouldAssertStrictTextRoundtrip(strictTextRoundtrip: boolean): strictTextRoundtrip is true;
+export declare function assertStrictTextRoundtrip(stage: string, expected: readonly TextEntity[], actual: readonly TextEntity[]): void;

package/dist/core/parser/types.d.ts

@@ -0,0 +1,80 @@
+import type { GeoMetaSnapshot, LayerBlockUsage, LayerSnapshot, TextEntity } from '../types';
+type ParsedHeaderCounts = Pick<GeoMetaSnapshot, 'entityCount' | 'lineCount' | 'fillCount' | 'dotCount' | 'textCount'>;
+export interface InsertRuntimeGeometry {
+    readonly count: number;
+    readonly raw: Uint8Array;
+    readonly groupLayerEncoding?: GroupLayerEncoding;
+}
+export interface InsertRuntimeVariant {
+    readonly id: number;
+    readonly blockName: string;
+    readonly line: InsertRuntimeGeometry;
+    readonly fill: InsertRuntimeGeometry;
+    readonly dot: InsertRuntimeGeometry;
+    readonly texts: readonly TextEntity[];
+}
+export interface InsertRuntimeInstance {
+    readonly instanceId: number;
+    readonly variantId: number;
+    readonly matA: number;
+    readonly matB: number;
+    readonly matC: number;
+    readonly matD: number;
+    readonly tx: number;
+    readonly ty: number;
+    readonly insLayerIdx: number;
+}
+export interface InsertRuntime {
+    readonly layer0Index: number;
+    readonly variants: readonly InsertRuntimeVariant[];
+    readonly instances: readonly InsertRuntimeInstance[];
+    readonly textIndexesByInstanceId: ReadonlyMap<number, readonly number[]>;
+    readonly ownerInstanceIdByVariantOrdinal?: ReadonlyMap<string, number>;
+}
+export interface ParsedHeader {
+    readonly bounds: GeoMetaSnapshot['bounds'];
+    readonly entityCount: ParsedHeaderCounts['entityCount'];
+    readonly lineCount: ParsedHeaderCounts['lineCount'];
+    readonly fillCount: ParsedHeaderCounts['fillCount'];
+    readonly dotCount: ParsedHeaderCounts['dotCount'];
+    readonly textCount: ParsedHeaderCounts['textCount'];
+    readonly layers: readonly LayerSnapshot[];
+    readonly texts: readonly TextEntity[];
+    readonly layerBlockUsages?: ReadonlyMap<number, readonly LayerBlockUsage[]>;
+    readonly insertRuntime?: InsertRuntime;
+    readonly promotedInsertInstanceIds?: readonly number[];
+}
+export interface GeoGeometrySegment {
+    readonly startVertex: number;
+    readonly vertexCount: number;
+    readonly color: readonly [number, number, number];
+    readonly layerIndex: number;
+    readonly lineweightPx?: number;
+}
+export interface GeoGeometryChunk {
+    readonly pos: Float32Array;
+    readonly col?: Uint8Array;
+    readonly lay?: Uint8Array | Uint16Array;
+    readonly count: number;
+    readonly segments?: readonly GeoGeometrySegment[];
+}
+export type GroupLayerEncoding = 'u8' | 'u16' | 'u8_lw' | 'u16_lw';
+export type GeoChunkKind = 'line' | 'fill' | 'dot' | 'text';
+export interface LineGeoChunk {
+    readonly kind: 'line';
+    readonly payload: GeoGeometryChunk;
+}
+export interface FillGeoChunk {
+    readonly kind: 'fill';
+    readonly payload: GeoGeometryChunk;
+}
+export interface DotGeoChunk {
+    readonly kind: 'dot';
+    readonly payload: GeoGeometryChunk;
+}
+export interface TextGeoChunk {
+    readonly kind: 'text';
+    readonly payload: TextEntity;
+}
+export type GeoChunk = LineGeoChunk | FillGeoChunk | DotGeoChunk | TextGeoChunk;
+export {};

package/dist/core/runtime-text-decoder.d.ts

@@ -0,0 +1,8 @@
+export interface RuntimeTextDecoder {
+    decode(input?: Uint8Array): string;
+}
+/**
+ * Resolve the standard Encoding API without importing DOM or Node typings.
+ * Browsers, Web Workers and supported Node runtimes all provide this global.
+ */
+export declare function createRuntimeTextDecoder(): RuntimeTextDecoder;

package/dist/core/types.d.ts

@@ -0,0 +1,147 @@
+export interface LayerMeta {
+    name: string;
+    color: [number, number, number];
+    lw_px: number;
+    visible?: boolean;
+}
+/** Axis-aligned renderer-neutral bounds: [minX, minY, maxX, maxY]. */
+export type CadBounds = readonly [number, number, number, number];
+export interface LayerSnapshot {
+    readonly index: number;
+    readonly name: string;
+    readonly color: readonly [number, number, number];
+    readonly lw_px: number;
+    readonly visible: boolean;
+}
+export interface TextEntity {
+    t: string;
+    x: number;
+    y: number;
+    h: number;
+    r: number;
+    c: [number, number, number];
+    li: number;
+    iv?: number;
+    io?: number;
+    ha: 'left' | 'center' | 'right';
+    va: 'top' | 'middle' | 'bottom' | 'alphabetic';
+    lh: number;
+    w?: number;
+    wf?: number;
+    mx?: true;
+    my?: true;
+}
+export interface BlockVariantMeta {
+    id: number;
+    line_count: number;
+    fill_count: number;
+    dot_count: number;
+    name?: string;
+    block_name?: string;
+    blockName?: string;
+}
+export interface ExternalGeometryStats {
+    line_count: number;
+    fill_count: number;
+    dot_count: number;
+    bbox: [number, number, number, number] | null;
+    own_bbox?: [number, number, number, number] | null;
+}
+export interface ExternalAnnotationStats extends ExternalGeometryStats {
+    text_count: number;
+}
+export type ExternalBlockVariantManifestEntry = {
+    id: number;
+    href: string;
+    raw_size: number;
+    line_count: number;
+    fill_count: number;
+    dot_count: number;
+} | {
+    id: number;
+    href: string;
+    raw_size: number;
+    normal: ExternalGeometryStats;
+    annotation: ExternalAnnotationStats;
+};
+export interface ExternalSceneAnnotationManifestEntry extends ExternalAnnotationStats {
+    href: string;
+    raw_size: number;
+}
+export interface ExternalAnnotationsManifest {
+    scene?: ExternalSceneAnnotationManifestEntry;
+}
+export interface GeoMetaFeatures {
+    has_external_variant_geometry?: boolean;
+    has_external_annotations?: boolean;
+    has_variant_texts_in_sidecar?: boolean;
+    [key: string]: unknown;
+}
+export interface BlockInstanceBBox {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface InsertUsage {
+    instanceId: number;
+    variantId: number;
+    label: string;
+    tx: number;
+    ty: number;
+    canHighlight: boolean;
+    bbox?: BlockInstanceBBox;
+}
+export interface LayerBlockUsage {
+    variantId: number;
+    blockName: string;
+    instanceCount: number;
+    bboxes: BlockInstanceBBox[];
+    inserts: InsertUsage[];
+}
+export interface GeoMeta {
+    bounds: [number, number, number, number];
+    entity_count: number;
+    line_count: number;
+    fill_count: number;
+    dot_count?: number;
+    version?: number;
+    version_minor?: number;
+    encoding?: string;
+    features?: GeoMetaFeatures;
+    external_variants?: ExternalBlockVariantManifestEntry[];
+    external_annotations?: ExternalAnnotationsManifest;
+    layer0_index?: number;
+    block_variants?: BlockVariantMeta[];
+    instance_count?: number;
+    layers: LayerMeta[];
+    texts: readonly TextEntity[];
+}
+export type PackEncoding = 'flat' | 'instanced' | 'nested_instanced' | 'nested_instanced_external' | 'nested_instanced_external_annotations';
+export interface GeoMetaSnapshot {
+    readonly bounds: readonly [number, number, number, number];
+    readonly entityCount: number;
+    readonly lineCount: number;
+    readonly fillCount: number;
+    readonly dotCount: number;
+    readonly textCount: number;
+}
+export interface GeoGroup {
+    pos: Float32Array;
+    col: Uint8Array;
+    lay: Uint8Array | Uint16Array;
+    count: number;
+}
+export interface ParsedGeoPayload {
+    meta: GeoMeta;
+    line: GeoGroup;
+    fill: GeoGroup;
+    dot: GeoGroup;
+    rawBytes: number;
+}
+export interface ViewportRect {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}

package/dist/core/utils/insert-bbox.d.ts

@@ -0,0 +1,10 @@
+import type { ViewportRect } from '../types';
+export interface InsertInstanceTransform {
+    readonly matA: number;
+    readonly matB: number;
+    readonly matC: number;
+    readonly matD: number;
+    readonly tx: number;
+    readonly ty: number;
+}
+export declare function transformBBoxByInstance(localBBox: ViewportRect | null, instance: InsertInstanceTransform): ViewportRect | null;

package/dist/core/utils/viewport-rect.d.ts

@@ -0,0 +1,21 @@
+import type { ViewportRect } from '../types';
+export interface ViewportRectTransform {
+    matA: number;
+    matB: number;
+    matC: number;
+    matD: number;
+    tx: number;
+    ty: number;
+}
+export declare function cloneViewportRect(rect: ViewportRect | null | undefined): ViewportRect | null;
+export declare function normalizeViewportRect(rect: ViewportRect | null | undefined): ViewportRect | null;
+export declare function mergeViewportRects(current: ViewportRect | null | undefined, next: ViewportRect | null | undefined): ViewportRect | null;
+export declare function viewportRectIntersects(a: ViewportRect, b: ViewportRect): boolean;
+export declare function viewportRectContains(outer: ViewportRect, inner: ViewportRect): boolean;
+export declare function viewportRectEquals(a: ViewportRect | null, b: ViewportRect | null): boolean;
+export declare function intersectViewportRects(a: ViewportRect, b: ViewportRect): ViewportRect | null;
+export declare function expandViewportRect(rect: ViewportRect, ratio: number): ViewportRect;
+export declare function computeViewportRectFromPositions(positions: ArrayLike<number>, count: number, stride: number, xOffset?: number, yOffset?: number): ViewportRect | null;
+export declare function transformViewportRect(rect: ViewportRect, transform: ViewportRectTransform): ViewportRect;
+export declare function viewportRectDiagonal(rect: ViewportRect): number;
+export declare function viewportRectCenterDistance(a: ViewportRect, b: ViewportRect): number;

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public CAD loading entry point.
+ *
+ * The package owns the complete browser loading lifecycle and returns a
+ * mountable Three.js GeoNode. Protocol-only consumers should import from
+ * `@nebula-spatial/cad-loader/core`.
+ */
+export { createLoadSession } from './session/load-session';
+export type { CadExternalVariantFetchSource, CadLoadErrorEvent, CadLoadEvent, CadLoadFlowControlOptions, CadLoadGeometryEvent, CadLoadInsertEvent, CadLoadMetaEvent, CadLoadReadyEvent, CadLoadSession, CadLoadSessionOptions, CadLoadSource, CadLoadTextEvent, CadLoadVariantGeometry, CadLoadVariantGeometryChunk, CadLoadVariantRequestEvent, } from './session/load-session';
+export { appendExternalVariantDeltaToGeoNode, assertValidSourceOrThrow, loadExternalVariantDeltaFromBuffer, loadGeo, normalizeGeoError, parseBuffer, parseBufferBounds, parseBufferHeader, readBufferExternalAnnotationManifest, readBufferExternalBlockAnnotations, readBufferExternalVariantDependencyPlan, readBufferExternalVariantManifest, } from './loader/geo-loader';
+export type { ExternalVariantDependencyOptions, ExternalVariantDependencyPlan, ExternalVariantFetchSource, LoadExternalVariantDeltaFetchSourceOptions, LoadExternalVariantDeltaOptions, LoadGeoOptions, } from './loader/geo-loader';
+export { GEO_NODE_STRUCTURE_CHANGE, GEO_NODE_VISUAL_CHANGE, GeoNode, } from './loader/internal/geo-node';
+export type { ColorPipelineStatsSnapshot, GeoNodeInternalChange, GeoNodeInternalChangeKind, InsertInstanceMatrix2D, } from './loader/internal/geo-node';
+export type { LineMemoryStatsSnapshot, LineCanonicalMemoryStats, } from './loader/internal/line-canonical';
+export { readBlockAnnotationSidecar, readSceneAnnotationSidecar, } from './core';
+export type { DecodedAnnotationSidecar, DxbsContainer, DxbsSectionEntry, ParsedHeader, } from './core';
+export type { BlockInstanceBBox, BlockVariantMeta, ExternalAnnotationsManifest, ExternalAnnotationStats, ExternalBlockVariantManifestEntry, ExternalGeometryStats, ExternalSceneAnnotationManifestEntry, GeoGroup, GeoMeta, GeoMetaFeatures, GeoMetaSnapshot, GeoLoadSource, InsertUsage, LayerBlockUsage, LayerMeta, LayerSnapshot, LayerVertexChunk, LayerVertexStat, LineRenderMode, PackEncoding, ParsedGeoPayload, RenderDebugBreakdownEntry, SceneStats, SplitBlockLayerDetail, TextEntity, ViewportRect, } from './shared/types';
+export { expandViewportRect, mergeViewportRects, viewportRectContains, viewportRectIntersects, } from './shared/utils/viewport-rect';
+export { transformBBoxByInstance } from './shared/utils/insert-bbox';
+export type { InsertInstanceTransform } from './shared/utils/insert-bbox';
+export { GeoLoaderError } from './shared/errors';
+export type { ResolveTextFont, ResolvedTextFont } from './shared/text-font';
+export type { BlockGeometryKind, VariantGeometry, } from './scene/instancing/block-geometry-registry';
+export type { InsertInstanceRecord } from './scene/instancing/insert-instance-table';
+export { cadInsertSelectionEquals, pickCadInsertAtPoint, resolveCadInsertDetails, } from './selection/cad-insert-selection';
+export type { CadInsertDetails, CadInsertPickOptions, CadInsertSelectionId, CadPoint2D, } from './selection/cad-insert-selection';