@ifc-lite/wasm 1.16.6 → 1.16.8

package/README.md

@@ -1,356 +1,142 @@
-<table align="center">
-<tr>
-<td valign="top">
-<img src="https://readme-typing-svg.herokuapp.com?font=JetBrains+Mono&weight=700&size=48&duration=2000&pause=5000&color=FFFFFF&vCenter=true&width=300&height=55&lines=IFClite" alt="IFClite">
-<br>
-<code>Fast</code> · <code>Lightweight</code> · <code>Columnar</code> · <code>Browser-native</code>
-</td>
-<td width="120" align="center" valign="middle">
-<img src="docs/assets/logo.png" alt="" width="100">
-</td>
-</tr>
-</table>
-
-<p align="center">
-  <a href="https://www.ifclite.com/"><img src="https://img.shields.io/badge/🚀_Try_it_Live-ifclite.com-ff6b6b?style=for-the-badge&labelColor=1a1a2e" alt="Try it Live"></a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/louistrue/ifc-lite/actions"><img src="https://img.shields.io/github/actions/workflow/status/louistrue/ifc-lite/release.yml?branch=main&style=flat-square&logo=github" alt="Build Status"></a>
-  <a href="https://github.com/louistrue/ifc-lite/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue?style=flat-square" alt="License"></a>
-  <a href="https://www.npmjs.com/package/@ifc-lite/parser"><img src="https://img.shields.io/npm/v/@ifc-lite/parser?style=flat-square&logo=npm&label=parser" alt="npm parser"></a>
-  <a href="https://crates.io/crates/ifc-lite-core"><img src="https://img.shields.io/crates/v/ifc-lite-core?style=flat-square&logo=rust&label=core" alt="crates.io"></a>
-</p>
-
-<p align="center">
-  <a href="#features">Features</a> · 
-  <a href="#quick-start">Quick Start</a> · 
-  <a href="#documentation">Documentation</a> · 
-  <a href="#architecture">Architecture</a> · 
-  <a href="#performance">Performance</a> · 
-  <a href="#contributing">Contributing</a>
-</p>
-
----
-
-## Overview
-
-**IFClite** parses, processes, and renders IFC files in the browser using **Rust + WebAssembly** and **WebGPU**. Smaller and faster than the alternatives.
-
-<p align="center">
-  <strong>~650 KB WASM (~260 KB gzipped)</strong> &nbsp;•&nbsp; <strong>2.6x faster</strong> &nbsp;•&nbsp; <strong>100% IFC4X3 schema (876 entities)</strong>
-</p>
-
-## Features
-
-| Feature | Description |
-|---------|-------------|
-| **Clean DX** | Columnar data structures, TypedArrays, consistent API. Built from scratch for clarity |
-| **STEP/IFC Parsing** | Zero-copy tokenization with full IFC4X3 schema support (876 entities) |
-| **Streaming Pipeline** | Progressive geometry processing. First triangles in 300-500ms |
-| **WebGPU Rendering** | Modern GPU-accelerated 3D with depth testing and frustum culling |
-| **Zero-Copy GPU** | Direct WASM memory to GPU buffers, 60-70% less RAM |
-
-## Quick Start
-
-### Option 1: Create a New Project (Recommended)
-
-Get started instantly without cloning the repo:
+# @ifc-lite/wasm
 
-```bash
-npx create-ifc-lite my-ifc-app
-cd my-ifc-app
-npm install && npm run parse
-```
-
-Or create a React viewer:
-
-```bash
-npx create-ifc-lite my-viewer --template react
-cd my-viewer
-npm install && npm run dev
-```
+Pre-built WebAssembly bindings for the IFClite Rust core. ~650 KB binary (~260 KB gzipped) covering STEP parsing, geometry tessellation, georeferencing, and zero-copy GPU upload.
 
-### Option 2: Install Packages Directly
+> **You probably don't need to use this package directly.** It's the WASM binary plus generated JS/TypeScript bindings that `@ifc-lite/parser`, `@ifc-lite/geometry`, and `@ifc-lite/renderer` consume internally. Reach for it when you want raw access to the Rust core without the higher-level wrappers.
 
-Add IFClite to your existing project:
+## Installation
 
 ```bash
-npm install @ifc-lite/parser
+npm install @ifc-lite/wasm
 ```
 
-```typescript
-import { IfcParser } from '@ifc-lite/parser';
+## Direct WASM use
 
-const parser = new IfcParser();
-const result = parser.parse(ifcBuffer);
+`IfcAPI` methods take the raw IFC text (a `string`), not a `Uint8Array`. Decode the buffer first.
 
-console.log(`Found ${result.entities.length} entities`);
-```
-
-For full 3D rendering, add geometry and renderer packages:
-
-```bash
-npm install @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer
-```
+```typescript
+import init, { IfcAPI } from '@ifc-lite/wasm';
 
-### Option 3: Rust/Cargo
+await init();                         // load and instantiate the WASM module
 
-For Rust projects:
+const api = new IfcAPI();
+const buffer = await fetch('model.ifc').then(r => r.arrayBuffer());
+const content = new TextDecoder().decode(buffer);
 
-```bash
-cargo add ifc-lite-core
-```
+// Lightweight parse — returns { entityCount, ... }
+const result = await api.parse(content);
+console.log(`Entities: ${result.entityCount}`);
 
-```rust
-use ifc_lite_core::parse_ifc;
+// Tessellated meshes — each entry has expressId, positions, indices, normals, color
+const meshes = api.parseMeshes(content);
+console.log(`${meshes.length} meshes`);
+for (let i = 0; i < meshes.length; i++) {
+  const mesh = meshes.get(i);
+  console.log(mesh.ifcType, mesh.expressId, mesh.vertexCount, 'vertices');
+}
 
-let result = parse_ifc(&ifc_bytes)?;
-println!("Parsed {} entities", result.entities.len());
+meshes.free();                        // free the Rust-side mesh buffer
+api.free();                           // free the API instance
 ```
 
-### Option 4: Clone the Repo (Contributors)
+## Streaming mesh batches
 
-For contributing or running the full demo app:
+For progressive rendering, stream meshes in batches and yield to the browser between them:
 
-```bash
-GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/louistrue/ifc-lite.git
-cd ifc-lite
-pnpm install && pnpm dev
+```typescript
+import init, { IfcAPI } from '@ifc-lite/wasm';
+
+await init();
+const api = new IfcAPI();
+
+await api.parseMeshesAsync(content, {
+  batchSize: 100,
+  onRtcOffset: ({ x, y, z, hasRtc }) => {
+    if (hasRtc) viewer.setWorldOffset(x, y, z);
+  },
+  onBatch: (meshes, progress) => {
+    for (const mesh of meshes) scene.add(toThreeMesh(mesh));
+    console.log(`${progress.percent}%`);
+  },
+  onComplete: ({ totalMeshes }) => console.log(`Done — ${totalMeshes} meshes`),
+});
 ```
 
-Open http://localhost:5173 and load an IFC file.
+## Zero-copy GPU upload
 
-> **Note:** Requires Node.js 18+ and pnpm 8+. No Rust toolchain needed - WASM is pre-built.
->
-> **Git LFS:** Large benchmark fixtures are intentionally not downloaded during clone. Pull only the files you need, for example `git lfs pull --include="tests/models/ara3d/AC20-FZK-Haus.ifc"`.
-> 
-> **📖 Full Guide**: See [Installation](docs/guide/installation.md) for detailed setup options including troubleshooting.
-
-### Basic Usage
+`parseToGpuGeometry` returns interleaved (position + normal) vertex data with pointers into WASM linear memory, ready for direct `GPUBuffer` upload:
 
 ```typescript
-import { IfcParser } from '@ifc-lite/parser';
-import { Renderer } from '@ifc-lite/renderer';
-
-// Parse IFC file
-const parser = new IfcParser();
-const result = parser.parse(ifcArrayBuffer);
-
-// Access entities
-const walls = result.entities.filter(e => e.type === 'IFCWALL');
-console.log(`Found ${walls.length} walls`);
-
-// Render geometry (requires @ifc-lite/renderer)
-const renderer = new Renderer(canvas);
-await renderer.loadGeometry(result.geometry);
-renderer.render();
-```
+import init, { IfcAPI } from '@ifc-lite/wasm';
 
-## Documentation
-
-| Resource | Description |
-|----------|-------------|
-| [**Quick Start**](docs/guide/quickstart.md) | Parse your first IFC file in 5 minutes |
-| [**Installation**](docs/guide/installation.md) | Detailed setup for npm, Cargo, and from source |
-| [**User Guide**](https://louistrue.github.io/ifc-lite/) | Complete guides: parsing, geometry, rendering, querying |
-| [**Tutorials**](docs/tutorials/building-viewer.md) | Build a viewer, custom queries, extend the parser |
-| [**Architecture**](docs/architecture/overview.md) | System design with detailed diagrams |
-| [**API Reference**](docs/api/typescript.md) | TypeScript, Rust, and WASM API docs |
-| [**Contributing**](docs/contributing/setup.md) | Development setup and testing guide |
-
-## Architecture
-
-```mermaid
-flowchart LR
-    IFC[IFC File] --> Tokenize
-    Tokenize --> Scan --> Decode
-    Decode --> Tables[Columnar Tables]
-    Decode --> Graph[Relationship Graph]
-    Tables --> Renderer[WebGPU Renderer]
-    Graph --> Export[glTF / Parquet]
-    
-    style IFC fill:#6366f1,stroke:#312e81,color:#fff
-    style Tokenize fill:#2563eb,stroke:#1e3a8a,color:#fff
-    style Scan fill:#2563eb,stroke:#1e3a8a,color:#fff
-    style Decode fill:#10b981,stroke:#064e3b,color:#fff
-    style Tables fill:#f59e0b,stroke:#7c2d12,color:#fff
-    style Graph fill:#f59e0b,stroke:#7c2d12,color:#fff
-    style Renderer fill:#a855f7,stroke:#581c87,color:#fff
-    style Export fill:#a855f7,stroke:#581c87,color:#fff
-```
-
-IFC files flow through three processing layers. See the [Architecture Documentation](docs/architecture/overview.md) for detailed diagrams including data flow, memory model, and threading.
+await init();
+const api = new IfcAPI();
+const gpuGeom = api.parseToGpuGeometry(content);
+const memory = api.getMemory();
 
-> **Deep Dive**: [Data Flow](docs/architecture/data-flow.md) ·
-> [Parsing Pipeline](docs/architecture/parsing-pipeline.md) ·
-> [Geometry Pipeline](docs/architecture/geometry-pipeline.md) ·
-> [Rendering Pipeline](docs/architecture/rendering-pipeline.md)
+// Direct views into WASM memory — no intermediate copy
+const vertexView = new Float32Array(memory.buffer, gpuGeom.vertexDataPtr, gpuGeom.vertexDataLen);
+const indexView = new Uint32Array(memory.buffer, gpuGeom.indicesPtr, gpuGeom.indicesLen);
 
-## Project Structure
+device.queue.writeBuffer(gpuVertexBuffer, 0, vertexView);
+device.queue.writeBuffer(gpuIndexBuffer, 0, indexView);
 
+// IMPORTANT: views are only valid until the next WASM allocation. Free immediately after upload.
+gpuGeom.free();
 ```
-ifc-lite/
-├── rust/                      # Rust/WASM backend
-│   ├── core/                  # IFC/STEP parsing (~2,000 LOC)
-│   ├── geometry/              # Geometry processing (~2,500 LOC)
-│   └── wasm-bindings/         # JavaScript API (~800 LOC)
-│
-├── packages/                  # TypeScript packages
-│   ├── parser/                # High-level IFC parser
-│   ├── geometry/              # Geometry bridge (WASM)
-│   ├── renderer/              # WebGPU rendering
-│   ├── cache/                 # Binary cache format
-│   ├── query/                 # Query system
-│   ├── data/                  # Columnar data structures
-│   ├── spatial/               # Spatial indexing
-│   ├── export/                # Export formats
-│   └── codegen/               # Schema generator
-│
-├── apps/
-│   └── viewer/                # React web application
-│
-└── docs/                      # Documentation (MkDocs)
-```
-
-## Performance
-
-### Bundle Size Comparison
-
-| Library | WASM Size | Gzipped |
-|---------|-----------|---------|
-| **IFClite** | **0.65 MB** | **0.26 MB** |
-| web-ifc | 1.1 MB | 0.4 MB |
-| IfcOpenShell | 15 MB | - |
-
-### Parse Performance
 
-| Model Size | IFClite | Notes |
-|------------|----------|-------|
-| 10 MB | ~100-200ms | Small models |
-| 50 MB | ~600-700ms | Typical models |
-| 100+ MB | ~1.5-2s | Complex geometry |
+For deduplicated geometry (one mesh per shape, per-instance transforms), use `parseToGpuInstancedGeometry(content)` and iterate `GpuInstancedGeometryCollection`.
 
-*Based on [benchmark results](tests/benchmark/benchmark-results.json) across 67 IFC files.*
+## Georeferencing
 
-### Zero-Copy GPU Pipeline
-
-- **Zero-copy WASM to WebGPU**: Direct memory access from WASM linear memory to GPU buffers
-- **60-70% reduction** in peak RAM usage
-- **74% faster** parse time with optimized data flow
-- **40-50% faster** geometry-to-GPU pipeline
-
-### Geometry Processing
-
-- **5x faster** overall than web-ifc (median 2.18x, up to 104x on some files)
-- Streaming pipeline with batched processing (100 meshes/batch)
-- First triangles visible in **300-500ms**
-
-*See [full benchmark data](tests/benchmark/benchmark-results.json) for per-file comparisons.*
-
-## Browser Requirements
-
-| Browser | Minimum Version | WebGPU |
-|---------|----------------|--------|
-| Chrome | 113+ | ✅ |
-| Edge | 113+ | ✅ |
-| Firefox | 127+ | ✅ |
-| Safari | 18+ | ✅ |
-
-> **More Info**: See [Browser Requirements](docs/guide/browser-requirements.md) for WebGPU feature detection and fallbacks.
-
-## Development (Contributors)
-
-For contributing to IFClite itself:
-
-```bash
-GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/louistrue/ifc-lite.git
-cd ifc-lite
-pnpm install
-
-pnpm dev          # Start viewer in dev mode
-pnpm build        # Build all packages
-pnpm test         # Run tests
-
-# Add a changeset when making changes
-pnpm changeset    # Describe your changes (required for releases)
-
-# Rust/WASM development (optional - WASM is pre-built)
-cd rust && cargo build --release --target wasm32-unknown-unknown
-bash scripts/build-wasm.sh  # Rebuild WASM after Rust changes
+```typescript
+import init, { IfcAPI } from '@ifc-lite/wasm';
+
+await init();
+const api = new IfcAPI();
+const georef = api.getGeoReference(content);
+
+if (georef) {
+  console.log(`CRS: ${georef.crsName}`);
+  const [e, n, h] = georef.localToMap(10, 20, 5);
+  console.log(`Local (10,20,5) → Map (${e}, ${n}, ${h})`);
+  georef.free();
+}
 ```
 
-## Packages
-
-| Package | Description | Status | Docs |
-|---------|-------------|--------|------|
-| `create-ifc-lite` | Project scaffolding CLI | ✅ Stable | [API](docs/api/typescript.md#create-ifc-lite) |
-| `@ifc-lite/parser` | STEP tokenizer & entity extraction | ✅ Stable | [API](docs/api/typescript.md#parser) |
-| `@ifc-lite/geometry` | Geometry processing bridge | ✅ Stable | [API](docs/api/typescript.md#geometry) |
-| `@ifc-lite/renderer` | WebGPU rendering pipeline | ✅ Stable | [API](docs/api/typescript.md#renderer) |
-| `@ifc-lite/cache` | Binary cache for instant loading | ✅ Stable | [API](docs/api/typescript.md#cache) |
-| `@ifc-lite/query` | Fluent & SQL query system | 🚧 Beta | [API](docs/api/typescript.md#query) |
-| `@ifc-lite/data` | Columnar data structures | ✅ Stable | [API](docs/api/typescript.md#data) |
-| `@ifc-lite/spatial` | Spatial indexing & culling | 🚧 Beta | [API](docs/api/typescript.md#spatial) |
-| `@ifc-lite/export` | Export (glTF, Parquet, etc.) | 🚧 Beta | [API](docs/api/typescript.md#export) |
-
-## Rust Crates
-
-| Crate | Description | Status | Docs |
-|-------|-------------|--------|------|
-| `ifc-lite-core` | STEP/IFC parsing | ✅ Stable | [docs.rs](https://docs.rs/ifc-lite-core) |
-| `ifc-lite-geometry` | Mesh triangulation | ✅ Stable | [docs.rs](https://docs.rs/ifc-lite-geometry) |
-| `ifc-lite-wasm` | WASM bindings | ✅ Stable | [docs.rs](https://docs.rs/ifc-lite-wasm) |
-
-## Community Projects
-
-Projects built by the community using IFClite (not officially maintained):
-
-| Project | Author | Description |
-|---------|--------|-------------|
-| [bimifc.de](https://bimifc.de/) | [@holg](https://github.com/holg) | Pure Rust/Bevy IFC viewer, no TypeScript needed |
+## Exports
 
-*Built something with IFClite? Open a PR to add it here!*
+| Class | Purpose |
+|---|---|
+| `IfcAPI` | Top-level parser entry point — `parse`, `parseMeshes`, `parseMeshesAsync`, `parseToGpuGeometry`, `parseZeroCopy`, `getGeoReference`, `extractProfiles`, `parseSymbolicRepresentations`, … |
+| `MeshCollection`, `MeshDataJs` | Tessellated geometry output |
+| `MeshCollectionWithRtc`, `RtcOffsetJs` | Mesh collection with relative-to-centre offset for large-coordinate models |
+| `InstancedMeshCollection`, `InstancedGeometry`, `InstanceData` | Instanced geometry path (deduplicated meshes + per-instance transforms) |
+| `ZeroCopyMesh`, `GpuGeometry`, `GpuMeshMetadata` | Zero-copy GPU upload handles |
+| `GpuInstancedGeometry`, `GpuInstancedGeometryCollection`, `GpuInstancedGeometryRef` | Zero-copy instanced path |
+| `GeoReferenceJs` | Georeferencing transform |
+| `ProfileCollection`, `ProfileEntryJs` | Cross-section profile data (extruded-area solids) |
+| `SymbolicRepresentationCollection`, `SymbolicCircle`, `SymbolicPolyline` | 2D symbolic representations (for plan / annotation views) |
 
-## Contributing
+All classes implement `free()` and `[Symbol.dispose]()` — call `free()` (or use `using`) to release Rust-side memory.
 
-We welcome contributions!
+## When to use a higher-level package instead
 
-| Resource | Description |
-|----------|-------------|
-| [**Development Setup**](docs/contributing/setup.md) | Prerequisites, installation, and project structure |
-| [**Testing Guide**](docs/contributing/testing.md) | Running tests, writing tests, CI |
-| [**Release Process**](RELEASE.md) | Versioning and publishing workflow |
+| You want… | Use |
+|---|---|
+| A typed, idiomatic TS API for parsing | [`@ifc-lite/parser`](../parser/README.md) |
+| Streaming geometry with worker support | [`@ifc-lite/geometry`](../geometry/README.md) |
+| WebGPU rendering | [`@ifc-lite/renderer`](../renderer/README.md) |
+| To avoid managing WASM lifecycles by hand | Any of the above |
 
-```bash
-# Fork and clone
-GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/YOUR_USERNAME/ifc-lite.git
-
-# Create a branch
-git checkout -b feature/my-feature
+## Rust source
 
-# Make changes and test
-pnpm test
+This package ships the bindings only. The Rust source lives in [`rust/wasm-bindings/`](https://github.com/louistrue/ifc-lite/tree/main/rust/wasm-bindings) and the core in [`rust/core/`](https://github.com/louistrue/ifc-lite/tree/main/rust/core). Available on crates.io as `ifc-lite-core`.
 
-# Add a changeset to describe your changes
-pnpm changeset
+## API
 
-# Submit a pull request (include the changeset file)
-```
+See the [WASM API Reference](https://louistrue.github.io/ifc-lite/api/wasm/).
 
 ## License
 
-This project is licensed under the [Mozilla Public License 2.0](LICENSE).
-
-## Acknowledgments
-
-- Built with [nom](https://github.com/rust-bakery/nom) for parsing
-- [earcutr](https://github.com/nickel-org/earcutr) for polygon triangulation
-- [nalgebra](https://nalgebra.org/) for linear algebra
-- [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/) for Rust/JS interop
-
----
-
-<p align="center">
-  Made with ❤️ for the AEC industry
-</p>
+[MPL-2.0](https://mozilla.org/MPL/2.0/)

package/package.json

@@ -5,7 +5,7 @@
     "IFC-Lite Contributors"
   ],
   "description": "WebAssembly bindings for IFC-Lite",
-  "version": "1.16.6",
+  "version": "1.16.8",
   "license": "MPL-2.0",
   "repository": {
     "type": "git",

package/pkg/ifc-lite.d.ts

@@ -1194,9 +1194,9 @@ export interface InitOutput {
   readonly profileentryjs_expressId: (a: number) => number;
   readonly symboliccircle_expressId: (a: number) => number;
   readonly __wbg_gpuinstancedgeometryref_free: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_1141: (a: number, b: number, c: number) => void;
-  readonly __wasm_bindgen_func_elem_1140: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_1181: (a: number, b: number, c: number, d: number) => void;
+  readonly __wasm_bindgen_func_elem_1151: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_1150: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_1190: (a: number, b: number, c: number, d: number) => void;
   readonly __wbindgen_export: (a: number) => void;
   readonly __wbindgen_export2: (a: number, b: number, c: number) => void;
   readonly __wbindgen_export3: (a: number, b: number) => number;

package/pkg/ifc-lite.js

@@ -212,12 +212,12 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-function __wasm_bindgen_func_elem_1141(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_1141(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_1151(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_1151(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_1181(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_1181(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_1190(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_1190(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 const GeoReferenceJsFinalization = (typeof FinalizationRegistry === 'undefined')
@@ -3093,7 +3093,7 @@ function __wbg_get_imports() {
                 const a = state0.a;
                 state0.a = 0;
                 try {
-                    return __wasm_bindgen_func_elem_1181(a, state0.b, arg0, arg1);
+                    return __wasm_bindgen_func_elem_1190(a, state0.b, arg0, arg1);
                 } finally {
                     state0.a = a;
                 }
@@ -3207,7 +3207,7 @@ function __wbg_get_imports() {
     };
     imports.wbg.__wbindgen_cast_782a03ac5d769879 = function(arg0, arg1) {
         // Cast intrinsic for `Closure(Closure { dtor_idx: 151, function: Function { arguments: [Externref], shim_idx: 152, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-        const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_1140, __wasm_bindgen_func_elem_1141);
+        const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_1150, __wasm_bindgen_func_elem_1151);
         return addHeapObject(ret);
     };
     imports.wbg.__wbindgen_cast_d6cd19b81560fd6e = function(arg0) {