Allow Performing Transforms with additionalTransforms (#265)

If src and target imodel's have differing local Helmert transforms,
transform target elements positions to maintain proper local positions.

The target imodel "additionalTransform" will always be maintained, even
if it is null. The source imodel when copied into the target will have a
combination of both helmert transforms applied to its elements
placements. This way the result will place the elements in a position
that when the targets "additionalTransform" is applied it will be in the
correct geographic position. If the target's "additionalTransform" is
null, then the we are simply applying the src's helmert transform
permanently to each elements position instead of just at render time. If
the src and target have different non null transforms, then the
resulting transform applied to the src elements will also negate the
helmert transform applied by the target model.

---------

Co-authored-by: Daniel Rodriguez <DanRod1999@users.noreply.github.com>

Author: DanRod1999

change/@itwin-imodel-transformer-8282633a-0288-4a06-9d23-800bce71d0c6.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "allow transforming imodels with matching CRS, but differing local transforms",
+  "packageName": "@itwin/imodel-transformer",
+  "email": "'DanRod1999@users.noreply.github.com'",
+  "dependentChangeType": "patch"
+}

common/api/imodel-transformer.api.md

@@ -22,6 +22,7 @@ import { EntityReference } from '@itwin/core-common';
 import { ExternalSourceAspect } from '@itwin/core-backend';
 import { ExternalSourceAspectProps } from '@itwin/core-common';
 import { FontProps } from '@itwin/core-common';
+import { Helmert2DWithZOffset } from '@itwin/core-common';
 import { Id64Arg } from '@itwin/core-bentley';
 import { Id64Array } from '@itwin/core-bentley';
 import { Id64Set } from '@itwin/core-bentley';
@@ -244,21 +245,24 @@ export interface IModelImportOptions {
 export class IModelTransformer extends IModelExportHandler {
     constructor(source: IModelDb | IModelExporter, target: IModelDb | IModelImporter, options?: IModelTransformOptions);
     protected addCustomChanges(_sourceDbChanges: ChangedInstanceIds): Promise<void>;
-    calculateEcefTransform(srcDb: IModelDb, targetDb: IModelDb): Transform;
+    calculateEcefTransform(): Transform | undefined;
+    // (undocumented)
+    calculateTransformFromHelmertTransforms(): Transform | undefined;
     combineElements(sourceElementIds: Id64Array, targetElementId: Id64String): void;
     // (undocumented)
     protected completePartiallyCommittedAspects(): void;
     // (undocumented)
     protected completePartiallyCommittedElements(): void;
     readonly context: IModelCloneContext;
+    // (undocumented)
+    static convertHelmertToTransform(helmert: Helmert2DWithZOffset | undefined): Transform;
     // @deprecated
     detectElementDeletes(): Promise<void>;
     // @deprecated
     detectRelationshipDeletes(): Promise<void>;
     static determineSyncType(sourceDb: IModelDb, targetDb: IModelDb,
     targetScopeElementId: Id64String): "forward" | "reverse";
     dispose(): void;
-    ecefTransform?: Transform;
     protected _elementsWithExplicitlyTrackedProvenance: Set<string>;
     readonly exporter: IModelExporter;
     static forEachTrackedElement(args: {
@@ -357,7 +361,6 @@ export class IModelTransformer extends IModelExportHandler {
 
 // @beta
 export interface IModelTransformOptions {
-    alignECEFLocations?: boolean;
     argsForProcessChanges?: ProcessChangesOptions;
     branchRelationshipDataBehavior?: "unsafe-migrate" | "reject";
     cloneUsingBinaryGeometry?: boolean;
@@ -371,6 +374,7 @@ export interface IModelTransformOptions {
     preserveElementIdsForFiltering?: boolean;
     skipPropagateChangesToRootElements?: boolean;
     targetScopeElementId?: Id64String;
+    tryAlignGeolocation?: boolean;
     wasSourceIModelCopiedToTarget?: boolean;
 }
 

packages/transformer/src/IModelTransformer.ts

@@ -23,7 +23,14 @@ import {
   YieldManager,
 } from "@itwin/core-bentley";
 import * as ECSchemaMetaData from "@itwin/ecschema-metadata";
-import { Point3d, Transform } from "@itwin/core-geometry";
+import {
+  Angle,
+  AxisIndex,
+  Matrix3d,
+  Point3d,
+  Transform,
+  Vector3d,
+} from "@itwin/core-geometry";
 import * as coreBackendPkgJson from "@itwin/core-backend/package.json";
 import {
   BriefcaseManager,
@@ -82,6 +89,7 @@ import {
   FontProps,
   GeometricElement3dProps,
   GeometricElementProps,
+  Helmert2DWithZOffset,
   IModel,
   IModelError,
   ModelProps,
@@ -240,11 +248,14 @@ export interface IModelTransformOptions {
    * @default undefined
    */
   argsForProcessChanges?: ProcessChangesOptions;
-  /** A flag that determines if spatial elements from the source db should be transformed if source and target iModel ECEF locations differ.
-   * @note This flag should only be used if imodels are linearly located
+
+  /**
+   * A flag that determines if spatial elements from the source db should be transformed if:
+   * source and target iModel GCS/CRS data is the same, but they have differing additional transforms
+   * source and target iModel ECEF locations differ
    * @default false
    */
-  alignECEFLocations?: boolean;
+  tryAlignGeolocation?: boolean;
 }
 
 /**
@@ -385,10 +396,15 @@ export class IModelTransformer extends IModelExportHandler {
   public readonly targetDb: IModelDb;
   /** The IModelTransformContext for this IModelTransformer. */
   public readonly context: IModelCloneContext;
-  /** The transform to be applied to the placement of spatial elements when source and target db have different ECEF locations
-   * @note transform can only be used when source and target are linearly located imodels
+  /** The transform to be applied to the placement of spatial elements
+   * This transform should be applied when:
+   * - source and target db have different ECEF locations
+   * - source and target db have matching GCS/CRS data, but differing `geographicCoordinateSystem.additionalTransform.helmert2DWithZOffset`
+   * @note for ECEF transforms, this can only be used when source and target are linearly located imodels
+   * @note for non linearly located imodels, this transform will be a linear transform derived from Helmert Transforms from the src and target iModels.
+   * @beta
    */
-  public ecefTransform?: Transform;
+  private _linearSpatialTransform?: Transform;
   private _syncType?: SyncType;
 
   /** The Id of the Element in the **target** iModel that represents the **source** repository as a whole and scopes its [ExternalSourceAspect]($backend) instances. */
@@ -599,7 +615,7 @@ export class IModelTransformer extends IModelExportHandler {
         options?.branchRelationshipDataBehavior ?? "reject",
       skipPropagateChangesToRootElements:
         options?.skipPropagateChangesToRootElements ?? true,
-      alignECEFLocations: options?.alignECEFLocations ?? false,
+      tryAlignGeolocation: options?.tryAlignGeolocation ?? false,
     };
     // check if authorization client is defined
     if (IModelHost.authorizationClient === undefined) {
@@ -667,9 +683,29 @@ export class IModelTransformer extends IModelExportHandler {
       (this.targetDb as any).codeValueBehavior = "exact";
     }
     /* eslint-enable @itwin/no-internal */
-    this.ecefTransform = this._options.alignECEFLocations
-      ? this.calculateEcefTransform(this.sourceDb, this.targetDb)
-      : undefined;
+    if (this._options.tryAlignGeolocation) {
+      if (
+        this.sourceDb.geographicCoordinateSystem ||
+        this.targetDb.geographicCoordinateSystem
+      ) {
+        Logger.logTrace(
+          loggerCategory,
+          "Aligning Additional transforms between imodels due to imodels containing GeographicCoordinateSystem data"
+        );
+        this._linearSpatialTransform =
+          this.calculateTransformFromHelmertTransforms();
+      } else if (this.sourceDb.ecefLocation && this.targetDb.ecefLocation) {
+        Logger.logTrace(
+          loggerCategory,
+          "Aligning ECEF Location's between imodels due to imodels not containing GeographicCoordinateSystem data"
+        );
+        this._linearSpatialTransform = this.calculateEcefTransform();
+      } else
+        Logger.logTrace(
+          loggerCategory,
+          "No Geolcation data to align, both GCS and ECEF are undefined"
+        );
+    }
   }
 
   /** validates that the importer set on the transformer has the same values for its shared options as the transformer.
@@ -1587,7 +1623,7 @@ export class IModelTransformer extends IModelExportHandler {
     }
 
     if (
-      this.ecefTransform !== undefined &&
+      this._linearSpatialTransform !== undefined &&
       sourceElement instanceof GeometricElement3d
     ) {
       // can check the sourceElement since this IModelTransformer does not remap classes
@@ -1596,7 +1632,7 @@ export class IModelTransformer extends IModelExportHandler {
       );
 
       if (placement.isValid) {
-        placement.multiplyTransform(this.ecefTransform);
+        placement.multiplyTransform(this._linearSpatialTransform);
         (targetElementProps as GeometricElement3dProps).placement = placement;
       }
     }
@@ -1610,45 +1646,137 @@ export class IModelTransformer extends IModelExportHandler {
    * @returns Transform that converts relative coordinates in the source iModel to relative coordinates in the target iModel.
    * @note This can only be used if both source and target iModels are linearly located
    */
-  public calculateEcefTransform(
-    srcDb: IModelDb,
-    targetDb: IModelDb
+  public calculateEcefTransform(): Transform | undefined {
+    const srcEcefLoc = this.sourceDb.ecefLocation;
+    const targetEcefLoc = this.targetDb.ecefLocation;
+
+    if (srcEcefLoc === undefined || targetEcefLoc === undefined) {
+      throw new IModelError(
+        IModelStatus.NoGeoLocation,
+        "Both source and target ECEF locations must be defined to calculate the transform."
+      );
+    }
+    if (srcEcefLoc.getTransform().isAlmostEqual(targetEcefLoc.getTransform())) {
+      Logger.logTrace(
+        loggerCategory,
+        "ECEF data is already aligned. No spatial transforms needed."
+      );
+      return undefined;
+    }
+
+    const srcSpatialToECEF = srcEcefLoc.getTransform(); // converts relative to ECEF in relation to source
+    const targetECEFToSpatial = targetEcefLoc.getTransform().inverse(); // converts ECEF to relative in relation to target
+    if (!targetECEFToSpatial) {
+      throw new IModelError(
+        IModelStatus.NoGeoLocation,
+        "Failed to invert target ECEF transform."
+      );
+    }
+    const ecefTransform =
+      targetECEFToSpatial.multiplyTransformTransform(srcSpatialToECEF); // chain both transforms
+
+    return ecefTransform;
+  }
+
+  public static convertHelmertToTransform(
+    helmert: Helmert2DWithZOffset | undefined
   ): Transform {
-    const srcEcefLoc = srcDb.ecefLocation;
-    const targetEcefLoc = targetDb.ecefLocation;
+    if (!helmert) {
+      return Transform.createIdentity();
+    }
+
+    const rotationXY = Matrix3d.createRotationAroundAxisIndex(
+      AxisIndex.Z,
+      Angle.createDegrees(helmert?.rotDeg)
+    );
+    rotationXY.scaleColumnsInPlace(helmert.scale, helmert.scale, 1.0);
+    const translation = Vector3d.create(
+      helmert.translationX,
+      helmert.translationY,
+      helmert.translationZ
+    );
+    const helmertTransform = Transform.createRefs(translation, rotationXY);
 
+    return helmertTransform;
+  }
+
+  public calculateTransformFromHelmertTransforms(): Transform | undefined {
+    if (
+      this.sourceDb.geographicCoordinateSystem?.horizontalCRS === undefined ||
+      this.sourceDb.geographicCoordinateSystem?.verticalCRS === undefined
+    ) {
+      throw new IModelError(
+        IModelStatus.BadRequest,
+        "Source iModel does not have a geographic coordinate system defined."
+      );
+    }
     if (
-      srcDb.geographicCoordinateSystem !== undefined ||
-      targetDb.geographicCoordinateSystem !== undefined
+      this.targetDb.geographicCoordinateSystem?.horizontalCRS === undefined ||
+      this.targetDb.geographicCoordinateSystem.verticalCRS === undefined
+    ) {
+      throw new IModelError(
+        IModelStatus.BadRequest,
+        "Target iModel does not have a geographic coordinate system defined."
+      );
+    }
+    if (
+      !this.sourceDb.geographicCoordinateSystem.horizontalCRS.equals(
+        this.targetDb.geographicCoordinateSystem.horizontalCRS
+      ) ||
+      !this.sourceDb.geographicCoordinateSystem.verticalCRS.equals(
+        this.targetDb.geographicCoordinateSystem.verticalCRS
+      )
     ) {
       throw new IModelError(
         IModelStatus.MismatchGcs,
-        "Both source and target geographic coordinate systems must not be defined to calculate the linear ecef transform."
+        "Source and target geographic coordinate systems must match to calculate the spatial transform."
       );
     }
+    if (
+      this.sourceDb.geographicCoordinateSystem.additionalTransform ===
+      this.targetDb.geographicCoordinateSystem.additionalTransform
+    ) {
+      Logger.logTrace(
+        loggerCategory,
+        "Geolocation data is already aligned. No spatial transforms needed."
+      );
+      return undefined;
+    }
 
-    if (srcEcefLoc === undefined || targetEcefLoc === undefined) {
+    const srcScale =
+      this.sourceDb.geographicCoordinateSystem.additionalTransform
+        ?.helmert2DWithZOffset?.scale ?? 1;
+    const targetScale =
+      this.targetDb.geographicCoordinateSystem.additionalTransform
+        ?.helmert2DWithZOffset?.scale ?? 1;
+
+    if (srcScale !== targetScale) {
       throw new IModelError(
-        IModelStatus.NoGeoLocation,
-        "Both source and target ECEF locations must be defined to calculate the transform."
+        IModelStatus.MismatchGcs,
+        "Spatial transform is non rigid. Source and target Helmert transforms must have the same scale to calculate a rigid spatial transform."
       );
-    } else {
-      if (srcEcefLoc.getTransform().isAlmostEqual(targetEcefLoc.getTransform()))
-        return Transform.createIdentity();
+    }
 
-      const srcSpatialToECEF = srcEcefLoc.getTransform(); // converts relative to ECEF in relation to source
-      const targetECEFToSpatial = targetEcefLoc.getTransform().inverse(); // converts ECEF to relative in relation to target
-      if (!targetECEFToSpatial) {
-        throw new IModelError(
-          IModelStatus.NoGeoLocation,
-          "Failed to invert target ECEF transform."
-        );
-      }
-      const ecefTransform =
-        targetECEFToSpatial.multiplyTransformTransform(srcSpatialToECEF); // chain both transforms
+    const srcTransform = IModelTransformer.convertHelmertToTransform(
+      this.sourceDb.geographicCoordinateSystem.additionalTransform
+        ?.helmert2DWithZOffset
+    ); // moves elements to where src helmert transform would move them at render time
+    const targetTransformInv = IModelTransformer.convertHelmertToTransform(
+      this.targetDb.geographicCoordinateSystem.additionalTransform
+        ?.helmert2DWithZOffset
+    ).inverse(); // negates target helmert transform that is applied at render time
 
-      return ecefTransform;
+    if (!targetTransformInv) {
+      throw new IModelError(
+        IModelStatus.NoGeoLocation,
+        "Failed to invert target Helmert transform."
+      );
     }
+
+    const combinedTransform =
+      targetTransformInv.multiplyTransformTransform(srcTransform);
+
+    return combinedTransform;
   }
 
   // if undefined, it can be initialized by calling [[this.processChangesets]]