> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ploterr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# buildFromBuildingModel

> buildFromBuildingModel makes 3D elements from a building model.

Use it to show a building that the user does not edit. For editing, use [`BuildingSession`](/floorkit/api/editor/building-session).

## Import

```typescript theme={null}
import { buildFromBuildingModel, disposeBuildResult, BmBuildError } from '@opengeometry/floorkit';
```

## Example

```typescript theme={null}
import * as THREE from 'three';
import {
  buildFromBuildingModel,
  disposeBuildResult,
  type BuildingModel,
} from '@opengeometry/floorkit';

export function inspectBuild(model: BuildingModel): void {
  const build = buildFromBuildingModel(model, new THREE.Group());
  try {
    console.log(build.warnings, build.sourceByLiveId);
  } finally {
    disposeBuildResult(build);
  }
}
```

## Notes

* Start the geometry kernel first.
* The `root` of the result is already a child of the parent that you give.
* `elementsById` gives the element for an id in the model. `sourceByLiveId` gives the model id for a live element.
* Read `warnings` after the build.
* A door, a window or a hole that does not fit on its wall at its saved `offset` is drawn there without a hole. The build does not change the model. It gives the warning `opening-does-not-fit`: its `openingFit` gives the offsets where the opening fits and the nearest one. Move the opening to such an offset to remove the warning.
* Call `disposeBuildResult` when you replace or remove the build.
* Give the content of external assets in `assetSources`. The function does not download them.

## Signature

```typescript theme={null}
function buildFromBuildingModel(
  ir: BuildingModel,
  parent: THREE.Object3D,
  options?: BuildOptions,
): BuildResult;
```

## Parameters

<ParamField path="ir" type="BuildingModel" required />

<ParamField path="parent" type="THREE.Object3D" required />

<ParamField path="options" type="BuildOptions">
  Default: `&#123;&#125;`.
</ParamField>

## Returns

```typescript theme={null}
BuildResult;
```

## disposeBuildResult

Release a completed build after replacing it or closing its owner.

```typescript theme={null}
function disposeBuildResult(built: BuildResult): void;
```

## BmBuildError

```typescript theme={null}
class BmBuildError extends Error {
  readonly path: string;
  readonly code: string;
  readonly reason?: unknown;
  constructor(path: string, code: string, message: string, reason?: unknown);
}
```

## Types

### BuildOptions

```typescript theme={null}
interface BuildOptions {
  validated?: boolean;
  stampMembership?: boolean;
  assetSources?: Record<string, string | OpenElementDefinition>;
  massColors?: Readonly<Record<string, BmColor>>;
}
```

<ResponseField name="validated" type="boolean">
  Skip revalidation for a document already checked this tick.
</ResponseField>

<ResponseField name="stampMembership" type="boolean">
  Stamp `storeyId`/`buildingId` onto every element's propertySet. Default true.
</ResponseField>

<ResponseField name="assetSources" type="Record<string, string | OpenElementDefinition>">
  `.op` sources for the document's `external-op` assets, keyed by their `uri`, as either a raw
  buffer or an already-parsed definition. Fetching is the CALLER's pre-step so this function stays
  synchronous — the same split `.opbase` uses (`OPBaseOptions.assetSources`). An `embedded-op` asset
  needs nothing here.
</ResponseField>

<ResponseField name="massColors" type="Readonly<Record<string, BmColor>>">
  The colour of a mass part by its use, `#rrggbb` by use name, used for a part when neither it nor
  its mass has a `color`. Replaces `MASS_COLORS_BY_USE` whole; a use it does not list takes
  `#a0b8c8`. Pass it where the project is opened (`ProjectManager` `build`) so that the live build,
  the plan drawings and the sheets take the same colours.
</ResponseField>

### BuildResult

```typescript theme={null}
interface BuildResult {
  root: THREE.Group;
  elementsById: Map<string, OPElement>;
  modelObjectsById: Map<string, CompiledModelObject>;
  sourceByLiveId: Map<string, BuildingSourceRef>;
  storeyGroups: Map<string, THREE.Group>;
  wallNetworks: Map<string, WallNetwork>;
  warnings: BmIssue[];
  spatialStructure: BuildingModelSpatialStructure;
}
```

<ResponseField name="root" type="THREE.Group" required>
  One group per build, already added to the parent, at identity — elements are in world coordinates.
</ResponseField>

<ResponseField name="elementsById" type="Map<string, OPElement>" required>
  BuildingModel id -> live element, so a caller can edit without re-parsing the document.
</ResponseField>

<ResponseField name="modelObjectsById" type="Map<string, CompiledModelObject>" required>
  Saved basic geometry, kept separate from BIM elements and their exporter contract.
</ResponseField>

<ResponseField name="sourceByLiveId" type="Map<string, BuildingSourceRef>" required>
  Live element ID -> authored BuildingModel identity and feature.
</ResponseField>

<ResponseField name="storeyGroups" type="Map<string, THREE.Group>" required />

<ResponseField name="wallNetworks" type="Map<string, WallNetwork>" required />

<ResponseField name="warnings" type="BmIssue[]" required />

<ResponseField name="spatialStructure" type="BuildingModelSpatialStructure" required />

### CompiledModelObject

Extend this discriminated union alongside BmModelObject.

```typescript theme={null}
type CompiledModelObject =
  | CompiledLineObject
  | CompiledArcObject
  | CompiledPolylineObject
  | CompiledPolygonObject
  | CompiledRectangleObject
  | CompiledCuboidObject
  | CompiledCylinderObject;
```

### BuildingModelSpatialStructure

The non-geometric ownership context returned by a BuildingModel build.

```typescript theme={null}
interface BuildingModelSpatialStructure {
  project: SpatialStructureScope;
  site?: SpatialStructureScope;
  buildings: SpatialStructureBuilding[];
}
```

### CompiledLineObject

A compiled line and its authored ownership, kept separate from BIM elements.

The package does not export this type by name.

```typescript theme={null}
interface CompiledLineObject {
  kind: 'line';
  id: string;
  buildingId: string;
  storeyId: string;
  workingPlaneId: string;
  worldStart: Vec3;
  worldEnd: Vec3;
  color?: string;
  object: LinePrimitive;
}
```

<ResponseField name="kind" type="'line'" required />

<ResponseField name="id" type="string" required />

<ResponseField name="buildingId" type="string" required />

<ResponseField name="storeyId" type="string" required />

<ResponseField name="workingPlaneId" type="string" required />

<ResponseField name="worldStart" type="Vec3" required />

<ResponseField name="worldEnd" type="Vec3" required />

<ResponseField name="color" type="string">
  Saved #rrggbb stroke, independent of the live THREE material.
</ResponseField>

<ResponseField name="object" type="LinePrimitive" required />

### CompiledArcObject

A compiled circular arc and its world-space working-plane frame.

```typescript theme={null}
interface CompiledArcObject {
  kind: 'arc';
  id: string;
  buildingId: string;
  storeyId: string;
  workingPlaneId: string;
  worldCenter: Vec3;
  worldXAxis: Vec3;
  worldYAxis: Vec3;
  radius: number;
  startAngle: number;
  sweepAngle: number;
  color?: string;
  object: ArcPrimitive;
}
```

### CompiledPolylineObject

A compiled open path with vertices in world XYZ coordinates.

```typescript theme={null}
interface CompiledPolylineObject {
  kind: 'polyline';
  id: string;
  buildingId: string;
  storeyId: string;
  workingPlaneId: string;
  worldVertices: Vec3[];
  color?: string;
  object: PolylinePrimitive;
}
```

### CompiledPolygonObject

A compiled filled profile with rings in world XYZ coordinates.

```typescript theme={null}
interface CompiledPolygonObject {
  kind: 'polygon';
  id: string;
  buildingId: string;
  storeyId: string;
  workingPlaneId: string;
  worldOuterRing: Vec3[];
  worldHoles: Vec3[][];
  color?: string;
  object: PolygonPrimitive;
}
```

### CompiledRectangleObject

A compiled rectangle with its saved mode and projected world boundary.

```typescript theme={null}
interface CompiledRectangleObject {
  kind: 'rectangle';
  id: string;
  buildingId: string;
  storeyId: string;
  workingPlaneId: string;
  mode: 'size' | 'freeform';
  worldOuterRing: Vec3[];
  worldHoles: Vec3[][];
  color?: string;
  object: RectanglePrimitive;
}
```

### CompiledCuboidObject

A native upright body and its authored footprint, with explicit saved ownership.

```typescript theme={null}
interface CompiledCuboidObject {
  kind: 'cuboid';
  id: string;
  buildingId: string;
  storeyId: string;
  workingPlaneId: string;
  mode: 'size' | 'freeform';
  height: number;
  worldOuterRing: Vec3[];
  worldHoles: Vec3[][];
  color?: string;
  object: AnalyticSolid & {
    ogType: string;
  };
}
```

### CompiledCylinderObject

A native circular body with explicit authored ownership and world placement.

```typescript theme={null}
interface CompiledCylinderObject {
  kind: 'cylinder';
  id: string;
  buildingId: string;
  storeyId: string;
  workingPlaneId: string;
  worldCenter: Vec3;
  radius: number;
  height: number;
  color?: string;
  object: AnalyticSolid & {
    ogType: string;
  };
}
```

### SpatialStructureScope

Property-bearing owner in a BuildingModel spatial hierarchy.

```typescript theme={null}
interface SpatialStructureScope {
  id: string;
  name: string;
  elevation?: number;
  propertySets?: PropertySets;
}
```

### SpatialStructureBuilding

```typescript theme={null}
interface SpatialStructureBuilding extends SpatialStructureScope {
  storeys: SpatialStructureScope[];
}
```

## Related

* [`ArcPrimitive`](/floorkit/api/primitives/arc-primitive)
* [`LinePrimitive`](/floorkit/api/primitives/line-primitive)
* [`OPElement`](/floorkit/api/architecture/op-element)
* [`PolygonPrimitive`](/floorkit/api/primitives/polygon-primitive)
* [`PolylinePrimitive`](/floorkit/api/primitives/polyline-primitive)
* [`RectanglePrimitive`](/floorkit/api/primitives/rectangle-primitive)
* [`WallNetwork`](/floorkit/api/architecture/wall-network)
* [`BmColor`](/floorkit/api/architecture/validate-building-model#bmcolor)
* [`BmIssue`](/floorkit/api/architecture/validate-building-model#bmissue)
* [`BuildingModel`](/floorkit/api/architecture/validate-building-model#buildingmodel)
* [`BuildingSourceRef`](/floorkit/api/drawings/plan-drawing-extractor#buildingsourceref)
* [`OpenElementDefinition`](/floorkit/api/architecture/open-element#openelementdefinition)
* [`PropertySets`](/floorkit/api/architecture/op-element#propertysets)
* [`Vec3`](/floorkit/api/architecture/wall#vec3)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.