@ifc-lite/flow-nodes 0.3.1 → 0.5.0

package/dist/speckle/client.js

@@ -0,0 +1,153 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * The Speckle wire protocol, spoken ONLY through `coreNetworkRequest` (the
+ * gated, https-only, exact-host-grant request function every flow node
+ * uses). Nothing here calls `fetch`: the transport comes from the host, and
+ * the grant check runs before any byte moves.
+ *
+ * Three requests, the same three Speckle's own object loader makes:
+ *
+ *   POST /graphql                               version → `referencedObject` (root object id)
+ *   GET  /objects/<project>/<object>/single     the root object alone
+ *   POST /api/getobjects/<project>              a batch of objects by id, one `id\tjson` per line
+ *
+ * The walk is lazy and iterative: a round fetches only the ids the previous
+ * round referenced and has not yet seen, so display meshes and their data
+ * chunks (the bulk of any commit) are never downloaded — `speckle.receive`
+ * does not write them (see `mapping.ts`). A visited set stops cycles and
+ * revisits, and `maxObjects` bounds the total, failing loudly when reached.
+ */
+import { coreNetworkRequest, NetworkDeniedError } from '@ifc-lite/sandbox';
+/** Keys whose values are display geometry: never followed, never fetched. */
+export const DISPLAY_KEYS = new Set(['displayValue', '@displayValue', 'displayMesh', '@displayMesh']);
+const BATCH_SIZE = 500;
+function headers(opts, extra) {
+    const h = { ...extra };
+    if (opts.token && opts.token.length > 0)
+        h.Authorization = `Bearer ${opts.token}`;
+    return h;
+}
+async function request(opts, url, method, extra, body) {
+    let res;
+    try {
+        res = await coreNetworkRequest({ url, method, headers: headers(opts, extra), body, timeoutMs: opts.timeoutMs, maxBytes: opts.maxBytes, signal: opts.signal }, opts.grants, opts.transport);
+    }
+    catch (err) {
+        if (err instanceof NetworkDeniedError)
+            throw new Error(`speckle.receive: ${err.message}`);
+        throw err;
+    }
+    if (res.status === 401 || res.status === 403) {
+        throw new Error(`speckle.receive: ${method} ${url} was refused (${res.status}); the project is private or the token lacks access`);
+    }
+    if (res.status < 200 || res.status >= 300)
+        throw new Error(`speckle.receive: ${method} ${url} failed with status ${res.status}`);
+    if (res.truncated)
+        throw new Error(`speckle.receive: the response from ${url} exceeded maxBytes (${opts.maxBytes}); raise maxBytes to receive this model`);
+    return res.body;
+}
+function parseJson(text, what) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`speckle.receive: ${what} is not valid JSON`);
+    }
+}
+const VERSION_QUERY = 'query ($projectId: String!, $versionId: String!) { project(id: $projectId) { version(id: $versionId) { id referencedObject } } }';
+const LATEST_QUERY = 'query ($projectId: String!, $modelId: String!) { project(id: $projectId) { model(id: $modelId) { versions(limit: 1) { items { id referencedObject } } } } }';
+/** The root object id a target points at, and the version it came from (if any). */
+export async function resolveRoot(opts, target) {
+    if (target.kind === 'object')
+        return { objectId: target.objectId };
+    const pinned = target.versionId !== undefined;
+    const body = JSON.stringify(pinned
+        ? { query: VERSION_QUERY, variables: { projectId: target.projectId, versionId: target.versionId } }
+        : { query: LATEST_QUERY, variables: { projectId: target.projectId, modelId: target.modelId } });
+    const text = await request(opts, `${target.server}/graphql`, 'POST', { 'Content-Type': 'application/json', Accept: 'application/json' }, body);
+    const res = parseJson(text, 'the GraphQL response');
+    if (res.errors && res.errors.length > 0) {
+        throw new Error(`speckle.receive: the server answered the version query with an error: ${res.errors.map((e) => e.message ?? '?').join('; ')}`);
+    }
+    const version = pinned ? res.data?.project?.version : res.data?.project?.model?.versions?.items?.[0];
+    if (!version) {
+        throw new Error(pinned ? `speckle.receive: version ${target.versionId} was not found in project ${target.projectId}` : `speckle.receive: model ${target.modelId} has no versions`);
+    }
+    if (typeof version.referencedObject !== 'string' || version.referencedObject.length === 0) {
+        throw new Error(`speckle.receive: version ${version.id} carries no referencedObject`);
+    }
+    return { objectId: version.referencedObject, versionId: version.id };
+}
+/** Every `referencedId` in an object's own JSON tree, except under display keys. */
+export function referencedIds(value, out = new Set()) {
+    const stack = [value];
+    while (stack.length > 0) {
+        const v = stack.pop();
+        if (Array.isArray(v)) {
+            for (const x of v)
+                stack.push(x);
+        }
+        else if (v !== null && typeof v === 'object') {
+            const o = v;
+            if (typeof o.referencedId === 'string')
+                out.add(o.referencedId);
+            for (const [k, child] of Object.entries(o)) {
+                if (k === '__closure' || DISPLAY_KEYS.has(k))
+                    continue;
+                if (child !== null && typeof child === 'object')
+                    stack.push(child);
+            }
+        }
+    }
+    return out;
+}
+function asObject(value, what) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || typeof value.id !== 'string') {
+        throw new Error(`speckle.receive: ${what} is not a Speckle object`);
+    }
+    return value;
+}
+async function fetchBatch(opts, target, ids) {
+    const text = await request(opts, `${target.server}/api/getobjects/${encodeURIComponent(target.projectId)}`, 'POST', { 'Content-Type': 'application/json', Accept: 'text/plain' }, JSON.stringify({ objects: JSON.stringify(ids) }));
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        const tab = line.indexOf('\t');
+        out.push(asObject(parseJson(tab >= 0 ? line.slice(tab + 1) : line, `object line "${line.slice(0, 40)}"`), 'a batch line'));
+    }
+    return out;
+}
+/**
+ * Fetch the root object and everything it references (display geometry
+ * excepted), keyed by id. Throws when an id the graph references is not
+ * returned by the server, or when `maxObjects` is reached.
+ */
+export async function fetchObjectGraph(opts, target, rootId) {
+    const objects = new Map();
+    const rootText = await request(opts, `${target.server}/objects/${encodeURIComponent(target.projectId)}/${encodeURIComponent(rootId)}/single`, 'GET', { Accept: 'text/plain' });
+    const root = asObject(parseJson(rootText, `root object ${rootId}`), `root object ${rootId}`);
+    objects.set(rootId, root);
+    let frontier = [...referencedIds(root)].filter((id) => !objects.has(id));
+    while (frontier.length > 0) {
+        if (objects.size + frontier.length > opts.maxObjects) {
+            throw new Error(`speckle.receive: the model references more than maxObjects (${opts.maxObjects}) objects; raise maxObjects to receive it`);
+        }
+        const next = new Set();
+        for (let i = 0; i < frontier.length; i += BATCH_SIZE) {
+            const ids = frontier.slice(i, i + BATCH_SIZE);
+            for (const obj of await fetchBatch(opts, target, ids))
+                objects.set(obj.id, obj);
+            const missing = ids.filter((id) => !objects.has(id));
+            if (missing.length > 0)
+                throw new Error(`speckle.receive: the server did not return ${missing.length} referenced object(s), e.g. ${missing[0]}`);
+            for (const id of ids)
+                referencedIds(objects.get(id), next);
+        }
+        frontier = [...next].filter((id) => !objects.has(id));
+    }
+    return objects;
+}
+//# sourceMappingURL=client.js.map

package/dist/speckle/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/speckle/client.ts"],"names":[],"mappings":"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"}

package/dist/speckle/geometry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reading Speckle geometry primitives into metres: points, straight lines,
+ * and polygonal outlines. Anything that is not exactly one of those (an
+ * arc, a NURBS curve, a gap between polycurve segments) is reported as
+ * `undefined` with a reason, so the caller refuses the element rather than
+ * approximating its shape.
+ */
+import type { SpeckleObject } from './client.js';
+export type Vec3 = [number, number, number];
+export type Resolver = (value: unknown) => Record<string, unknown> | undefined;
+/** Resolve a detached `{ speckle_type: 'reference', referencedId }` against the fetched graph; inline objects pass through. */
+export declare function resolverFor(objects: ReadonlyMap<string, SpeckleObject>): Resolver;
+/** `speckle_type` is a `:`-joined inheritance chain; true when `base` is one of its links. */
+export declare function isA(obj: Record<string, unknown> | undefined, base: string): boolean;
+/** The most-derived link of the chain, the name refusals use. */
+export declare function leafType(obj: Record<string, unknown>): string;
+/** A Speckle point in metres; its own `units` win over the owner's. */
+export declare function pointOf(resolve: Resolver, value: unknown, ownerUnits: unknown): Vec3 | undefined;
+/** Start/end of an `Objects.Geometry.Line`, in metres. */
+export declare function lineOf(resolve: Resolver, value: unknown, ownerUnits: unknown): {
+    start: Vec3;
+    end: Vec3;
+} | {
+    reason: string;
+};
+/**
+ * The vertices of a closed, planar-horizontal outline (a `Polycurve` of
+ * `Line` segments, or a closed `Polyline`), in metres, without the closing
+ * duplicate. Everything else — arcs, open or gapped outlines, outlines whose
+ * vertices do not share one elevation — returns a reason.
+ */
+export declare function outlineOf(resolve: Resolver, value: unknown, ownerUnits: unknown): {
+    points: Vec3[];
+} | {
+    reason: string;
+};
+//# sourceMappingURL=geometry.d.ts.map

package/dist/speckle/geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../src/speckle/geometry.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;AAE/E,+HAA+H;AAC/H,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,QAAQ,CAOjF;AAED,8FAA8F;AAC9F,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAK7D;AAOD,uEAAuE;AACvE,wBAAgB,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAMhG;AAED,0DAA0D;AAC1D,wBAAgB,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9H;AAuBD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,IAAI,EAAE,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAgCzH"}

package/dist/speckle/geometry.js

@@ -0,0 +1,126 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { lengthScale } from './units.js';
+/** Resolve a detached `{ speckle_type: 'reference', referencedId }` against the fetched graph; inline objects pass through. */
+export function resolverFor(objects) {
+    return (value) => {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const o = value;
+        if (typeof o.referencedId === 'string')
+            return objects.get(o.referencedId);
+        return o;
+    };
+}
+/** `speckle_type` is a `:`-joined inheritance chain; true when `base` is one of its links. */
+export function isA(obj, base) {
+    return typeof obj?.speckle_type === 'string' && obj.speckle_type.split(':').includes(base);
+}
+/** The most-derived link of the chain, the name refusals use. */
+export function leafType(obj) {
+    const t = typeof obj.speckle_type === 'string' ? obj.speckle_type : 'Base';
+    const chain = t.split(':');
+    const leaf = chain[chain.length - 1];
+    return leaf.slice(leaf.lastIndexOf('.') + 1);
+}
+/** `a Line`, `an Arc`. */
+const withArticle = (word) => `${/^[AEIOU]/i.test(word) ? 'an' : 'a'} ${word}`;
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+/** A Speckle point in metres; its own `units` win over the owner's. */
+export function pointOf(resolve, value, ownerUnits) {
+    const p = resolve(value);
+    if (!p || !finite(p.x) || !finite(p.y) || !finite(p.z))
+        return undefined;
+    const s = lengthScale(p.units) ?? lengthScale(ownerUnits);
+    if (s === undefined)
+        return undefined;
+    return [p.x * s, p.y * s, p.z * s];
+}
+/** Start/end of an `Objects.Geometry.Line`, in metres. */
+export function lineOf(resolve, value, ownerUnits) {
+    const line = resolve(value);
+    if (!line)
+        return { reason: 'has no location line' };
+    if (!isA(line, 'Objects.Geometry.Line'))
+        return { reason: `has ${withArticle(leafType(line))} location, not a straight line` };
+    const units = line.units ?? ownerUnits;
+    const start = pointOf(resolve, line.start, units);
+    const end = pointOf(resolve, line.end, units);
+    if (!start || !end)
+        return { reason: 'has a location line without numeric points in a length unit' };
+    return { start, end };
+}
+/** A flat number list, possibly chunked into `DataChunk` references. */
+function numbers(resolve, value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const item of value) {
+        if (finite(item))
+            out.push(item);
+        else {
+            const chunk = resolve(item);
+            if (!chunk || !Array.isArray(chunk.data) || !chunk.data.every(finite))
+                return undefined;
+            out.push(...chunk.data);
+        }
+    }
+    return out;
+}
+const TOL = 1e-4; // metres: 0.1 mm
+function near(a, b) {
+    return Math.abs(a[0] - b[0]) <= TOL && Math.abs(a[1] - b[1]) <= TOL && Math.abs(a[2] - b[2]) <= TOL;
+}
+/**
+ * The vertices of a closed, planar-horizontal outline (a `Polycurve` of
+ * `Line` segments, or a closed `Polyline`), in metres, without the closing
+ * duplicate. Everything else — arcs, open or gapped outlines, outlines whose
+ * vertices do not share one elevation — returns a reason.
+ */
+export function outlineOf(resolve, value, ownerUnits) {
+    const curve = resolve(value);
+    if (!curve)
+        return { reason: 'has no outline' };
+    const units = curve.units ?? ownerUnits;
+    let points = [];
+    if (isA(curve, 'Objects.Geometry.Polycurve')) {
+        const segments = Array.isArray(curve.segments) ? curve.segments : [];
+        for (const [i, seg] of segments.entries()) {
+            const line = lineOf(resolve, seg, units);
+            if ('reason' in line) {
+                const s = resolve(seg);
+                return { reason: `has an outline with ${withArticle(s ? leafType(s) : 'missing')} segment, not only straight lines` };
+            }
+            if (i > 0 && !near(points[points.length - 1], line.start))
+                return { reason: 'has an outline with a gap between segments' };
+            if (i === 0)
+                points.push(line.start);
+            points.push(line.end);
+        }
+    }
+    else if (isA(curve, 'Objects.Geometry.Polyline')) {
+        const flat = numbers(resolve, curve.value);
+        const s = lengthScale(units);
+        if (!flat || flat.length % 3 !== 0 || s === undefined)
+            return { reason: 'has a polyline outline without numeric coordinates in a length unit' };
+        for (let i = 0; i < flat.length; i += 3)
+            points.push([flat[i] * s, flat[i + 1] * s, flat[i + 2] * s]);
+        if (curve.closed !== true && !(points.length > 1 && near(points[0], points[points.length - 1])))
+            return { reason: 'has an open polyline outline' };
+        if (curve.closed === true)
+            points.push(points[0]);
+    }
+    else {
+        return { reason: `has ${withArticle(leafType(curve))} outline, not line segments` };
+    }
+    if (points.length < 2 || !near(points[0], points[points.length - 1]))
+        return { reason: 'has an outline that does not close' };
+    points = points.slice(0, -1);
+    if (points.length < 3)
+        return { reason: 'has an outline with fewer than three vertices' };
+    if (points.some((p) => Math.abs(p[2] - points[0][2]) > TOL))
+        return { reason: 'has an outline that is not horizontal (sloped)' };
+    return { points };
+}
+//# sourceMappingURL=geometry.js.map

package/dist/speckle/geometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.js","sourceRoot":"","sources":["../../src/speckle/geometry.ts"],"names":[],"mappings":"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"}

package/dist/speckle/mapping.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Speckle object graph → planned IFC elements (mapping v1). Pure: no I/O,
+ * no model access. See docs/architecture/speckle-mapping.md for the table.
+ *
+ *   Objects.BuiltElements.Wall    → IfcWall   (straight location line, height, WALL_ATTR_WIDTH_PARAM)
+ *   Objects.BuiltElements.Floor   → IfcSlab   (flat polygonal outline, FLOOR_ATTR_THICKNESS_PARAM)
+ *   Objects.BuiltElements.Roof    → IfcRoof   (flat polygonal footprint, ROOF_ATTR_THICKNESS_PARAM)
+ *   Objects.BuiltElements.Column  → IfcColumn (vertical, unrotated location line, `b` × `h`)
+ *   Objects.BuiltElements.Beam    → IfcBeam   (straight location line, `b` × `h`)
+ *
+ * The body is rebuilt parametrically through the same `bim.store.add*`
+ * builders `model.addElement` uses; `bim.store` has no tessellated-body
+ * writer, so display meshes are counted and reported, never written.
+ * Coordinates are made relative to the element's own Speckle level and
+ * written into the one target storey.
+ *
+ * The walk is iterative with a global visited set (the output for an id is
+ * a pure function of that id, so revisits are skipped, not re-counted).
+ */
+import type { AddBeamInStoreParams, AddColumnInStoreParams, AddRoofPolygonParams, AddSlabPolygonParams, AddWallInStoreParams } from '@ifc-lite/sdk';
+import type { SpeckleObject } from './client.js';
+import { type ParamValue } from './parameters.js';
+import { RefusalLog, type SpeckleRefusal } from './refusals.js';
+export declare const PSET_SOURCE = "Speckle_Source";
+export declare const PSET_TYPE = "Speckle_TypeParameters";
+export declare const PSET_INSTANCE = "Speckle_InstanceParameters";
+export type PlannedElement = {
+    /** Stable identity across versions: the Revit `applicationId`, else the Speckle id. */
+    readonly key: string;
+    readonly speckleType: string;
+    readonly speckleId: string;
+    readonly psets: Readonly<Record<string, Readonly<Record<string, ParamValue>>>>;
+    readonly displayMeshes: number;
+    readonly skippedEntries: number;
+} & ({
+    readonly kind: 'wall';
+    readonly params: AddWallInStoreParams;
+} | {
+    readonly kind: 'slab';
+    readonly params: AddSlabPolygonParams;
+} | {
+    readonly kind: 'roof';
+    readonly params: AddRoofPolygonParams;
+} | {
+    readonly kind: 'column';
+    readonly params: AddColumnInStoreParams;
+} | {
+    readonly kind: 'beam';
+    readonly params: AddBeamInStoreParams;
+});
+export interface MappingOptions {
+    /** Only elements on this Speckle level (by name); empty = every level. */
+    readonly level?: string;
+}
+export interface MappingResult {
+    readonly planned: PlannedElement[];
+    readonly refusals: RefusalLog;
+}
+/** Walk the fetched graph from its root and plan every mappable element. */
+export declare function mapSpeckleGraph(objects: ReadonlyMap<string, SpeckleObject>, rootId: string, opts?: MappingOptions): MappingResult;
+export type { SpeckleRefusal };
+//# sourceMappingURL=mapping.d.ts.map

package/dist/speckle/mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../../src/speckle/mapping.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACpJ,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAuC,KAAK,UAAU,EAAyB,MAAM,iBAAiB,CAAC;AAC9G,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAA6B,MAAM,eAAe,CAAC;AAG3F,eAAO,MAAM,WAAW,mBAAmB,CAAC;AAC5C,eAAO,MAAM,SAAS,2BAA2B,CAAC;AAClD,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAI1D,MAAM,MAAM,cAAc,GAAG;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC,GAAG,CACA;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CACnE,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;CAC/B;AAiKD,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CAwBrI;AAED,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/speckle/mapping.js

@@ -0,0 +1,208 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { DISPLAY_KEYS } from './client.js';
+import { isA, leafType, lineOf, outlineOf, resolverFor } from './geometry.js';
+import { dimension, psetRows, readParameters } from './parameters.js';
+import { RefusalLog } from './refusals.js';
+import { lengthScale } from './units.js';
+export const PSET_SOURCE = 'Speckle_Source';
+export const PSET_TYPE = 'Speckle_TypeParameters';
+export const PSET_INSTANCE = 'Speckle_InstanceParameters';
+const KINDS = [
+    ['Objects.BuiltElements.Wall', 'wall'],
+    ['Objects.BuiltElements.Floor', 'slab'],
+    ['Objects.BuiltElements.Roof', 'roof'],
+    ['Objects.BuiltElements.Column', 'column'],
+    ['Objects.BuiltElements.Beam', 'beam'],
+];
+const kindOf = (o) => KINDS.find(([base]) => isA(o, base))?.[1];
+function isContainer(o) {
+    const t = typeof o.speckle_type === 'string' ? o.speckle_type : 'Base';
+    return t === 'Base' || isA(o, 'Speckle.Core.Models.Collections.Collection') || t.startsWith('Objects.Organization.');
+}
+/** Child slots a container is walked through: `elements` and dynamic `@`-detached members. */
+function childSlots(o) {
+    const out = [];
+    for (const [k, v] of Object.entries(o)) {
+        if (DISPLAY_KEYS.has(k) || (k !== 'elements' && !k.startsWith('@')))
+            continue;
+        if (Array.isArray(v))
+            out.push(...v);
+        else if (v !== null && typeof v === 'object')
+            out.push(v);
+    }
+    return out;
+}
+/** Display geometry under every key the client skips; a bare object counts as one. */
+function displayCount(o) {
+    let n = 0;
+    for (const key of DISPLAY_KEYS) {
+        const v = o[key];
+        if (Array.isArray(v))
+            n += v.length;
+        else if (v !== null && typeof v === 'object')
+            n += 1;
+    }
+    return n;
+}
+class Refused extends Error {
+    reason;
+    constructor(reason, detail) {
+        super(detail);
+        this.reason = reason;
+    }
+}
+const TOL = 1e-4;
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : v === null || v === undefined ? undefined : String(v));
+const xy = (p) => [p[0], p[1]];
+function required(params, internal, label) {
+    const d = dimension(params, internal);
+    if ('reason' in d)
+        throw new Refused('missing-dimension', `${d.reason} (${label})`);
+    return d.value;
+}
+function line(resolve, o) {
+    const l = lineOf(resolve, o.baseLine, o.units);
+    if ('reason' in l)
+        throw new Refused('geometry', l.reason);
+    return l;
+}
+function flatOutline(resolve, o) {
+    if (typeof o.slope === 'number' && Math.abs(o.slope) > 1e-9)
+        throw new Refused('geometry', 'is sloped; v1 writes flat slabs and roofs only');
+    if (Array.isArray(o.voids) && o.voids.length > 0)
+        throw new Refused('openings', 'has openings (voids), which a v1 extrusion would fill in');
+    const outline = outlineOf(resolve, o.outline, o.units);
+    if ('reason' in outline)
+        throw new Refused('geometry', outline.reason);
+    return outline.points;
+}
+function plan(resolve, o, kind, params, elevation) {
+    const header = {
+        Name: [str(o.family), str(o.type)].filter((s) => s !== undefined).join(': ') || leafType(o),
+        ObjectType: str(o.type),
+        Tag: str(o.elementId),
+    };
+    const local = (p) => [p[0], p[1], p[2] - elevation];
+    switch (kind) {
+        case 'wall': {
+            const { start, end } = line(resolve, o);
+            if (Math.abs(start[2] - end[2]) > TOL)
+                throw new Refused('geometry', 'has a location line that is not horizontal');
+            const height = typeof o.height === 'number' && o.height > 0 ? o.height * (lengthScale(o.units) ?? Number.NaN) : Number.NaN;
+            if (!Number.isFinite(height))
+                throw new Refused('missing-dimension', 'no positive height');
+            return { kind, params: { ...header, Start: local(start), End: local(end), Height: height, Thickness: required(params, 'WALL_ATTR_WIDTH_PARAM', 'Width') } };
+        }
+        case 'slab': {
+            const points = flatOutline(resolve, o);
+            const thickness = required(params, 'FLOOR_ATTR_THICKNESS_PARAM', 'Thickness');
+            // A Revit floor's outline is its top face at the level: the slab hangs below it.
+            return { kind, params: { ...header, Profile: 'polygon', OuterCurve: points.map(xy), Position: [0, 0, points[0][2] - elevation - thickness], Thickness: thickness } };
+        }
+        case 'roof': {
+            if (isA(o, 'Objects.BuiltElements.Revit.RevitRoof.RevitExtrusionRoof'))
+                throw new Refused('geometry', 'is an extrusion roof (a profile swept along a path)');
+            const points = flatOutline(resolve, o);
+            const thickness = required(params, 'ROOF_ATTR_THICKNESS_PARAM', 'Thickness');
+            return { kind, params: { ...header, Profile: 'polygon', OuterCurve: points.map(xy), Position: [0, 0, points[0][2] - elevation], Thickness: thickness } };
+        }
+        case 'column': {
+            const { start, end } = line(resolve, o);
+            if (Math.abs(start[0] - end[0]) > TOL || Math.abs(start[1] - end[1]) > TOL)
+                throw new Refused('geometry', 'is slanted; v1 writes vertical columns only');
+            if (typeof o.rotation === 'number' && Math.abs(o.rotation) > 1e-9)
+                throw new Refused('geometry', 'is rotated about its axis, which the column writer cannot express');
+            const base = start[2] <= end[2] ? start : end;
+            const height = Math.abs(end[2] - start[2]);
+            if (height <= TOL)
+                throw new Refused('missing-dimension', 'no height (zero-length location line)');
+            return { kind, params: { ...header, Position: local(base), Height: height, Width: required(params, 'b', 'b'), Depth: required(params, 'h', 'h') } };
+        }
+        case 'beam': {
+            const { start, end } = line(resolve, o);
+            return { kind, params: { ...header, Start: local(start), End: local(end), Width: required(params, 'b', 'b'), Height: required(params, 'h', 'h') } };
+        }
+    }
+}
+function sourcePset(o, levelName) {
+    const rows = { SpeckleId: o.id, SpeckleType: String(o.speckle_type) };
+    const add = (k, v) => {
+        const s = str(v);
+        if (s !== undefined)
+            rows[k] = s;
+    };
+    add('ApplicationId', o.applicationId);
+    add('Category', o.category);
+    add('Family', o.family);
+    add('Type', o.type);
+    add('ElementId', o.elementId);
+    add('Level', levelName);
+    add('SourceUnits', o.units);
+    return rows;
+}
+function mapElement(resolve, o, kind, opts, log, planned) {
+    const type = leafType(o);
+    const level = resolve(o.level);
+    const levelName = str(level?.name);
+    if (opts.level && levelName !== opts.level) {
+        log.add(type, 'other-level', `on level "${levelName ?? '(none)'}", not the requested level "${opts.level}"`, o.id);
+        return;
+    }
+    const scale = lengthScale(o.units);
+    if (scale === undefined) {
+        log.add(type, 'no-units', `units "${String(o.units ?? '(none)')}" is not a length unit`, o.id);
+        return;
+    }
+    const elevation = typeof level?.elevation === 'number' ? level.elevation * (lengthScale(level.units) ?? scale) : 0;
+    const { parameters, skipped } = readParameters(resolve, o);
+    try {
+        const p = plan(resolve, o, kind, parameters, elevation);
+        planned.push({
+            ...p,
+            key: str(o.applicationId) ?? o.id,
+            speckleType: type,
+            speckleId: o.id,
+            psets: { [PSET_SOURCE]: sourcePset(o, levelName), [PSET_TYPE]: psetRows(parameters, 'type'), [PSET_INSTANCE]: psetRows(parameters, 'instance') },
+            displayMeshes: displayCount(o),
+            skippedEntries: skipped,
+        });
+    }
+    catch (err) {
+        if (!(err instanceof Refused))
+            throw err;
+        log.add(type, err.reason, err.message, o.id);
+    }
+}
+/** Walk the fetched graph from its root and plan every mappable element. */
+export function mapSpeckleGraph(objects, rootId, opts = {}) {
+    const resolve = resolverFor(objects);
+    const log = new RefusalLog();
+    const planned = [];
+    const root = objects.get(rootId);
+    if (!root)
+        throw new Error(`speckle.receive: root object ${rootId} was not fetched`);
+    const seen = new Set();
+    const stack = [root];
+    while (stack.length > 0) {
+        const o = resolve(stack.pop());
+        if (!o || typeof o.id !== 'string' || seen.has(o.id))
+            continue;
+        seen.add(o.id);
+        const kind = kindOf(o);
+        if (kind)
+            mapElement(resolve, o, kind, opts, log, planned);
+        else if (!isContainer(o)) {
+            log.add(leafType(o), 'unmapped-type', 'has no v1 mapping', o.id);
+            continue;
+        }
+        // Containers, and hosted elements under a mapped one (a stacked wall's
+        // layers, a wall's doors), are walked in document order.
+        const children = kind ? (Array.isArray(o.elements) ? o.elements : []) : childSlots(o);
+        for (let i = children.length - 1; i >= 0; i--)
+            stack.push(children[i]);
+    }
+    return { planned, refusals: log };
+}
+//# sourceMappingURL=mapping.js.map