@ifc-lite/spatial

@ifc-lite/spatial

Spatial indexing for IFClite. Builds a BVH (Bounding Volume Hierarchy) over your meshes and serves three query primitives: AABB intersection, raycast, and frustum culling.

Installation

npm install @ifc-lite/spatial

Build an index

import { buildSpatialIndex } from '@ifc-lite/spatial';

const index = buildSpatialIndex(meshes); // MeshData[] from @ifc-lite/geometry

// For very large models (50K+ meshes), use the time-sliced builder:
// it yields to the event loop between chunks so the UI stays responsive.
import { buildSpatialIndexAsync } from '@ifc-lite/spatial';
const indexAsync = await buildSpatialIndexAsync(meshes);

Raycast (entity picking)

const origin: [number, number, number] = [0, 5, 10];
const direction: [number, number, number] = [0, -1, 0];

const hits = index.raycast(origin, direction);
// → expressIds of meshes the ray intersects, in hit order

if (hits.length > 0) {
  console.log(`First hit: expressId ${hits[0]}`);
}

AABB query (region select)

const region = {
  min: [-5, 0, -5],
  max: [5, 3, 5],
} as const;

const hits = index.queryAABB(region);
// → expressIds of every mesh whose bounds intersect the box

console.log(`${hits.length} entities in region`);

Frustum culling

import { FrustumUtils } from '@ifc-lite/spatial';

// Build a frustum from a view-projection matrix (column-major 4×4)
const frustum = FrustumUtils.fromViewProjMatrix(viewProjMatrix);

const visible = index.queryFrustum(frustum);
// → expressIds visible to the camera; renderer only draws these

When to use this

The renderer (@ifc-lite/renderer) ships its own GPU-side picking and culling — for typical use you don't need this package directly. Reach for @ifc-lite/spatial when you're:

• Building a custom renderer (Three.js, Babylon.js, custom WebGPU)
• Running CPU-side raycasts for measurements / snapping / hit-tests outside the GPU pipeline
• Doing offline analysis (e.g. server-side intersection tests)

API

See the API Reference.

License

MPL-2.0