@ifc-lite/export 2.3.0 → 2.4.0

package/dist/merged-exporter.d.ts

@@ -75,11 +75,49 @@ export interface MergeExportOptions {
      *   (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.
+     * - `'normalize'`: single-unit merge. A model with a *different* length unit
+     *   is *rescaled* — every length-valued datum (all `IfcCartesianPoint`
+     *   coordinates, extrusion depths, profile dimensions, radii, thicknesses,
+     *   storey elevations, placement offsets, `IfcLengthMeasure` property values,
+     *   `IfcQuantityLength`/`Area`/`Volume`, …) is converted from its own unit
+     *   into the first model's unit — and then unified into the single first
+     *   `IfcProject` (its `IfcUnitAssignment` and contexts deduplicated). The
+     *   output is one ordinary single-unit IFC that opens correctly everywhere
+     *   (BIM Vision included). Angles, ratios, counts and georeferencing offsets
+     *   are left as-is. Area/volume values assume the SI-derived unit
+     *   (square/cube of the length unit). See {@link ./unit-normalize.ts} for the
+     *   exact set of rescaled attributes.
      * - `'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';
+    unitReconciliation?: 'auto' | 'normalize' | 'assume-shared';
+    /**
+     * How IfcSite instances are matched across models for spatial unification
+     * (mirrors IfcOpenShell/BlenderBIM's "Merge Projects" recipe). Omitted
+     * (default) keeps today's combined heuristic: match by Name
+     * (case-insensitive), else unify when both models contribute exactly one
+     * site.
+     *
+     * - `'single'`: unify only when each model contributes exactly one
+     *   IfcSite — Name is ignored entirely.
+     * - `'by-name'`: unify only sites with a matching Name; a lone,
+     *   differently-named site in each model is kept as two separate roots.
+     */
+    mergeSites?: 'single' | 'by-name';
+    /** Same matching strategy as {@link mergeSites}, applied to IfcBuilding. */
+    mergeBuildings?: 'single' | 'by-name';
+    /**
+     * How IfcBuildingStorey instances are matched across models. Omitted
+     * (default) is `'by-name-then-elevation'` — today's behavior.
+     *
+     * - `'by-name'`: match only by Name (case-insensitive); no elevation
+     *   fallback.
+     * - `'by-elevation'`: match only by Elevation (±0.5 model-unit tolerance,
+     *   same as today), ignoring Name entirely.
+     * - `'by-name-then-elevation'`: try Name first, fall back to Elevation.
+     */
+    mergeStoreys?: 'by-name' | 'by-elevation' | 'by-name-then-elevation';
     /** Apply visibility filtering to each model before merging */
     visibleOnly?: boolean;
     /** Hidden entity IDs per model (local expressIds) */
@@ -123,6 +161,12 @@ export interface MergeExportResult {
          * unit differed from the first model's. 0 means a single unified project.
          */
         federatedModelCount: number;
+        /**
+         * Number of models whose length-valued data was rescaled into the first
+         * model's unit under `unitReconciliation: 'normalize'`. 0 for the other
+         * modes (or when every model already shared the first model's unit).
+         */
+        normalizedModelCount: number;
         /**
          * Human-readable advisories about the merge (empty on a clean single-unit
          * merge). Notably flags when federation produced more than one IfcProject,
@@ -154,14 +198,15 @@ export interface MergeExportResult {
  *    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.
+ * Conformance trade-off: when federation triggers (under the default `'auto'`),
+ * the file contains more than one IfcProject, which intentionally relaxes the
+ * IfcSingleProjectInstance EXPRESS rule (SIZEOF(IfcProject) <= 1). This preserves
+ * both units without rewriting coordinates, and is strictly better than a silent
+ * mis-scale. `MergeExportResult.stats.warnings` flags it. To instead get one
+ * ordinary single-unit IfcProject, pass `unitReconciliation: 'normalize'` — it
+ * rescales every length-valued datum of the differing-unit models into the first
+ * model's unit (see {@link ./unit-normalize.ts}). Use `'assume-shared'` only when
+ * the caller has already normalised units.
  *
  * 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
@@ -192,6 +237,13 @@ export declare class MergedExporter {
      * Assemble the result stats, including any federation conformance warnings.
      */
     private buildStats;
+    /**
+     * Record advisories for a model being normalized. The rescaler derives its
+     * length-attribute map from the IFC4 schema registry, so it may not cover
+     * length attributes introduced by newer schemas (IFC4X3 alignment / linear
+     * referencing), and it deliberately leaves georeferencing untouched.
+     */
+    private collectNormalizeCaveats;
     /**
      * 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
@@ -203,6 +255,36 @@ export declare class MergedExporter {
      * per-model id offsets and the primary model's project/infra/spatial/unit info.
      */
     private buildMergeSetup;
+    /**
+     * Decide how one model folds into the merge from its length unit and the
+     * reconciliation mode.
+     *
+     * - The primary model, `assume-shared`, and any model that already shares the
+     *   primary unit are unified with no rescale.
+     * - Under `normalize`, a differing-unit model is unified *and* rescaled: every
+     *   length-valued datum is multiplied by `primaryScale`-relative factor so its
+     *   geometry stays correct under the single shared unit.
+     * - Otherwise (`auto`) a differing-unit model is federated (kept as its own
+     *   project + units), leaving its raw coordinates untouched.
+     *
+     * Area/volume reconciliation is gated on the length unit differing: a model that
+     * shares the primary's length unit is treated as fully compatible (factors 1).
+     * A model that pairs a matching length unit with a *divergent* area/volume unit
+     * (a non-conformant combination no mainstream exporter emits) is not rescaled.
+     */
+    private resolveModelMode;
+    /**
+     * Resolve a model's declared AREAUNIT / VOLUMEUNIT scale (SI m² / m³ per unit)
+     * by walking IfcProject → IfcUnitAssignment. Falls back to the length-derived
+     * unit (`lengthScale ** power`) when the model declares no explicit area/volume
+     * unit — the IFC default. A prefixed SI area/volume unit (rare) applies the
+     * prefix once (buildingSMART / IfcOpenShell convention).
+     */
+    private resolveDerivedUnitScale;
+    /** Uppercase an enum token, stripping the STEP `.ENUM.` dots. `''` for nullish. */
+    private normalizeEnum;
+    /** Extract the number from a bare real or a typed measure token (`IFCAREAMEASURE(0.09)`). */
+    private parseMeasureNumber;
     /**
      * Resolve a model's length unit scale (raw IFC length → metres). Prefers an
      * explicit `lengthUnitScale` on the input, else the value the parser stamped
@@ -220,10 +302,10 @@ export declare class MergedExporter {
      * 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.
+     * Compatible models (same unit, `assume-shared`, or `normalize`d into the
+     * primary unit) 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
@@ -293,11 +375,30 @@ export declare class MergedExporter {
      * to the first model's equivalents. Matched entities are remapped and
      * their duplicate entity is skipped from output.
      *
-     * Matching strategy:
-     * - Sites/Buildings: by name (case-insensitive), or if only one in each model
-     * - Storeys: by name first, then by elevation (tolerance ±0.5 model units)
+     * Matching strategy per container type is driven by
+     * {@link MergeExportOptions.mergeSites} / `mergeBuildings` / `mergeStoreys`
+     * (all optional; omitted keeps the pre-existing combined heuristic):
+     * - Sites/Buildings: `'single'` (ignore name, unify iff exactly one in each
+     *   model), `'by-name'` (name only, no fallback), or omitted — name first,
+     *   else single-instance fallback.
+     * - Storeys: `'by-name'`, `'by-elevation'` (tolerance ±0.5 model units), or
+     *   `'by-name-then-elevation'` (default, also the omitted behavior).
      */
     private unifySpatialEntities;
+    /**
+     * Match one IfcSite/IfcBuilding instance against the first model's
+     * equivalents, per {@link mergeMode}:
+     * - `'single'`: ignore name — unify iff both models contribute exactly one.
+     * - `'by-name'`: name match only, no single-instance fallback.
+     * - omitted: name match, else single-instance fallback (pre-existing heuristic).
+     *
+     * `matchedFirst` excludes first-model targets already claimed by an earlier
+     * entity in this same model's loop — without it, two of this model's sites
+     * (or buildings) sharing a name/being the sole instance would both resolve
+     * to the same target, and the second would be dropped (skipped + remapped)
+     * rather than kept as its own root.
+     */
+    private matchRootContainer;
     /**
      * Skip IfcRelAggregates that become fully redundant after spatial unification.
      *

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

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