@ivl/bim-object

TypeScript type definitions for authoring BIM object source files for the TS → Rust/WASM transpiler.

These types describe the authoring contract only — there is no runtime code. They cover:

1. The Geometry API objects call inside view functions.
2. The parameter definition schema (Parameters).
3. The object export contract (ViewFunction, SheetViewFunction, InferParams, …).

The signatures are reconciled against the arguments the transpiler's geometry handlers actually read (see src/geometry-transformer.ts in the transpiler repo).

Installation

npm install --save-dev @ivl/bim-object
# or
pnpm add -D @ivl/bim-object

Usage

import type { Geometry, Parameters, InferParams } from '@ivl/bim-object';

const Parameters = {
  radius: { type: 'number', default: 0.5, label: 'Radius', unit: 'm', step: 0.05, required: true },
} satisfies Parameters;

export function get3dViewGeometry(
  geometry: Geometry,
  params: InferParams<typeof Parameters>,
  lod: number,
) {
  geometry.addSphere({ center: [0, 0, 0], radius: params.radius });
}

Note that const Parameters is deliberately not exported: TypeScript does not allow an exported value to share the name of an imported type, and the transpiler picks up the Parameters declaration either way. If you prefer to export it, use the ParametersObject alias in the satisfies clause instead.

You can also copy index.d.ts directly into an authoring repo instead of taking the dependency — it is intentionally self-contained.

Grouping geometry

geometry.createGroup(…) returns a handle that takes every geometry method and places all of it with one transform, so an assembly can be positioned and rotated as a unit.

const arm = geometry.createGroup({ position: [0, 0, 0] });

arm.addCylinder({ start: [10, 0, 0], end: [10, 0, 2], radius: 0.1 });
arm.addBox({ center: [10, 0, 2.2], size: [0.4, 0.4, 0.4] });

arm.setRotation([0, Math.PI / 2, 0]);   // swings the whole arm about [0, 0, 0]
arm.setPosition([0, 0, 1.5]);           // then lifts it

Children are authored in the group's local space and end up at groupPosition + R(groupRotation) · childCoordinate. The pivot is therefore the group's own origin, not each child's — the cylinder above rotates around [0, 0, 0] even though it sits at x = 10. Rotations are [rx, ry, rz] in radians, applied X then Y then Z.

setPosition/setRotation are retroactive: they re-aim every child, including those added before the call. The group's geometry is emitted at the last statement that touches the group, so it can be drawn after geometry authored below it. Groups do not nest.

View-plane text

geometry.addText({ …, useViewPlane: true }) places a label in the view plane rather than the drawing plane. It is anchored at a 3D point but drawn square to the viewport, so orbiting a 3D view moves the label with its anchor without ever angling the text.

geometry.addText({
  position: [0, 0, 2.4],       // anchored in 3D; z is only honoured here
  text: 'AHU-01',
  size: 0.15,
  useViewPlane: true,
});

rotation/angle still applies, but as a rotation within the viewport instead of within the model. The flag may be parameter-driven, in which case the label falls back to ordinary drawing-plane text whenever the flag is off.

View-plane text lowers to the host import addTextViewPlane; an object using it does not load on a host that does not provide that import.

Multi-line text

A \n in a label's text starts a new line, whether it comes from a literal, a string parameter or a concatenation. The host lays the lines out below the first, in the text's own frame, for drawing-plane and view-plane text alike.

geometry.addText({
  position: [0, 0],
  text: 'AHU-01\n' + params.Duty,
  size: 0.15,
  lineHeight: 1.4,      // baselines 1.4 text heights apart; omit for the host default
  textAlign: 'center',  // each line centred on the anchor; 'left' (default) or 'right'
});

textAlign must be a literal — a parameter-driven alignment is rejected rather than silently ignored. Both settings reach the host as the trailing line_height and align arguments of addText2D / addTextViewPlane; a host that predates them draws the text as one left-aligned line.

String arrays

text.split(separator) produces a string array you can index, measure, iterate and concatenate — the usual way to build a label out of parts of a parameter.

const words = params.Label.split(' ');

geometry.addText({ position: [0, 0], text: words[0] + '-' + words[2], size: 1 });
geometry.addText({ position: [0, 1], text: words[words.length - 1], size: 1 });

for (const word of words) {
  geometry.addText({ position: [0, 2], text: word, size: 1 });
}

Reading past the end yields empty text rather than undefined: the object has no such value, and the alternative would abort the whole object's geometry. words.length is a number like any other, so it can drive a loop or a dimension.

Two argument forms are rejected rather than translated, because their result would differ from JavaScript's: split(''), which splits into characters, and split(separator, limit). Neither is supported — split on a real separator and index the parts you want.

Drawing title blocks

Specialist title blocks use the MOB parameter-first sheet signature. Sheet-view coordinates and text sizes are paper millimetres. Author the view as an exported function declaration; SheetViewFunction describes the same callable shape.

import type { Geometry, InferParams, LOD } from '@ivl/bim-object';

/** @mobBehaviour documentation.sheet.title-block */
export const Parameters = {
  DrawingNumber: { type: 'string', default: '', semanticRole: 'sheet.number' },
} as const;

export function getSheetViewGeometry(
  params: InferParams<typeof Parameters>,
  geometry: Geometry,
  _lod: LOD,
): void {
  geometry.addText({ position: [5, 5], text: params.DrawingNumber, size: 3.5 });
}

export default { Parameters, getSheetViewGeometry };