IFCLite

https://ifclite.dev/docs
Admin
IFClite is an open-source toolkit for working with IFC (Industry Foundation Classes) files, running...
Tokens:47,397
Snippets:447
Trust Score:2.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Clone and Build Project from Source

Source: https://ifclite.dev/docs/guide/installation

Commands to clone the repository, install dependencies, and start the development viewer.

```bash
# Clone the repository
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/LTplus-AG/ifc-lite.git
cd ifc-lite

# Install dependencies
pnpm install

# Build all packages (uses pre-built WASM)
pnpm build

# Start the viewer
pnpm dev
```

--------------------------------

### Install Client Dependencies

Source: https://ifclite.dev/docs/guide/quickstart

Install the required client and renderer packages via npm.

```bash
npm install @ifc-lite/server-client @ifc-lite/renderer
```

--------------------------------

### Install @ifc-lite packages

Source: https://ifclite.dev/docs/tutorials/threejs-integration

Install the necessary parser and data packages via npm.

```bash
npm install @ifc-lite/parser @ifc-lite/data
```

--------------------------------

### Install and Run IFCLite Native Binary

Source: https://ifclite.dev/docs/guide/installation

Methods for installing the server via npm and executing the binary directly or via npx.

```bash
# Install the server-bin package
npm install -g @ifc-lite/server-bin

# Start the server (downloads binary on first run)
ifc-lite-server

# Or use npx
npx @ifc-lite/server-bin
```

--------------------------------

### Start the IFC Lite Server

Source: https://ifclite.dev/docs/guide/quickstart

Commands to launch the server using Docker or the native binary.

```bash
# Using Docker
docker run -p 3001:8080 ghcr.io/ltplus-ag/ifc-lite-server

# Or using native binary
npx @ifc-lite/server-bin
```

--------------------------------

### Start the IFClite Server

Source: https://ifclite.dev/docs/guide/server

Methods to launch the server using Docker, the npm binary, or from source.

```shell
docker run -p 3001:8080 \
  -v ifc-cache:/app/cache \
  ghcr.io/ltplus-ag/ifc-lite-server
```

```shell
npx @ifc-lite/server-bin
```

```shell
cd apps/server
cargo run --release
```

--------------------------------

### Verifying Client-Side Installation

Source: https://ifclite.dev/docs/guide/installation

Verify the parser installation by loading an IFC file and checking schema metadata.

```javascript
import { IfcParser } from '@ifc-lite/parser';

const parser = new IfcParser();
const buffer = await fetch('model.ifc').then(r => r.arrayBuffer());
const store = await parser.parseColumnar(buffer);

console.log('Schema:', store.schemaVersion);
console.log('Entities:', store.entityCount);
```

--------------------------------

### Install Python Geometry Library

Source: https://ifclite.dev/docs/guide/installation

Install the native geometry tessellation package for Python.

```bash
pip install ifclite-geom
```

--------------------------------

### Initialize Project and Dependencies

Source: https://ifclite.dev/docs/tutorials/building-viewer

Commands to create a new Vite project with TypeScript and install the required IFC-lite packages.

```bash
# Create new project
mkdir my-ifc-viewer
cd my-ifc-viewer

# Initialize with Vite + TypeScript
npm create vite@latest . -- --template vanilla-ts

# Install dependencies
npm install @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer @ifc-lite/query
```

--------------------------------

### Install IFClite packages

Source: https://ifclite.dev/docs/guide/quickstart

Add the core parser, geometry, and renderer packages to an existing project.

```bash
npm install @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer
```

--------------------------------

### Install IFClite Packages via Package Manager

Source: https://ifclite.dev/docs/guide/installation

Install core, rendering, server, or IFC5 support packages using your preferred package manager.

```bash
# Core parsing (client-side)
pnpm add @ifc-lite/parser

# With rendering
pnpm add @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer

# Server client SDK
pnpm add @ifc-lite/server-client

# IFC5 support
pnpm add @ifc-lite/ifcx
```

```bash
# Core parsing (client-side)
npm install @ifc-lite/parser

# With rendering
npm install @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer

# Server client SDK
npm install @ifc-lite/server-client

# IFC5 support
npm install @ifc-lite/ifcx
```

```bash
# Core parsing (client-side)
yarn add @ifc-lite/parser

# With rendering
yarn add @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer

# Server client SDK
yarn add @ifc-lite/server-client

# IFC5 support
yarn add @ifc-lite/ifcx
```

--------------------------------

### Install R3F dependencies

Source: https://ifclite.dev/docs/tutorials/threejs-integration

Install the required packages for IFC-Lite geometry processing and React-Three-Fiber integration.

```bash
npm install @ifc-lite/geometry three @react-three/fiber @react-three/drei
```

--------------------------------

### Spatial Indexing and Frustum Culling Example

Source: https://ifclite.dev/docs/api/typescript

Demonstrates initializing geometry, building a spatial index, and rendering with frustum culling enabled.

```typescript
import { GeometryProcessor } from '@ifc-lite/geometry';
import { buildSpatialIndex } from '@ifc-lite/spatial';
import { Renderer } from '@ifc-lite/renderer';

const geometry = new GeometryProcessor();
await geometry.init();
const result = await geometry.process(new Uint8Array(buffer));

// Build spatial index for frustum culling
const spatialIndex = buildSpatialIndex(result.meshes);

const renderer = new Renderer(canvas);
await renderer.init();
renderer.loadGeometry(result);

// Render with frustum culling
renderer.render({
  enableFrustumCulling: true,
  spatialIndex
});
```

--------------------------------

### Complex SQL Query Examples

Source: https://ifclite.dev/docs/guide/querying

Advanced SQL examples for joining relationships, calculating aggregates, and filtering based on missing properties.

```sql
-- Find walls with their storey names
-- ContainsElements edges run storey (source_id) -> element (target_id)
SELECT
  e.express_id,
  e.name as wall_name,
  s.name as storey_name
FROM entities e
JOIN relationships r ON e.express_id = r.target_id
JOIN entities s ON r.source_id = s.express_id
WHERE e.type LIKE 'IfcWall%'
  AND r.rel_type = 'ContainsElements'
  AND s.type = 'IfcBuildingStorey';

-- Calculate total area by entity type
SELECT
  e.type,
  SUM(q.value) as total_area
FROM entities e
JOIN quantities q ON e.express_id = q.entity_id
WHERE q.quantity_name = 'NetArea'
GROUP BY e.type
ORDER BY total_area DESC;

-- Find walls with missing fire ratings
SELECT e.express_id, e.name, e.type
FROM entities e
WHERE e.type LIKE 'IfcWall%'
  AND NOT EXISTS (
    SELECT 1 FROM properties p
    WHERE p.entity_id = e.express_id
      AND p.pset_name = 'Pset_WallCommon'
      AND p.prop_name = 'FireRating'
  );
```

--------------------------------

### Install IFC Lite dependencies manually

Source: https://ifclite.dev/docs/tutorials/threejs-integration

Add the required geometry and Three.js packages to an existing project.

```bash
npm install @ifc-lite/geometry three
npm install -D @types/three
```

--------------------------------

### Initialize Main Application Entry Point

Source: https://ifclite.dev/docs/tutorials/building-viewer

Sets up the viewer instance, event listeners for file loading, and property selection callbacks.

```typescript
// src/main.ts
import { IfcViewer } from './viewer';
import { updateStatus, renderProperties } from './ui';
import './style.css';

async function main() {
  // Get elements
  const canvas = document.getElementById('viewer') as HTMLCanvasElement;
  const fileInput = document.getElementById('file-input') as HTMLInputElement;
  const propertiesPanel = document.getElementById('properties') as HTMLElement;

  // Create viewer
  const viewer = new IfcViewer(canvas);

  // Set up callbacks
  viewer.onProgress = updateStatus; // onProgress delivers a "phase: percent%" string
  viewer.onSelect = (expressId) => {
    if (expressId) {
      const entity = viewer.getEntity(expressId);
      const props = viewer.getProperties(expressId);
      if (entity) {
        renderProperties(propertiesPanel, expressId, entity, props || []);
      }
    } else {
      propertiesPanel.innerHTML = '<p>Click an element to view properties</p>';
    }
  };

  // Initialize
  try {
    await viewer.init();
    updateStatus('Ready - Drop an IFC file');
  } catch (error) {
    updateStatus('WebGPU not supported');
    console.error(error);
    return;
  }

  // File input handler
  fileInput.addEventListener('change', async () => {
    const file = fileInput.files?.[0];
    if (!file) return;

    updateStatus(`Loading ${file.name}...`);

    try {
      const result = await viewer.loadFile(file);
      updateStatus(`Loaded ${result.entityCount} entities`);
    } catch (error) {
      updateStatus('Error loading file');
      console.error(error);
    }
  });
}

main();
```

--------------------------------

### Initialize IFClite Projects with CLI

Source: https://ifclite.dev/docs/guide/installation

Use the create-ifc-lite CLI to scaffold projects based on specific templates.

```bash
npx create-ifc-lite my-app
cd my-app
npm install
npm run parse sample.ifc
```

```bash
npx create-ifc-lite my-viewer --template react
cd my-viewer
npm install
npm run dev
```

```bash
npx create-ifc-lite my-viewer --template threejs
cd my-viewer
npm install
npm run dev
```

```bash
npx create-ifc-lite my-viewer --template babylonjs
cd my-viewer
npm install
npm run dev
```

```bash
npx create-ifc-lite my-backend --template server
cd my-backend
npm install
npm run server:start
npm run example sample.ifc
```

```bash
npx create-ifc-lite my-backend --template server-native
cd my-backend
npm install
npm run server:start
```

--------------------------------

### Prototyping with CDN

Source: https://ifclite.dev/docs/guide/installation

Use this for quick prototyping without a build step. Requires an HTTP server environment.

```html
<script type="module">
  import { IfcParser } from 'https://cdn.jsdelivr.net/npm/@ifc-lite/parser/+esm';

  const parser = new IfcParser();
  const response = await fetch('model.ifc');
  const buffer = await response.arrayBuffer();
  const store = await parser.parseColumnar(buffer);
  console.log('Entities:', store.entityCount);
</script>
```

--------------------------------

### GET /api/v1/health

Source: https://ifclite.dev/docs/guide/server

Performs a liveness health check on the server.

```APIDOC
## GET /api/v1/health

### Description
Performs a liveness health check on the server. This endpoint is always open.

### Method
GET

### Endpoint
/api/v1/health
```

--------------------------------

### Connect to Server from Client

Source: https://ifclite.dev/docs/guide/server

Initialize the server client and perform a health check.

```javascript
import { IfcServerClient } from '@ifc-lite/server-client';

const client = new IfcServerClient({
  baseUrl: 'http://localhost:3001'
});

// Health check
const health = await client.health();
console.log('Server status:', health.status);
```

--------------------------------

### GET /api/v1/cache/check/{hash}

Source: https://ifclite.dev/docs/guide/server

Checks if a file is cached based on its hash.

```APIDOC
## GET /api/v1/cache/check/{hash}

### Description
Checks if a file is cached based on its hash. Returns 200 if cached, 404 otherwise.

### Method
GET

### Endpoint
/api/v1/cache/check/{hash}

### Parameters
#### Path Parameters
- **hash** (string) - Required - The hash of the file to check.
```

--------------------------------

### Scaffold a new IFC Lite project

Source: https://ifclite.dev/docs/tutorials/threejs-integration

Use the CLI to initialize a project with the Three.js template.

```bash
npx create-ifc-lite my-viewer --template threejs
cd my-viewer
npm install
npm run dev
```

--------------------------------

### Build IFCLite Server from Source

Source: https://ifclite.dev/docs/guide/installation

Compiling the server binary from the repository workspace using Cargo.

```bash
cargo build --release -p ifc-lite-server
./target/release/ifc-lite-server
```

--------------------------------

### Run development and production commands

Source: https://ifclite.dev/docs/tutorials/building-viewer

Use these commands to manage the application lifecycle during development and deployment.

```bash
# Start development server
npm run dev

# Build for production
npm run build
```

--------------------------------

### Initialize and parse IFC via CLI

Source: https://ifclite.dev/docs

Use the create-ifc-lite tool to scaffold a new project and parse an IFC file directly from the command line.

```bash
npx create-ifc-lite my-app
cd my-app && npm install && npm run parse ./model.ifc
```

--------------------------------

### Scaffold Three.js or Babylon.js viewers

Source: https://ifclite.dev/docs

Use the CLI to generate projects pre-configured for Three.js or Babylon.js integration.

```bash
npx create-ifc-lite my-viewer --template threejs     # Three.js
npx create-ifc-lite my-viewer --template babylonjs    # Babylon.js
```

--------------------------------

### Initialize Client and Load IFC File

Source: https://ifclite.dev/docs/guide/quickstart

Connect to the server and parse an IFC file using the Parquet format for optimized performance.

```typescript
import { IfcServerClient } from '@ifc-lite/server-client';
import { Renderer } from '@ifc-lite/renderer';

async function main() {
  const canvas = document.getElementById('viewer') as HTMLCanvasElement;
  const renderer = new Renderer(canvas);
  await renderer.init();

  // Connect to server
  const client = new IfcServerClient({
    baseUrl: 'http://localhost:3001'
  });

  // Load file (input element or drag-drop)
  const fileInput = document.getElementById('file-input') as HTMLInputElement;
  const file = fileInput?.files?.[0];
  if (!file) return;

  // Parse with Parquet format (15x smaller than JSON)
  const result = await client.parseParquet(file);

  console.log(`Parsed ${result.meshes.length} meshes`);
  console.log(`Cache key: ${result.cache_key}`);

  // On repeat loads, the server will return cached data instantly
  // (client computes file hash and checks cache before uploading)
}

main();
```

--------------------------------

### Initialize and render a model

Source: https://ifclite.dev/docs/guide/quickstart

Shows how to initialize the renderer and load geometry using either streaming or the GeometryProcessor.

```typescript
import { Renderer } from '@ifc-lite/renderer';
import { GeometryProcessor } from '@ifc-lite/geometry';

const canvas = document.getElementById('viewer') as HTMLCanvasElement;
const renderer = new Renderer(canvas);
await renderer.init();

// Option 1: Add meshes from server response (streaming)
renderer.addMeshes(result.meshes);

// Option 2: Load geometry from GeometryProcessor result
const geometry = new GeometryProcessor();
await geometry.init();
const meshes = [];
for await (const event of geometry.processAdaptive(new Uint8Array(buffer))) {
  if (event.type === 'batch') meshes.push(...event.meshes);
}
renderer.loadGeometry(meshes);

// Fit camera to model
renderer.fitToView();

// Start render loop
function animate() {
  renderer.render();
  requestAnimationFrame(animate);
}
animate();
```

--------------------------------

### Deployment Commands

Source: https://ifclite.dev/docs/guide/server

Common CLI commands for deploying the server to Railway, Fly.io, and Kubernetes environments.

```bash
# Railway deployment
railway up

# Fly.io deployment
fly deploy

# Kubernetes
kubectl apply -f k8s/deployment.yaml
```

--------------------------------

### Scaffold a server backend

Source: https://ifclite.dev/docs

Generate a backend project template for handling IFC files on the server.

```bash
npx create-ifc-lite my-backend --template server
cd my-backend && npm install && npm run server:start
```

--------------------------------

### createBCFProject

Source: https://ifclite.dev/docs/api/typescript

Initializes a new BCF project instance.

```APIDOC
## createBCFProject(options?: { name?: string; version?: '2.1' | '3.0' }): BCFProject

### Description
Creates a new BCFProject instance with optional name and version settings.

### Parameters
- **options** (Object) - Optional - Configuration for the project including name and version ('2.1' or '3.0').

### Response
- **BCFProject** (Object) - The initialized project.
```

--------------------------------

### IfcServerClient Constructor

Source: https://ifclite.dev/docs/guide/server

Initializes a new instance of the IfcServerClient.

```APIDOC
## IfcServerClient(options)

### Description
Initializes the client with a base URL and optional timeout.

### Parameters
- **options** (object) - Required
  - **baseUrl** (string) - Required - The server URL.
  - **timeout** (number) - Optional - Request timeout in milliseconds (default: 300000).
```

--------------------------------

### Initialize IfcServerClient

Source: https://ifclite.dev/docs/guide/server

Instantiate the client with a base URL and optional timeout configuration.

```typescript
import { IfcServerClient } from '@ifc-lite/server-client';

const client = new IfcServerClient({
  baseUrl: 'http://localhost:3001',
  timeout: 300000  // 5 minutes (default)
});
```

--------------------------------

### Initialize manual rendering pipeline

Source: https://ifclite.dev/docs

Manually configure the renderer and geometry processor to display IFC models in a canvas.

```javascript
import { IfcParser } from '@ifc-lite/parser';
import { GeometryProcessor } from '@ifc-lite/geometry';
import { Renderer } from '@ifc-lite/renderer';

const renderer = new Renderer(canvas);
await renderer.init();
const geometry = new GeometryProcessor();
await geometry.init();

const parser = new IfcParser();
const store = await parser.parseColumnar(buffer);
const meshes = [];
for await (const event of geometry.processAdaptive(new Uint8Array(buffer))) {
  if (event.type === 'batch') meshes.push(...event.meshes);
}

renderer.loadGeometry(meshes);
renderer.fitToView();
renderer.render();
```

--------------------------------

### Run IFCLite Server with Docker

Source: https://ifclite.dev/docs/guide/installation

Commands to deploy the official IFCLite container, including options for persistent storage and environment variable configuration.

```bash
# Run the official container
docker run -p 3001:8080 ghcr.io/ltplus-ag/ifc-lite-server

# With persistent cache
docker run -p 3001:8080 -v ifc-cache:/app/cache ghcr.io/ltplus-ag/ifc-lite-server

# With environment configuration
docker run -p 3001:8080 \
  -e RUST_LOG=info \
  -e MAX_FILE_SIZE_MB=500 \
  -e WORKER_THREADS=8 \
  ghcr.io/ltplus-ag/ifc-lite-server
```

--------------------------------

### BCF Project Creation and Mutation

Source: https://ifclite.dev/docs/api/typescript

Helpers for initializing BCF projects and managing topics, comments, and viewpoints.

```typescript
function createBCFProject(options?: { name?: string; version?: '2.1' | '3.0' }): BCFProject;
function createBCFTopic(options: { title: string; author: string; /* ... */ }): BCFTopic;
function createBCFComment(options: { author: string; comment: string }): BCFComment;

function addTopicToProject(project: BCFProject, topic: BCFTopic): void;
function addCommentToTopic(topic: BCFTopic, comment: BCFComment): void;
function addViewpointToTopic(topic: BCFTopic, viewpoint: BCFViewpoint): void;
function updateTopicStatus(/* topic, status, ... */): void;
```

--------------------------------

### Create an IFC file with IfcCreator

Source: https://ifclite.dev/docs/api/typescript

Initializes a new IFC project and adds a building storey and wall element.

```typescript
import { IfcCreator } from '@ifc-lite/create';

const creator = new IfcCreator({ Name: 'My Project' });
const storey = creator.addIfcBuildingStorey({ Name: 'Ground Floor', Elevation: 0 });
creator.addIfcWall(storey, {
  Start: [0, 0, 0], End: [5, 0, 0],
  Thickness: 0.2, Height: 3,
});
const { content } = creator.toIfc();
```

--------------------------------

### Scaffold a React-based viewer

Source: https://ifclite.dev/docs

Generate a new viewer project using the React template.

```bash
npx create-ifc-lite my-viewer --template react
cd my-viewer && npm install && npm run dev
```

--------------------------------

### Implement IFC viewer logic

Source: https://ifclite.dev/docs/guide/quickstart

Initialize the renderer, process IFC geometry, and render the model in the browser.

```typescript
// main.ts
import { IfcParser } from '@ifc-lite/parser';
import { GeometryProcessor } from '@ifc-lite/geometry';
import { Renderer } from '@ifc-lite/renderer';

async function main() {
  // Get the canvas element
  const canvas = document.getElementById('viewer') as HTMLCanvasElement;

  // Initialize the renderer
  const renderer = new Renderer(canvas);
  await renderer.init();

  // Initialize the geometry processor (loads WASM)
  const geometry = new GeometryProcessor();
  await geometry.init();

  // Load an IFC file
  const response = await fetch('model.ifc');
  const buffer = await response.arrayBuffer();

  // Parse the IFC file (columnar mode for best performance)
  const parser = new IfcParser();
  const store = await parser.parseColumnar(buffer, {
    onProgress: ({ phase, percent }) => {
      console.log(`Parsing: ${phase} ${percent}%`);
    }
  });

  console.log(`Parsed ${store.entityCount} entities`);

  // Process geometry from the IFC buffer
  const meshes = [];
  for await (const event of geometry.processAdaptive(new Uint8Array(buffer))) {
    if (event.type === 'batch') meshes.push(...event.meshes);
  }

  console.log(`Extracted ${meshes.length} meshes`);

  // Load geometry into renderer (creates GPU buffers and batches)
  renderer.loadGeometry(meshes);

  // Fit camera to model bounds
  renderer.fitToView();

  // Example: Query entities from the parsed store
  // The store variable from parser.parseColumnar() is available here in the same scope
  const wallIds = store.entityIndex.byType.get('IFCWALL') ?? [];
  console.log(`Found ${wallIds.length} walls`);

  // Start render loop
  function animate() {
    renderer.render();
    requestAnimationFrame(animate);
  }
  animate();

  // Add camera controls (see below)
  setupCameraControls(canvas, renderer);
}

main();
```

--------------------------------

### ProjectParams Interface

Source: https://ifclite.dev/docs/api/typescript

Configuration interface for initializing a new IFC project.

```typescript
interface ProjectParams {
  Name?: string;
  Description?: string;
  Schema?: 'IFC2X3' | 'IFC4' | 'IFC4X3';
  LengthUnit?: string;  // 'METRE' (default), 'MILLIMETRE', 'FOOT'
  Author?: string;
  Organization?: string;
}
```

--------------------------------

### GeometryProcessor.init()

Source: https://ifclite.dev/docs/api/typescript

Initializes the WASM environment. This must be called before any geometry processing or export operations.

```APIDOC
## init()

### Description
Initializes the WASM kernel required for geometry processing.

### Signature
`init(): Promise<void>`
```

--------------------------------

### Define Application Styles

Source: https://ifclite.dev/docs/tutorials/building-viewer

CSS rules for the property panel layout and file input styling.

```css
/* Add to style.css */
.prop-section {
  margin-bottom: 1rem;
  padding-bottom: 1rem;
  border-bottom: 1px solid #444;
}

.prop-section h3 {
  color: #4f46e5;
  margin-bottom: 0.5rem;
}

.prop-section h4 {
  color: #888;
  font-size: 0.9rem;
  margin-bottom: 0.5rem;
}

.prop-section p {
  margin: 0.25rem 0;
  font-size: 0.9rem;
}

.prop-section table {
  width: 100%;
  font-size: 0.85rem;
}

.prop-section td {
  padding: 0.25rem 0;
}

.prop-section td:first-child {
  color: #888;
  width: 40%;
}

#file-input {
  padding: 0.5rem;
  background: #4f46e5;
  border: none;
  border-radius: 4px;
  color: white;
  cursor: pointer;
}

#status {
  color: #888;
}
```

--------------------------------

### Implement Keyboard Shortcuts for Viewer Interaction

Source: https://ifclite.dev/docs/tutorials/building-viewer

Adds event listeners for keyboard inputs to control model visibility, isolation, and camera fitting. Requires integration into the viewer class structure.

```typescript
// Add to viewer.ts
private selectedId: number | null = null;
private hiddenIds = new Set<number>();
private isolatedIds: Set<number> | null = null;
private selectedIds = new Set<number>();

private setupKeyboardShortcuts(): void {
  document.addEventListener('keydown', (e) => {
    switch (e.key) {
      case 'f':
        this.renderer.fitToView();
        break;
      case 'h':
        if (this.selectedId) {
          this.hiddenIds.add(this.selectedId);
          this.render();
        }
        break;
      case 'i':
        if (this.selectedId) {
          this.isolatedIds = new Set([this.selectedId]);
          this.render();
        }
        break;
      case 'Escape':
        this.isolatedIds = null;
        this.selectedIds.clear();
        this.render();
        break;
    }
  });
}

private render(): void {
  this.renderer.render({
    hiddenIds: this.hiddenIds,
    isolatedIds: this.isolatedIds,
    selectedIds: this.selectedIds
  });
}
```

--------------------------------

### Generate Rust documentation with cargo

Source: https://ifclite.dev/docs/api/rust

Executes the cargo doc command to build and open documentation for all items, including private ones.

```bash
cargo doc --no-deps --document-private-items --open
```

--------------------------------

### Initialize GeometryProcessor for Native Desktop

Source: https://ifclite.dev/docs/guide/desktop

Configure the GeometryProcessor to utilize native Rust geometry processing when running within a Tauri environment.

```typescript
import { GeometryProcessor, isTauri, type IPlatformBridge } from '@ifc-lite/geometry';

// preferNative defaults to true; the native path activates only when isTauri()
// is true. On the web it is always false and the WASM path is used.
const processor = new GeometryProcessor({ preferNative: true });
```

--------------------------------

### Create View Preset Toolbar Buttons

Source: https://ifclite.dev/docs/tutorials/building-viewer

Dynamically generates UI buttons to trigger predefined camera orientations. Assumes a toolbar element exists in the DOM.

```typescript
// Add toolbar buttons
const presets = ['front', 'back', 'left', 'right', 'top'] as const;

presets.forEach(preset => {
  const button = document.createElement('button');
  button.textContent = preset;
  button.onclick = () => {
    const camera = viewer.getRenderer().getCamera();
    camera.setPresetView(preset, viewer.getModelBounds() ?? undefined);
  };
  toolbar.appendChild(button);
});
```

--------------------------------

### Define Project Structure

Source: https://ifclite.dev/docs/tutorials/building-viewer

The recommended file organization for the IFC viewer project.

```text
my-ifc-viewer/
├── src/
│   ├── main.ts           # Entry point
│   ├── viewer.ts         # Viewer class
│   ├── ui.ts             # UI components
│   └── style.css         # Styles
├── index.html
├── vite.config.ts
└── package.json
```

--------------------------------

### Running a clash detection session

Source: https://ifclite.dev/docs/api/rust

Initializes a session and executes a rule using ingested geometry buffers.

```rust
use ifc_lite_clash::ClashSession;

let mut session = ClashSession::new();
// positions: concatenated per-element vertex coords (x, y, z, ...)
// pos_ranges: [float_offset, float_len] per element
// indices: concatenated per-element LOCAL triangle indices
// idx_ranges: [idx_offset, idx_len] per element
// aabbs: [minx, miny, minz, maxx, maxy, maxz] per element
session.ingest(&[], &[], &[], &[], &[]);
let result = session.run_rule(&[], &[], 0, 0.0, 0.0, false);

```

--------------------------------

### Parse IFC5 and IFC files

Source: https://ifclite.dev/docs/guide/quickstart

Demonstrates auto-detecting file formats and parsing IFCX files directly to access pre-tessellated meshes.

```typescript
import { parseAuto } from '@ifc-lite/parser';
import { parseIfcx, detectFormat } from '@ifc-lite/ifcx';

// Auto-detect format
const result = await parseAuto(buffer);

if (result.format === 'ifcx') {
  // IFC5 file (result.data is IfcxParseResult)
  console.log('IFC5 with', result.meshes.length, 'pre-tessellated meshes');
} else {
  // IFC STEP file (result.data is IfcDataStore)
  console.log('IFC with', result.data.entityCount, 'entities');
}

// Or parse IFCX directly
const format = detectFormat(buffer);
if (format === 'ifcx') {
  const ifcxResult = await parseIfcx(buffer, {
    onProgress: ({ phase, percent }) => console.log(`${phase}: ${percent}%`)
  });

  // IFC5 uses ECS composition - entities have components
  console.log(`Entities: ${ifcxResult.entityCount}`);
  console.log(`Meshes: ${ifcxResult.meshes.length}`);

  // Pre-tessellated USD geometry
  for (const mesh of ifcxResult.meshes) {
    console.log(`Mesh for entity #${mesh.expressId}: ${mesh.ifcType}`);
  }
}
```

--------------------------------

### Configure ifc-lite-geometry features

Source: https://ifclite.dev/docs/api/rust

Optional features for debugging, benchmarking, and observability.

```toml
default = []          # no optional features
debug_geometry = []   # extra geometry debugging output
csg_capture = []      # measurement-only CSG corpus capture for benches
observability = []    # route diagnostics through `tracing` instead of eprintln

```

--------------------------------

### View Repository Directory Structure

Source: https://ifclite.dev/docs/guide/installation

Displays the high-level organization of the ifc-lite project, including Rust, TypeScript, and application directories.

```text
ifc-lite/
├── rust/                      # Rust/WASM backend
│   ├── core/                  # IFC/STEP parsing
│   ├── geometry/              # Geometry processing
│   ├── processing/            # Streaming / entity scan
│   ├── export/                # glTF / IFC5 export
│   ├── clash/                 # Clash detection
│   ├── ffi/                   # C FFI bindings
│   ├── python/                # Python wheel (ifclite-geom)
│   └── wasm-bindings/         # JavaScript API
│
├── packages/                  # TypeScript packages (@ifc-lite/*)
│   ├── parser/                # High-level IFC parser
│   ├── ifcx/                  # IFC5 (IFCX) parser
│   ├── geometry/              # Geometry bridge (WASM)
│   ├── renderer/              # WebGPU rendering
│   ├── cli/                   # Terminal toolkit
│   ├── sdk/                   # Scripting SDK
│   ├── viewer/                # @ifc-lite/viewer-core (CLI 3D viewer)
│   ├── server-client/         # Server SDK
│   ├── create-ifc-lite/       # Project scaffolding CLI
│   └── ...                    # query, data, spatial, export, ids, bcf, ...
│
├── apps/
│   ├── viewer/                # React web application
│   ├── viewer-embed/          # Embeddable viewer
│   ├── landing/               # Landing page
│   └── server/                # Rust HTTP server
│
└── docs/                      # Documentation (MkDocs)
```

--------------------------------

### Apply Base Styles

Source: https://ifclite.dev/docs/tutorials/building-viewer

CSS styles to define the layout and dark theme for the viewer interface.

```css
/* src/style.css */
* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  font-family: system-ui, sans-serif;
  background: #1a1a1a;
  color: #fff;
}

#app {
  display: flex;
  flex-direction: column;
  height: 100vh;
}

header {
  padding: 1rem;
  background: #2a2a2a;
  display: flex;
  gap: 1rem;
  align-items: center;
}

main {
  flex: 1;
  display: flex;
  overflow: hidden;
}

#viewer {
  flex: 1;
}

#properties {
  width: 300px;
  background: #2a2a2a;
  padding: 1rem;
  overflow-y: auto;
}
```

--------------------------------

### Define Core Parser Modules

Source: https://ifclite.dev/docs/api/rust

Lists the primary modules available in the ifc-lite-core crate for STEP parsing and entity management.

```rust
pub mod parser;          // STEP tokenization and entity scanning
pub mod decoder;         // Lazy entity decoding + entity index
pub mod generated;       // Generated IFC type enumeration (IfcType)
pub mod schema_gen;      // Decoded attribute values and entities
pub mod streaming;       // Streaming parse events
pub mod fast_parse;      // Fast single-purpose extraction helpers
pub mod georef;          // Georeferencing extraction
pub mod legacy_entities; // IFC2X3 legacy entity handling
pub mod model_bounds;    // Model/placement bounds scanning
pub mod project_units;   // Project unit resolution
pub mod step_encoding;   // STEP string encode/decode
pub mod units;           // Unit conversion helpers
pub mod error;           // Error types
```

--------------------------------

### IfcAPI Constructor

Source: https://ifclite.dev/docs/api/rust

Initializes a new instance of the IfcAPI for interacting with IFC data.

```APIDOC
## new()

### Description
Create and initialize the IFC API.

### Method
Constructor

### Returns
- **IfcAPI** - A new instance of the API.
```

--------------------------------

### Initialize and Use GeometryProcessor

Source: https://ifclite.dev/docs/architecture/overview

Entry point for converting IFC bytes into meshes. Supports both full buffer processing and streaming for large files.

```typescript
import { GeometryProcessor } from '@ifc-lite/geometry';

const processor = new GeometryProcessor({ enableInstancing: true });
await processor.init();

// Small/medium files: process the whole buffer at once
const result = await processor.process(ifcBytes);

// Large files: stream events (rtcOffset, batches of meshes, progress)
for await (const event of processor.processStreaming(ifcBytes)) {
  if (event.type === 'batch') {
    // handle each batch of meshes
  }
}
```

--------------------------------

### createViewpoint

Source: https://ifclite.dev/docs/api/typescript

Creates a BCFViewpoint from the current viewer state.

```APIDOC
## createViewpoint(options): BCFViewpoint

### Description
Generates a BCFViewpoint object based on the provided viewer state (camera, section plane, selection, visibility, snapshot).

### Parameters
- **options** (Object) - Required - The viewer state configuration.

### Response
- **BCFViewpoint** (Object) - The created viewpoint.
```

--------------------------------

### Build the IFC Data Store

Source: https://ifclite.dev/docs/tutorials/threejs-integration

Initialize the IfcParser to create a columnar index from an IFC buffer.

```typescript
import {
  IfcParser,
  type IfcDataStore,
  extractEntityAttributesOnDemand,
  extractPropertiesOnDemand,
  extractQuantitiesOnDemand,
} from '@ifc-lite/parser';

async function buildDataStore(buffer: ArrayBuffer): Promise<IfcDataStore> {
  return new IfcParser().parseColumnar(buffer);
}
```

--------------------------------

### Accessing Entities and Spatial Hierarchy

Source: https://ifclite.dev/docs/guide/quickstart

Demonstrates how to parse a buffer into an IfcDataStore and navigate the entity index and spatial hierarchy.

```typescript
const store = await parser.parseColumnar(buffer);

// Access entities by type
const wallIds = store.entityIndex.byType.get('IFCWALL') ?? [];
const doorIds = store.entityIndex.byType.get('IFCDOOR') ?? [];
const windowIds = store.entityIndex.byType.get('IFCWINDOW') ?? [];

// Access entity by ID
const entityRef = store.entityIndex.byId.get(123);
if (entityRef) {
  console.log(`Entity #${entityRef.expressId}: ${entityRef.type}`);
}

// Get spatial hierarchy
import { IfcTypeEnum } from '@ifc-lite/data';

const hierarchy = store.spatialHierarchy;
console.log(`Project: ${hierarchy.project.name}`);

// List storeys (SpatialNode.type is a numeric IfcTypeEnum, keyed by expressId)
for (const storey of hierarchy.project.children) {
  if (storey.type === IfcTypeEnum.IfcBuildingStorey) {
    const elements = hierarchy.byStorey.get(storey.expressId) ?? [];
    console.log(`${storey.name}: ${elements.length} elements`);
  }
}
```

--------------------------------

### POST /api/v1/parse/parquet

Source: https://ifclite.dev/docs/guide/server

Performs a full parse of an IFC file and returns the result as a Parquet file.

```APIDOC
## POST /api/v1/parse/parquet

### Description
Performs a full parse of an IFC file and returns the result as a Parquet file.

### Method
POST

### Endpoint
/api/v1/parse/parquet
```

--------------------------------

### Defining C FFI parsing entry points

Source: https://ifclite.dev/docs/api/rust

Exposes unsafe C-compatible functions for parsing IFC files and managing memory.

```rust
/// Parse an IFC file at `path` and write a serialized result buffer
pub unsafe extern "C" fn ifc_lite_parse(
    path_ptr: *const u8, path_len: usize,
    out_ptr: *mut *mut u8, out_len: *mut usize,
) -> i32;

/// Same, with an explicit opening-filter mode
/// (`opening_filter_mode`: 0 = Default, 1 = IgnoreAll, 2 = IgnoreOpaque)
pub unsafe extern "C" fn ifc_lite_parse_ex(
    path_ptr: *const u8, path_len: usize,
    opening_filter_mode: i32,
    out_ptr: *mut *mut u8, out_len: *mut usize,
) -> i32;

/// Free a buffer returned by the parse calls
pub unsafe extern "C" fn ifc_lite_free(ptr: *mut u8, len: usize);

```

--------------------------------

### Verifying IFC5 Support

Source: https://ifclite.dev/docs/guide/installation

Detect file format and parse IFC5 content using the ifcx module.

```javascript
import { parseIfcx, detectFormat } from '@ifc-lite/ifcx';

const format = detectFormat(buffer); // 'ifc', 'ifcx', 'glb', or 'unknown'
if (format === 'ifcx') {
  const result = await parseIfcx(buffer);
  console.log('IFC5 entities:', result.entityCount);
}
```

--------------------------------

### Implement selection and picking

Source: https://ifclite.dev/docs/guide/quickstart

Handles canvas click events to perform GPU picking and retrieve entity properties on demand.

```typescript
import { extractPropertiesOnDemand } from '@ifc-lite/parser';

// Track selection state
let selectedIds = new Set<number>();
let hiddenIds = new Set<number>();
let isolatedIds: Set<number> | null = null;

// GPU picking
canvas.addEventListener('click', async (e) => {
  const rect = canvas.getBoundingClientRect();
  const x = e.clientX - rect.left;
  const y = e.clientY - rect.top;

  const hit = await renderer.pick(x, y);
  if (hit) {
    const expressId = hit.expressId;
    console.log(`Selected entity #${expressId}`);
    selectedIds = new Set([expressId]);

    // Get properties using on-demand extraction
    const props = extractPropertiesOnDemand(store, expressId);
    displayProperties(props);
  } else {
    selectedIds.clear();
  }

  // Re-render with updated selection
  renderer.render({ selectedIds, hiddenIds, isolatedIds });
});
```

--------------------------------

### Initializing Geometry Processor with WASM

Source: https://ifclite.dev/docs/guide/installation

Explicitly initialize the WASM module when using the geometry processor via CDN.

```html
<script type="module">
  import { GeometryProcessor } from 'https://cdn.jsdelivr.net/npm/@ifc-lite/geometry/+esm';
  import initWasm from 'https://cdn.jsdelivr.net/npm/@ifc-lite/wasm/+esm';

  // Initialize WASM with explicit path (required for CDN)
  const wasmUrl = 'https://cdn.jsdelivr.net/npm/@ifc-lite/wasm/pkg/ifc-lite_bg.wasm';
  await initWasm({ module_or_path: wasmUrl });

  const processor = new GeometryProcessor();
  await processor.init();
  // ... process geometry
</script>
```

--------------------------------

### WASM Feature Flags

Source: https://ifclite.dev/docs/api/rust

Configuration options for the build process, including support for threading, console tracing, and geometry debugging.

```toml
default = ["console_error_panic_hook"]
threads = []          # threaded bundle via wasm-bindgen-rayon (built separately)
console-tracing = []  # forward structured diagnostics to the DevTools console
debug_geometry = []   # forwards to ifc-lite-geometry/debug_geometry
```

--------------------------------

### Docker Compose Configuration

Source: https://ifclite.dev/docs/guide/server

Standard Docker Compose service definition for the IFC Lite server with environment variables and volume mapping.

```yaml
version: '3.8'

services:
  ifc-lite-server:
    image: ghcr.io/ltplus-ag/ifc-lite-server:latest
    ports:
      - "3001:8080"
    environment:
      - RUST_LOG=info
      - MAX_FILE_SIZE_MB=500
      - WORKER_THREADS=8
      - CACHE_MAX_AGE_DAYS=30
    volumes:
      - ifc-cache:/app/cache

volumes:
  ifc-cache:
```

--------------------------------

### parseAuto

Source: https://ifclite.dev/docs/api/typescript

Auto-detects the file format (IFC/STEP vs IFCX/JSON) and parses the content accordingly.

```APIDOC
## parseAuto(buffer: ArrayBuffer)

### Description
Automatically detects the file format (IFC/STEP, IFCX/JSON, or .ifcZIP) and parses the provided buffer. Returns a result containing the parsed data and format information.
```

--------------------------------

### IfcCreator

Source: https://ifclite.dev/docs/api/typescript

The IfcCreator class is used to build valid IFC4 STEP files programmatically. It provides methods to define spatial structures, add building elements, and manage properties or materials.

```APIDOC
## IfcCreator

### Description
Class for creating and managing IFC project structures and elements.

### Constructor
`new IfcCreator(params?: ProjectParams)`

### Methods
- `addIfcBuildingStorey(params: StoreyParams): number`
- `addIfcWall(storeyId, params: WallParams): number`
- `addIfcSlab(storeyId, params: SlabParams): number`
- `addIfcColumn(storeyId, params: ColumnParams): number`
- `addIfcBeam(storeyId, params: BeamParams): number`
- `addIfcStair(storeyId, params: StairParams): number`
- `addIfcRoof(storeyId, params: RoofParams): number`
- `addIfcGableRoof(storeyId, params: GableRoofParams): number`
- `addIfcDoor(storeyId, params: DoorParams): number`
- `addIfcWindow(storeyId, params: WindowParams): number`
- `addIfcWallDoor(wallId, params: WallDoorParams): number`
- `addIfcWallWindow(wallId, params: WallWindowParams): number`
- `addIfcRamp(storeyId, params: RampParams): number`
- `addIfcRailing(storeyId, params: RailingParams): number`
- `addIfcPlate(storeyId, params: PlateParams): number`
- `addIfcMember(storeyId, params: MemberParams): number`
- `addIfcFooting(storeyId, params: FootingParams): number`
- `addIfcPile(storeyId, params: PileParams): number`
- `addIfcSpace(storeyId, params: SpaceParams): number`
- `addIfcPropertySet(elementId, pset: PropertySetDef): number`
- `addIfcElementQuantity(elementId, qset: QuantitySetDef): number`
- `addIfcMaterial(elementId, material: MaterialDef): void`
- `setColor(elementId, name: string, rgb: [number, number, number]): void`
- `toIfc(): CreateResult`
```

--------------------------------

### Client-Side Streaming Patterns

Source: https://ifclite.dev/docs/guide/server

Demonstrates mapping server mesh data to renderer shapes using both callback and async iterator patterns.

```typescript
import type { MeshData as ServerMeshData } from '@ifc-lite/server-client';

// Server meshes use snake_case fields; map to the renderer's shape.
const toRendererMesh = (m: ServerMeshData) => ({
  expressId: m.express_id,
  ifcType: m.ifc_type,
  positions: m.positions,
  normals: m.normals,
  indices: m.indices,
  color: m.color,
});

// Using callback
await client.parseParquetStream(file, (batch) => {
  // batch.meshes are already decoded server MeshData
  renderer.addMeshes(batch.meshes.map(toRendererMesh));
});

// Using async iterator
for await (const event of client.parseStream(file)) {
  if (event.type === 'batch') {
    renderer.addMeshes(event.meshes.map(toRendererMesh));
  }
}
```

--------------------------------

### Constraints, Audit, and Translation

Source: https://ifclite.dev/docs/api/typescript

Utilities for matching constraints, auditing document structure, and localizing reports.

```typescript
function matchConstraint(constraint: IDSConstraint, value: unknown): boolean;
function formatConstraint(constraint: IDSConstraint): string;
function getConstraintMismatchReason(constraint: IDSConstraint, value: unknown): string;

// IDS document correctness audit
function auditIDSDocument(/* ... */): IDSAuditReport;
function auditIDSStructure(/* ... */): IDSAuditReport;

// Report localisation
function createTranslationService(locale: 'en' | 'de' | 'fr'): TranslationService;
```

--------------------------------

### Re-export profile and extrusion modules

Source: https://ifclite.dev/docs/api/rust

Access points for profile handling and extrusion operations.

```rust
pub use profile::{Profile2D, Profile2DWithVoids, Profile2DType, VoidInfo};
pub use profile_extractor::{extract_profiles, ExtractedProfile};
pub use extrusion::{extrude_profile, extrude_profile_lofted, extrude_profile_with_voids};
```

--------------------------------

### Build Entity Index

Source: https://ifclite.dev/docs/api/rust

Defines the structure and construction method for mapping express IDs to file byte ranges.

```rust
/// Index of entity byte ranges in the file: express_id -> (start, end)
pub type EntityIndex = FxHashMap<u32, (usize, usize)>;

/// Build the index in one scan over the file bytes
pub fn build_entity_index<T>(content: &T) -> EntityIndex;
```
Tokens:
Raw