brepjs-bim 0.17.2 → 0.19.0

package/README.md

@@ -14,6 +14,13 @@ and serializes the result to a valid **IFC-SPF** file — with a matching import
 Pipeline: **author spec → `BimModel` (typed element + brepjs geometry) → spatial structure +
 property sets + classification → export IFC / COBie, validate, round-trip.**
 
+The declarative entry point is
+[`brepjs-families`](https://www.npmjs.com/package/brepjs-families): author the building as a tree of
+prop-driven components, then `familiesToBim(tree, { project })` projects it onto a `BimModel` with
+stable GlobalIds derived from component key paths. Hand-authoring specs against `BimModel` remains
+the low-level path (and covers elements the declarative route doesn't yet). See the
+[Declarative Models guide](https://brepjs.dev/families/overview).
+
 ## Scope
 
 Parametric authoring of the common IFC4 building elements plus the data layers that make a model

package/dist/brepjs-bim.cjs

@@ -535,7 +535,7 @@ var propertyKeyTypes = /* @__PURE__*/ new Set([
 function escapeRegex(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function clone(inst, def, params) {
+function clone$1(inst, def, params) {
 	const cl = new inst._zod.constr(def ?? inst._zod.def);
 	if (!def || params?.parent) cl._zod.parent = inst;
 	return cl;
@@ -571,7 +571,7 @@ function pick(schema, mask) {
 	const currDef = schema._zod.def;
 	const checks = currDef.checks;
 	if (checks && checks.length > 0) throw new Error(".pick() cannot be used on object schemas containing refinements");
-	return clone(schema, mergeDefs(schema._zod.def, {
+	return clone$1(schema, mergeDefs(schema._zod.def, {
 		get shape() {
 			const newShape = {};
 			for (const key in mask) {
@@ -589,7 +589,7 @@ function omit(schema, mask) {
 	const currDef = schema._zod.def;
 	const checks = currDef.checks;
 	if (checks && checks.length > 0) throw new Error(".omit() cannot be used on object schemas containing refinements");
-	return clone(schema, mergeDefs(schema._zod.def, {
+	return clone$1(schema, mergeDefs(schema._zod.def, {
 		get shape() {
 			const newShape = { ...schema._zod.def.shape };
 			for (const key in mask) {
@@ -610,7 +610,7 @@ function extend(schema, shape) {
 		const existingShape = schema._zod.def.shape;
 		for (const key in shape) if (Object.getOwnPropertyDescriptor(existingShape, key) !== void 0) throw new Error("Cannot overwrite keys on object schemas containing refinements. Use `.safeExtend()` instead.");
 	}
-	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
+	return clone$1(schema, mergeDefs(schema._zod.def, { get shape() {
 		const _shape = {
 			...schema._zod.def.shape,
 			...shape
@@ -621,7 +621,7 @@ function extend(schema, shape) {
 }
 function safeExtend(schema, shape) {
 	if (!isPlainObject(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
-	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
+	return clone$1(schema, mergeDefs(schema._zod.def, { get shape() {
 		const _shape = {
 			...schema._zod.def.shape,
 			...shape
@@ -632,7 +632,7 @@ function safeExtend(schema, shape) {
 }
 function merge(a, b) {
 	if (a._zod.def.checks?.length) throw new Error(".merge() cannot be used on object schemas containing refinements. Use .safeExtend() instead.");
-	return clone(a, mergeDefs(a._zod.def, {
+	return clone$1(a, mergeDefs(a._zod.def, {
 		get shape() {
 			const _shape = {
 				...a._zod.def.shape,
@@ -650,7 +650,7 @@ function merge(a, b) {
 function partial(Class, schema, mask) {
 	const checks = schema._zod.def.checks;
 	if (checks && checks.length > 0) throw new Error(".partial() cannot be used on object schemas containing refinements");
-	return clone(schema, mergeDefs(schema._zod.def, {
+	return clone$1(schema, mergeDefs(schema._zod.def, {
 		get shape() {
 			const oldShape = schema._zod.def.shape;
 			const shape = { ...oldShape };
@@ -673,7 +673,7 @@ function partial(Class, schema, mask) {
 	}));
 }
 function required(Class, schema, mask) {
-	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
+	return clone$1(schema, mergeDefs(schema._zod.def, { get shape() {
 		const oldShape = schema._zod.def.shape;
 		const shape = { ...oldShape };
 		if (mask) for (const key in mask) {
@@ -4042,7 +4042,7 @@ var ZodType = /*@__PURE__*/ $constructor("ZodType", (inst, def) => {
 			return this.check(...chks);
 		},
 		clone(def, params) {
-			return clone(this, def, params);
+			return clone$1(this, def, params);
 		},
 		brand() {
 			return this;
@@ -27735,6 +27735,16 @@ function peelTranslates(node) {
 		moved
 	};
 }
+/** True when the element's transform PROP carries a rotation. The spec path
+*  folds only translations into IfcLocalPlacement (walls orient via `axisX`),
+*  so a tRotate placement would export un-rotated while the viewport shows it
+*  rotated — reject instead of diverging. Rotations a family render bakes
+*  into its own body geometry (e.g. a circular beam oriented along axisX) are
+*  fine: the spec rebuilds that body parametrically from props. */
+function hasRotateOp(el) {
+	const ops = el.props["transform"];
+	return Array.isArray(ops) && ops.some((op) => typeof op === "object" && op !== null && op.op === "rotate");
+}
 /** Fold the resolved geometry's outer translate chain into the spec placement
 *  origin, so IfcLocalPlacement matches the IR world frame no matter where the
 *  transform came from (family-internal or prop-level). */
@@ -27818,6 +27828,36 @@ function addFill(model, fill, input, identity) {
 	}
 	return (0, brepjs.err)(specError("FAMILIES_UNSUPPORTED_FILL", `familiesToBim: no fill mapping for element type '${fill.type}' at '${fill.keyPath}'`));
 }
+/** Materialize an unrouted element's IR and add it as a proxy. The body is
+*  authoritative for a proxy (no parametric spec to diverge from), so baked
+*  transforms — rotations included — are fine here. */
+function addProxyElement(model, el, evaluator) {
+	const evaluated = evaluator.evaluate(el.geometry);
+	if (!evaluated.ok) return (0, brepjs.err)(specError("FAMILIES_PROXY_EVAL_FAILED", `familiesToBim: '${el.keyPath}' failed to materialize for the proxy route: ${evaluated.error.message}`, evaluated.error));
+	let source = evaluated.value;
+	if (!(0, brepjs.isSolid)(source)) {
+		const solids = (0, brepjs.getSolids)(source);
+		const only = solids.length === 1 ? solids[0] : void 0;
+		if (only === void 0) return (0, brepjs.err)(specError("FAMILIES_PROXY_NOT_SOLID", `familiesToBim: '${el.keyPath}' materialized to ${solids.length} solids — a proxy body must be exactly one`));
+		source = only;
+	}
+	const copy = (0, brepjs.clone)(source);
+	if (!copy.ok) return (0, brepjs.err)(specError("FAMILIES_PROXY_EVAL_FAILED", `familiesToBim: '${el.keyPath}' could not copy the materialized body`, copy.error));
+	const valid = (0, brepjs.validSolid)(copy.value);
+	if (!valid.ok) {
+		copy.value[Symbol.dispose]();
+		return (0, brepjs.err)(specError("FAMILIES_PROXY_INVALID", `familiesToBim: '${el.keyPath}' materialized to an invalid solid: ${valid.error}`));
+	}
+	const nameAttr = el.attributes["name"];
+	const materialProp = el.props["materialName"];
+	const specProps = collectSpecProps(el);
+	return model.addProxy({
+		name: typeof nameAttr === "string" ? nameAttr : el.type,
+		solid: valid.value,
+		materialName: typeof materialProp === "string" ? materialProp : specProps["materialName"],
+		customProperties: specProps["customProperties"]
+	}, { stableKey: el.keyPath });
+}
 /** Map a wall's synthesized Opening children onto addDoor/addWindow. The
 *  wall-relative offsets come from the void geometry's frame minus the host's:
 *  exact because both carry the same outer host transform. */
@@ -27890,7 +27930,9 @@ function familiesToBim(root, options) {
 	if (project !== null) model.aggregate(project.localId, siteResult.value);
 	model.aggregate(siteResult.value, buildingId);
 	const idByKeyPath = /* @__PURE__ */ new Map();
-	const walk = (el, storeyId) => {
+	const walk = (el, storeyId, rotated) => {
+		const rotatedHere = rotated || hasRotateOp(el);
+		let proxied = false;
 		let containerId = storeyId;
 		const route = specRoute(el.type);
 		if (el.type === "Storey") {
@@ -27907,6 +27949,7 @@ function familiesToBim(root, options) {
 		} else if (route !== void 0) {
 			const keyed = requireKeyed(el);
 			if (!keyed.ok) return keyed;
+			if (rotatedHere) return (0, brepjs.err)(specError("FAMILIES_UNSUPPORTED_TRANSFORM", `familiesToBim: '${el.keyPath}' carries a rotated placement — the spec path folds only translations into IfcLocalPlacement; orient walls via axisX instead of tRotate`));
 			const voids = el.props["voids"];
 			if (Array.isArray(voids)) {
 				const openings = el.children.filter((c) => c.type === "Opening").length;
@@ -27924,15 +27967,25 @@ function familiesToBim(root, options) {
 				if (!opened.ok) return opened;
 			}
 		} else if (el.type === "Opening") return (0, brepjs.err)(specError("FAMILIES_OPENING_OUTSIDE_WALL", `familiesToBim: opening '${el.keyPath}' is not hosted by a Wall — only wall openings are mapped`));
-		else if (el.type !== "Group" && el.geometry.kind !== "Empty") return (0, brepjs.err)(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}'`));
+		else if (el.type !== "Group" && el.geometry.kind !== "Empty") {
+			if (options.proxyEvaluator === void 0) return (0, brepjs.err)(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}' — add a spec route, or pass proxyEvaluator to export it as an IfcBuildingElementProxy`));
+			const keyed = requireKeyed(el);
+			if (!keyed.ok) return keyed;
+			if (containerId === null) return (0, brepjs.err)(specError("FAMILIES_NO_STOREY", `familiesToBim: '${el.keyPath}' has no Storey ancestor — IFC elements need spatial containment`));
+			const added = addProxyElement(model, el, options.proxyEvaluator);
+			if (!added.ok) return added;
+			model.placeIn(added.value, containerId);
+			idByKeyPath.set(el.keyPath, added.value);
+			proxied = true;
+		}
 		for (const child of el.children) {
-			if (el.type === "Wall" && child.type === "Opening") continue;
-			const r = walk(child, containerId);
+			if ((el.type === "Wall" || proxied) && child.type === "Opening") continue;
+			const r = walk(child, containerId, rotatedHere);
 			if (!r.ok) return r;
 		}
 		return (0, brepjs.ok)(void 0);
 	};
-	const walked = walk(root, null);
+	const walked = walk(root, null, false);
 	if (!walked.ok) {
 		model[Symbol.dispose]();
 		return walked;

package/dist/brepjs-bim.js

@@ -1,4 +1,4 @@
-import { addHoles, applyMatrix, autoHeal, box, castShape, convexHull, cut, err, extrude, fuse, getKernel, isClosedWire, isOk, isPlanarWire, isSolid, isValid, isValidSolid, measureVolume, mesh, ok, outerWire, polygon, revolve, rotate, validSolid } from "brepjs";
+import { addHoles, applyMatrix, autoHeal, box, castShape, clone, convexHull, cut, err, extrude, fuse, getKernel, getSolids, isClosedWire, isOk, isPlanarWire, isSolid, isValid, isValidSolid, measureVolume, mesh, ok, outerWire, polygon, revolve, rotate, validSolid } from "brepjs";
 import * as WebIFC from "web-ifc";
 import { Handle, IfcAPI } from "web-ifc";
 //#region src/identity/ifcGuid.ts
@@ -512,7 +512,7 @@ var propertyKeyTypes = /* @__PURE__*/ new Set([
 function escapeRegex(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function clone(inst, def, params) {
+function clone$1(inst, def, params) {
 	const cl = new inst._zod.constr(def ?? inst._zod.def);
 	if (!def || params?.parent) cl._zod.parent = inst;
 	return cl;
@@ -548,7 +548,7 @@ function pick(schema, mask) {
 	const currDef = schema._zod.def;
 	const checks = currDef.checks;
 	if (checks && checks.length > 0) throw new Error(".pick() cannot be used on object schemas containing refinements");
-	return clone(schema, mergeDefs(schema._zod.def, {
+	return clone$1(schema, mergeDefs(schema._zod.def, {
 		get shape() {
 			const newShape = {};
 			for (const key in mask) {
@@ -566,7 +566,7 @@ function omit(schema, mask) {
 	const currDef = schema._zod.def;
 	const checks = currDef.checks;
 	if (checks && checks.length > 0) throw new Error(".omit() cannot be used on object schemas containing refinements");
-	return clone(schema, mergeDefs(schema._zod.def, {
+	return clone$1(schema, mergeDefs(schema._zod.def, {
 		get shape() {
 			const newShape = { ...schema._zod.def.shape };
 			for (const key in mask) {
@@ -587,7 +587,7 @@ function extend(schema, shape) {
 		const existingShape = schema._zod.def.shape;
 		for (const key in shape) if (Object.getOwnPropertyDescriptor(existingShape, key) !== void 0) throw new Error("Cannot overwrite keys on object schemas containing refinements. Use `.safeExtend()` instead.");
 	}
-	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
+	return clone$1(schema, mergeDefs(schema._zod.def, { get shape() {
 		const _shape = {
 			...schema._zod.def.shape,
 			...shape
@@ -598,7 +598,7 @@ function extend(schema, shape) {
 }
 function safeExtend(schema, shape) {
 	if (!isPlainObject(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
-	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
+	return clone$1(schema, mergeDefs(schema._zod.def, { get shape() {
 		const _shape = {
 			...schema._zod.def.shape,
 			...shape
@@ -609,7 +609,7 @@ function safeExtend(schema, shape) {
 }
 function merge(a, b) {
 	if (a._zod.def.checks?.length) throw new Error(".merge() cannot be used on object schemas containing refinements. Use .safeExtend() instead.");
-	return clone(a, mergeDefs(a._zod.def, {
+	return clone$1(a, mergeDefs(a._zod.def, {
 		get shape() {
 			const _shape = {
 				...a._zod.def.shape,
@@ -627,7 +627,7 @@ function merge(a, b) {
 function partial(Class, schema, mask) {
 	const checks = schema._zod.def.checks;
 	if (checks && checks.length > 0) throw new Error(".partial() cannot be used on object schemas containing refinements");
-	return clone(schema, mergeDefs(schema._zod.def, {
+	return clone$1(schema, mergeDefs(schema._zod.def, {
 		get shape() {
 			const oldShape = schema._zod.def.shape;
 			const shape = { ...oldShape };
@@ -650,7 +650,7 @@ function partial(Class, schema, mask) {
 	}));
 }
 function required(Class, schema, mask) {
-	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
+	return clone$1(schema, mergeDefs(schema._zod.def, { get shape() {
 		const oldShape = schema._zod.def.shape;
 		const shape = { ...oldShape };
 		if (mask) for (const key in mask) {
@@ -4019,7 +4019,7 @@ var ZodType = /*@__PURE__*/ $constructor("ZodType", (inst, def) => {
 			return this.check(...chks);
 		},
 		clone(def, params) {
-			return clone(this, def, params);
+			return clone$1(this, def, params);
 		},
 		brand() {
 			return this;
@@ -27712,6 +27712,16 @@ function peelTranslates(node) {
 		moved
 	};
 }
+/** True when the element's transform PROP carries a rotation. The spec path
+*  folds only translations into IfcLocalPlacement (walls orient via `axisX`),
+*  so a tRotate placement would export un-rotated while the viewport shows it
+*  rotated — reject instead of diverging. Rotations a family render bakes
+*  into its own body geometry (e.g. a circular beam oriented along axisX) are
+*  fine: the spec rebuilds that body parametrically from props. */
+function hasRotateOp(el) {
+	const ops = el.props["transform"];
+	return Array.isArray(ops) && ops.some((op) => typeof op === "object" && op !== null && op.op === "rotate");
+}
 /** Fold the resolved geometry's outer translate chain into the spec placement
 *  origin, so IfcLocalPlacement matches the IR world frame no matter where the
 *  transform came from (family-internal or prop-level). */
@@ -27795,6 +27805,36 @@ function addFill(model, fill, input, identity) {
 	}
 	return err(specError("FAMILIES_UNSUPPORTED_FILL", `familiesToBim: no fill mapping for element type '${fill.type}' at '${fill.keyPath}'`));
 }
+/** Materialize an unrouted element's IR and add it as a proxy. The body is
+*  authoritative for a proxy (no parametric spec to diverge from), so baked
+*  transforms — rotations included — are fine here. */
+function addProxyElement(model, el, evaluator) {
+	const evaluated = evaluator.evaluate(el.geometry);
+	if (!evaluated.ok) return err(specError("FAMILIES_PROXY_EVAL_FAILED", `familiesToBim: '${el.keyPath}' failed to materialize for the proxy route: ${evaluated.error.message}`, evaluated.error));
+	let source = evaluated.value;
+	if (!isSolid(source)) {
+		const solids = getSolids(source);
+		const only = solids.length === 1 ? solids[0] : void 0;
+		if (only === void 0) return err(specError("FAMILIES_PROXY_NOT_SOLID", `familiesToBim: '${el.keyPath}' materialized to ${solids.length} solids — a proxy body must be exactly one`));
+		source = only;
+	}
+	const copy = clone(source);
+	if (!copy.ok) return err(specError("FAMILIES_PROXY_EVAL_FAILED", `familiesToBim: '${el.keyPath}' could not copy the materialized body`, copy.error));
+	const valid = validSolid(copy.value);
+	if (!valid.ok) {
+		copy.value[Symbol.dispose]();
+		return err(specError("FAMILIES_PROXY_INVALID", `familiesToBim: '${el.keyPath}' materialized to an invalid solid: ${valid.error}`));
+	}
+	const nameAttr = el.attributes["name"];
+	const materialProp = el.props["materialName"];
+	const specProps = collectSpecProps(el);
+	return model.addProxy({
+		name: typeof nameAttr === "string" ? nameAttr : el.type,
+		solid: valid.value,
+		materialName: typeof materialProp === "string" ? materialProp : specProps["materialName"],
+		customProperties: specProps["customProperties"]
+	}, { stableKey: el.keyPath });
+}
 /** Map a wall's synthesized Opening children onto addDoor/addWindow. The
 *  wall-relative offsets come from the void geometry's frame minus the host's:
 *  exact because both carry the same outer host transform. */
@@ -27867,7 +27907,9 @@ function familiesToBim(root, options) {
 	if (project !== null) model.aggregate(project.localId, siteResult.value);
 	model.aggregate(siteResult.value, buildingId);
 	const idByKeyPath = /* @__PURE__ */ new Map();
-	const walk = (el, storeyId) => {
+	const walk = (el, storeyId, rotated) => {
+		const rotatedHere = rotated || hasRotateOp(el);
+		let proxied = false;
 		let containerId = storeyId;
 		const route = specRoute(el.type);
 		if (el.type === "Storey") {
@@ -27884,6 +27926,7 @@ function familiesToBim(root, options) {
 		} else if (route !== void 0) {
 			const keyed = requireKeyed(el);
 			if (!keyed.ok) return keyed;
+			if (rotatedHere) return err(specError("FAMILIES_UNSUPPORTED_TRANSFORM", `familiesToBim: '${el.keyPath}' carries a rotated placement — the spec path folds only translations into IfcLocalPlacement; orient walls via axisX instead of tRotate`));
 			const voids = el.props["voids"];
 			if (Array.isArray(voids)) {
 				const openings = el.children.filter((c) => c.type === "Opening").length;
@@ -27901,15 +27944,25 @@ function familiesToBim(root, options) {
 				if (!opened.ok) return opened;
 			}
 		} else if (el.type === "Opening") return err(specError("FAMILIES_OPENING_OUTSIDE_WALL", `familiesToBim: opening '${el.keyPath}' is not hosted by a Wall — only wall openings are mapped`));
-		else if (el.type !== "Group" && el.geometry.kind !== "Empty") return err(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}'`));
+		else if (el.type !== "Group" && el.geometry.kind !== "Empty") {
+			if (options.proxyEvaluator === void 0) return err(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}' — add a spec route, or pass proxyEvaluator to export it as an IfcBuildingElementProxy`));
+			const keyed = requireKeyed(el);
+			if (!keyed.ok) return keyed;
+			if (containerId === null) return err(specError("FAMILIES_NO_STOREY", `familiesToBim: '${el.keyPath}' has no Storey ancestor — IFC elements need spatial containment`));
+			const added = addProxyElement(model, el, options.proxyEvaluator);
+			if (!added.ok) return added;
+			model.placeIn(added.value, containerId);
+			idByKeyPath.set(el.keyPath, added.value);
+			proxied = true;
+		}
 		for (const child of el.children) {
-			if (el.type === "Wall" && child.type === "Opening") continue;
-			const r = walk(child, containerId);
+			if ((el.type === "Wall" || proxied) && child.type === "Opening") continue;
+			const r = walk(child, containerId, rotatedHere);
 			if (!r.ok) return r;
 		}
 		return ok(void 0);
 	};
-	const walked = walk(root, null);
+	const walked = walk(root, null, false);
 	if (!walked.ok) {
 		model[Symbol.dispose]();
 		return walked;

package/dist/familiesAdapter.d.ts

@@ -1,4 +1,4 @@
-import { Result } from 'brepjs';
+import { Result, csg } from 'brepjs';
 import { ResolvedElement } from 'brepjs-families';
 import { BimModel } from './model/bimModel.js';
 import { LocalId } from './identity/localId.js';
@@ -8,6 +8,15 @@ export interface FamiliesToBimOptions {
     readonly project: ProjectSpec;
     readonly siteName?: string | undefined;
     readonly buildingName?: string | undefined;
+    /**
+     * Enables the proxy route: an unrouted geometry-bearing element is
+     * materialized through this evaluator and exported as an
+     * IfcBuildingElementProxy (tessellated, world-frame body). Without it,
+     * unrouted types stay a hard FAMILIES_UNSUPPORTED_TYPE error. The
+     * evaluator's handles stay borrowed; the adapter clones what it hands the
+     * model.
+     */
+    readonly proxyEvaluator?: csg.Evaluator | undefined;
 }
 export interface FamiliesBimResult {
     readonly model: BimModel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brepjs-bim",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "BIM layer for brepjs — IFC4-aligned parametric building elements",
   "keywords": [
     "bim",