@ifc-lite/export 2.0.0 → 2.2.0

package/dist/merged-exporter.d.ts

@@ -6,6 +6,7 @@
  * structure unification, and infrastructure deduplication.
  */
 import type { IfcDataStore } from '@ifc-lite/parser';
+import type { MutablePropertyView } from '@ifc-lite/mutations';
 /**
  * A model to be included in the merge, with its data store and metadata.
  */
@@ -16,6 +17,29 @@ export interface MergeModelInput {
     name: string;
     /** Parsed IFC data store (must have source buffer) */
     dataStore: IfcDataStore;
+    /**
+     * Length unit scale of this model — the factor that converts the model's raw
+     * IFC length values into base SI metres (`1.0` metres, `0.001` millimetres,
+     * `0.3048` feet, …). Optional: when omitted the exporter reads
+     * `dataStore.lengthUnitScale`, falling back to `1.0`.
+     *
+     * The merge compares each model's scale to the first model's to decide
+     * whether it can be folded into the unified project (same unit) or must be
+     * federated as its own project (different unit). See {@link MergedExporter}.
+     */
+    lengthUnitScale?: number;
+    /**
+     * Pending edits for this model — property / attribute / quantity / retype /
+     * positional mutations and overlay-created entities. When present and
+     * non-empty, {@link MergedExporter.exportAsync} bakes them into the model
+     * (via {@link StepExporter}) before merging, so federated export round-trips
+     * edits exactly like single-model export. Empty or absent views cost nothing.
+     *
+     * Only honoured by the async `exportAsync` path: baking re-parses the edited
+     * bytes, which needs the async parser. The synchronous {@link MergedExporter.export}
+     * throws if any model carries pending edits.
+     */
+    mutationView?: MutablePropertyView;
 }
 /**
  * Options for merged STEP export
@@ -38,6 +62,24 @@ export interface MergeExportOptions {
      * - 'keep-first': Keep the first model's IfcProject as the root
      */
     projectStrategy?: 'keep-first';
+    /**
+     * How to reconcile models whose length unit differs from the first model's.
+     *
+     * - `'auto'` (default): unit-aware merge. Models that share the first
+     *   model's length unit are unified into a single `IfcProject` (spatial
+     *   structure and infrastructure deduplicated). A model with a *different*
+     *   length unit is federated — it keeps its own `IfcProject`,
+     *   `IfcUnitAssignment` and representation contexts so its coordinates stay
+     *   correctly scaled, instead of being silently reinterpreted under the
+     *   first model's unit. The output then contains more than one `IfcProject`
+     *   (a deliberate relaxation of the IfcSingleProjectInstance rule, flagged in
+     *   `stats.warnings`) — the only way to preserve mixed units in one file
+     *   without rewriting every length-valued attribute.
+     * - `'assume-shared'`: treat every model as sharing the first model's unit
+     *   (the pre-1332 behaviour). Use only when the caller has already
+     *   normalised units; mixing real units under this mode mis-scales geometry.
+     */
+    unitReconciliation?: 'auto' | 'assume-shared';
     /** Apply visibility filtering to each model before merging */
     visibleOnly?: boolean;
     /** Hidden entity IDs per model (local expressIds) */
@@ -76,20 +118,54 @@ export interface MergeExportResult {
         totalEntityCount: number;
         /** File size in bytes */
         fileSize: number;
+        /**
+         * Number of models federated as their own IfcProject because their length
+         * unit differed from the first model's. 0 means a single unified project.
+         */
+        federatedModelCount: number;
+        /**
+         * Human-readable advisories about the merge (empty on a clean single-unit
+         * merge). Notably flags when federation produced more than one IfcProject,
+         * which intentionally relaxes the IfcSingleProjectInstance schema rule.
+         */
+        warnings: string[];
     };
 }
 /**
  * Merges multiple IFC models into a single STEP file.
  *
  * Uses the same approach as IfcOpenShell's MergeProjects recipe, extended
- * with spatial hierarchy unification:
+ * with spatial hierarchy unification and unit-aware federation:
  * 1. First model's entities use their original IDs
  * 2. Subsequent models' IDs are offset to avoid collisions
- * 3. IfcProject is unified — all references remapped to the first model's project
- * 4. Spatial structure (Site, Building, Storey) is unified by name/elevation:
- *    matching entities are remapped to the first model's equivalents so that
- *    products from all models end up in the same unified tree
- * 5. Duplicate entities and shared infrastructure (units, contexts) are skipped
+ * 3. A model that shares the first model's length unit is *unified*: its
+ *    IfcProject is remapped to the first model's, spatial structure (Site,
+ *    Building, Storey) is unified by name/elevation, and shared infrastructure
+ *    (units, contexts) is deduplicated.
+ * 4. A model with a *different* length unit is *federated*: it keeps its own
+ *    IfcProject, IfcUnitAssignment and representation contexts, so its raw
+ *    coordinates remain correctly scaled rather than being reinterpreted under
+ *    the first model's unit (the mis-scale bug, issue #1332).
+ * 5. GlobalIds are reconciled, not blindly duplicated: a non-relationship
+ *    rooted entity that repeats a GlobalId already emitted *in the same unit
+ *    space* is unified (references remapped to the one instance). Otherwise —
+ *    a federated/different-unit instance, or an objectified relationship whose
+ *    payload (RelatedObjects) may differ — it is kept and re-stamped with a
+ *    fresh deterministic GlobalId so the file has no duplicate-GlobalId errors
+ *    and no relationship membership is lost.
+ *
+ * Conformance trade-off: when federation triggers, the file contains more than
+ * one IfcProject, which intentionally relaxes the IfcSingleProjectInstance
+ * EXPRESS rule (SIZEOF(IfcProject) <= 1). This is the only way to keep two
+ * different length units in one STEP file without rewriting every length-valued
+ * coordinate, and it is strictly better than the previous silent mis-scale.
+ * `MergeExportResult.stats.warnings` flags it; pass
+ * `unitReconciliation: 'assume-shared'` to force a single project when units
+ * are already normalised.
+ *
+ * Limitation: federation only unifies a model against the *first* model's unit
+ * group. Two non-first models that share a unit different from the first are
+ * each kept as independent projects (correct, just less deduplicated).
  */
 export declare class MergedExporter {
     private models;
@@ -101,6 +177,94 @@ export declare class MergedExporter {
      * responsive during large merged exports.
      */
     exportAsync(options: MergeExportOptions): Promise<MergeExportResult>;
+    /**
+     * Bake each model's pending edits into its source bytes before merging.
+     *
+     * A model with a non-empty {@link MergeModelInput.mutationView} is run through
+     * {@link StepExporter} in its own source schema (mutations applied, geometry +
+     * quantities kept), and the resulting bytes are re-parsed into a fresh data
+     * store. The merge pipeline then sees the edited entities as ordinary source,
+     * so unit-aware federation, GlobalId reconciliation and id offsetting are
+     * unaffected. Models without edits pass through untouched (no export/parse cost).
+     */
+    private bakeMutatedModels;
+    /**
+     * Assemble the result stats, including any federation conformance warnings.
+     */
+    private buildStats;
+    /**
+     * Build the ifc-lite provenance header. Merged files have no single source
+     * header to round-trip, so we deliberately emit our own rather than picking
+     * one model's FILE_DESCRIPTION arbitrarily.
+     */
+    private buildHeader;
+    /**
+     * Compute the model-independent state shared by export()/exportAsync():
+     * per-model id offsets and the primary model's project/infra/spatial/unit info.
+     */
+    private buildMergeSetup;
+    /**
+     * Resolve a model's length unit scale (raw IFC length → metres). Prefers an
+     * explicit `lengthUnitScale` on the input, else the value the parser stamped
+     * on the data store, else metres.
+     */
+    private resolveUnitScale;
+    /** True when two length unit scales are equal within relative tolerance. */
+    private unitsCompatible;
+    /**
+     * Resolve the set of express ids to include for a model under visibility
+     * filtering, or `null` when no filtering is requested (include everything).
+     */
+    private computeIncludedEntityIds;
+    /**
+     * Plan how a model's entities are remapped, skipped, or re-stamped, given
+     * whether it shares the primary model's length unit (`compatible`).
+     *
+     * Compatible (or `assume-shared`) models are unified into the primary project:
+     * their IfcProject, shared infrastructure, and matching spatial structure are
+     * deduplicated, and a rooted entity repeating an already-emitted GlobalId is
+     * unified to that one instance.
+     *
+     * Incompatible (federated) models keep their own project, units, contexts and
+     * spatial structure so their coordinates stay correctly scaled; a rooted
+     * entity whose GlobalId collides with one already emitted is given a fresh
+     * deterministic GlobalId, since the two cannot be the same instance across
+     * different unit spaces.
+     */
+    private planModel;
+    /**
+     * Render one source entity into its final STEP line: apply id offset + shared
+     * remaps, re-stamp a federated GlobalId if needed, apply schema conversion,
+     * and register the emitted GlobalId so later models can reconcile against it.
+     * Returns `null` when schema conversion drops the entity.
+     */
+    private renderEntity;
+    /**
+     * Read the GlobalId (first quoted attribute) from an already-rendered STEP
+     * line. Used to register the id that was actually emitted, after any id
+     * remap, GlobalId re-stamp, or schema conversion. Returns null if the first
+     * quoted token is not a 22-char GlobalId.
+     */
+    private readLeadingGuid;
+    /**
+     * Mint a fresh, deterministic, collision-free GlobalId for an entity whose id
+     * collides. Seeded from the original GlobalId and the model's stable id so the
+     * output is reproducible and does not churn when an unrelated earlier model
+     * changes size; checked against both already-emitted ids and the ids minted
+     * so far for this model.
+     */
+    private mintUniqueGuid;
+    /**
+     * Read an entity's GlobalId (first attribute) by decoding only its head.
+     * Returns the 22-char id for a rooted entity, or `null` for any entity whose
+     * first attribute is not a GlobalId (geometry, lists, property atoms, …).
+     */
+    private extractGlobalIdFast;
+    /**
+     * Replace an entity's GlobalId (first quoted attribute) with `newGuid`.
+     * `newGuid` is a 22-char IFC id (no quote in its charset), so this is safe.
+     */
+    private replaceGlobalId;
     /**
      * Remap all #ID references in a STEP entity line.
      * Applies offset to all IDs, then overrides with specific remappings.

package/dist/merged-exporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merged-exporter.d.ts","sourceRoot":"","sources":["../src/merged-exporter.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0BrD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,SAAS,EAAE,YAAY,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,eAAe,CAAC,EAAE,YAAY,CAAC;IAE/B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qDAAqD;IACrD,sBAAsB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,0DAA0D;IAC1D,wBAAwB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAE3D,yCAAyC;IACzC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,YAAY,CAAC;IAC/C,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,OAAO,EAAE,UAAU,CAAC;IACpB,iBAAiB;IACjB,KAAK,EAAE;QACL,8BAA8B;QAC9B,UAAU,EAAE,MAAM,CAAC;QACnB,mCAAmC;QACnC,gBAAgB,EAAE,MAAM,CAAC;QACzB,yBAAyB;QACzB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAoB;gBAEtB,MAAM,EAAE,eAAe,EAAE;IAOrC,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB;IAmKtD;;;;OAIG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsK1E;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAsDvB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAelC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;;;;;;;OAQG;IACH,OAAO,CAAC,oBAAoB;IA2E5B;;;;;;;;;OASG;IACH,OAAO,CAAC,0BAA0B;IA8BlC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAa9B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CA0D7B"}
+{"version":3,"file":"merged-exporter.d.ts","sourceRoot":"","sources":["../src/merged-exporter.ts"],"names":[],"mappings":"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"}