add isolate elements feature to transformer test app (#3601)

* add isolateElements tool to the transformer test-app

* add geometry options

* add to README note about the new isolatedElements feature

* fix cloneUsingJsonGeometry option description

Co-authored-by: Michael Belousov <MichaelBelousov@users.noreply.github.com>

test-apps/imodel-transformer/README.md

@@ -51,3 +51,10 @@ A common strategy is to run with verbose logging on to find the problem element
 Once the problem area has been identified, you can employ various strategies to set a conditional breakpoint.
 One possibility is to edit the `onTransformElement` method in `Transformer.ts` to add a `if (sourceElement.getDisplayLabel() === "x")` or `if (sourceElement.id === "x")` conditional (using information from the log output) around a "hit problem area" log function call and then set a breakpoint on that log message.
 After rebuilding, re-running, and hitting the breakpoint, you can then step into the core IModelTransformer methods to see what is really going on.
+
+### isolating bad elements
+
+You can pass a comma-separated list of element ids to the `--isolateElements` (such as `id1,id2`) to transform to the specified target
+a filtered iModel containing only the path to the given elements/models specified by the given ids. This can be
+useful to create smaller reproduction iModels with less data that still contain problematic elements. You can also isolate the entire subtrees
+of these elements by using `--isolateTrees` instead of `--isolateElements`.

test-apps/imodel-transformer/src/Main.ts

@@ -165,6 +165,24 @@ void (async () => {
           type: "boolean",
           default: false,
         },
+        isolateElements: {
+          desc: "transform filtering all element/models that aren't part of the logical path to a set of comma-separated element ids",
+          type: "string",
+        },
+        isolateTrees: {
+          desc: "transform filtering all element/models that aren't part of the logical path to a set of comma-separated element ids, or one of their children",
+          type: "string",
+        },
+        loadSourceGeometry: {
+          desc: "load geometry from the source as JSON while transforming, for easier (but not performant) transforming of geometry",
+          type: "boolean",
+          default: false,
+        },
+        cloneUsingJsonGeometry: {
+          desc: "sets cloneUsingBinaryGeometry in the transformer options to true, which is slower but allows simple editing of geometry in javascript.",
+          type: "boolean",
+          default: false,
+        },
       })
       .parse();
 
@@ -327,13 +345,28 @@ void (async () => {
 
     const transformerOptions: TransformerOptions = {
       ...args,
+      cloneUsingBinaryGeometry: !args.cloneUsingJsonGeometry,
       excludeSubCategories: args.excludeSubCategories?.split(","),
       excludeCategories: args.excludeCategories?.split(","),
     };
 
     if (processChanges) {
       assert(undefined !== args.sourceStartChangesetId);
       await Transformer.transformChanges(await acquireAccessToken(), sourceDb, targetDb, args.sourceStartChangesetId, transformerOptions);
+    } else if (args.isolateElements !== undefined || args.isolateTrees !== undefined) {
+      const isolateTrees = args.isolateTrees !== undefined;
+      const isolateArg = args.isolateElements ?? args.isolateTrees;
+      assert(isolateArg !== undefined);
+      const isolateList = isolateArg.split(",");
+      const transformer = await Transformer.transformIsolated(sourceDb, targetDb, isolateList, isolateTrees, transformerOptions);
+      Logger.logInfo(
+        loggerCategory,
+        [
+          "remapped elements:",
+          isolateList.map((id) => `${id}=>${transformer.context.findTargetElementId(id)}`).join(", "),
+        ].join("\n")
+      );
+      transformer.dispose();
     } else {
       await Transformer.transformAll(sourceDb, targetDb, transformerOptions);
     }

test-apps/imodel-transformer/src/Transformer.ts

@@ -66,6 +66,42 @@ export class Transformer extends IModelTransformer {
     transformer.logElapsedTime();
   }
 
+  /**
+   * attempt to isolate a set of elements by transforming only them from the source to the target
+   * @note the transformer is returned, not disposed, you must dispose it yourself
+   */
+  public static async transformIsolated(
+    sourceDb: IModelDb,
+    targetDb: IModelDb,
+    isolatedElementIds: Id64Array,
+    includeChildren = false,
+    options?: TransformerOptions
+  ): Promise<IModelTransformer> {
+    class IsolateElementsTransformer extends Transformer {
+      public override shouldExportElement(sourceElement: Element) {
+        if (!includeChildren
+          && (isolatedElementIds.some((id) => sourceElement.parent?.id === id)
+            || isolatedElementIds.some((id) => sourceElement.model === id))
+        )
+          return false;
+        return super.shouldExportElement(sourceElement);
+      }
+    }
+    const transformer = new IsolateElementsTransformer(sourceDb, targetDb, options);
+    transformer.initialize(options);
+    await transformer.processSchemas();
+    await transformer.saveChanges("processSchemas");
+    for (const id of isolatedElementIds)
+      await transformer.processElement(id);
+    await transformer.saveChanges("process isolated elements");
+    if (options?.deleteUnusedGeometryParts) {
+      transformer.deleteUnusedGeometryParts();
+      await transformer.saveChanges("deleteUnusedGeometryParts");
+    }
+    transformer.logElapsedTime();
+    return transformer;
+  }
+
   private constructor(sourceDb: IModelDb, targetDb: IModelDb, options?: TransformerOptions) {
     super(sourceDb, new IModelImporter(targetDb, { simplifyElementGeometry: options?.simplifyElementGeometry }), options);
   }