Drawing production MVP requirements

[pmconne]

Is your feature request related to a problem? Please describe.

@Josh-Schifter's drawing production team has minimum requirements for their initial release.

Describe the solution you'd like

They need to create a field in a sheet template and see that field be updated when the template is copied from a catalog iModel to create a new BisCore.Sheet in the design iModel.

Tasks

• [x] Implement ITextAnnotation.onCloned
  • [x] Remap element Ids in JSON when copying a field from one iModel to another
  • [x] Copy or create ElementDrivesTextAnnotation relationships between iModels
  • [x] Copy default text style or remap based on name
• [x] #8615 and cloning a text style imports font
• [x] Enhance display-test-app for testing and API validation
  • [x] Key-ins
    • [x] Save TextDecoration's current annotation as a TextAnnotation2d element, possibly replacing the annotation on an existing element.
    • [x] Populate TextDecoration's current annotation from an existing element.
    • [x] Add a FieldRun to TextDecoration
  • [x] Support specifying channels to which DTA is permitted to write.
• [x] Support all of the property types in #8490
  • [x] Formatting
    • [x] DateTime
    • [x] String
    • [ ] ~~Scale~~ not for MVP
  • [x] Field definition+evaluation
    • [x] Element properties
    • [x] ECView properties
    • [x] Project properties and Sheet properties
    • [x] SheetReference properties (ECView) issues/8490#issuecomment-3438055100) awaiting a decision on how to persist them.
• [x] Font cache invalidation
• [ ] Detect when a drawing may need to be regenerated
• [x] #8101
• [x] #8745

Josh suggested testing with sheet number (CodeValue for SheetReference) to start since that one's already implemented, but see question above about when sheet references actually get created in the workflow.

[pmconne]

@Josh-Schifter I need to know how scales are supposed to be formatted.

[DanRod1999]

Scales will not be included as part of MVP. See here for original post.

[pmconne]

@Ellord207 suggested project properties may no longer be part of MVP requirements. @Josh-Schifter is that accurate?

[Josh-Schifter]

@Ellord207 suggested project properties may no longer be part of MVP requirements. @Josh-Schifter is that accurate?

No accurate. We do need a few project properties as describe here: https://github.com/iTwin/itwinjs-core/issues/8490#issuecomment-3437986767

[pmconne]

@Josh-Schifter there's only one item remaining in the list.

Detect when a drawing may need to be regenerated

Is anything else missing from the list?

This last item is about regenerating annotations on section drawings, right? Since the logic to generate annotations resides in the authoring application, I suspect an API to detect when they need to be regenerated belongs there as well.

What do you need (API-wise or just technical guidance) from platform here?

Do you have a list of things that, when changed, require the annotations to be regenerated? Does the following list begin to cover it?

• The SpatialViewDefinition (including model+category selectors and display style) displayed on the drawing.
  • We can probably record the elements' LastMod properties at time of annotation generation.
• The geometry of any of the models displayed by the SpatialViewDefinition.
  • We can probably record the models' GeometryGuid properties at time of annotation generation.
• The parameters controlling annotation generation.
  • I don't know where/whether these are stored - do you?

[Ellord207]

What do you need (API-wise or just technical guidance) from platform here?

We are looking for technical guidance at this point in two aspects:

Detecting when Annotations are Outdated (of less priority)

We are not concerned about the SpatialViewDefinition or “parameters controlling annotation generation” changing since we will be the ones directly changing them. What we are concerned about is when spatial elements change. Your suggestion of using the models' GeometryGuid to track changes is good, but there’s still the possibility of a property on an element changing. It should also be considered even a relatively small geometric changes can result in many Drawings becoming outdated.

We suspect that we will need to create a way to map/relate annotated elements to the drawings where they appear. We will explore that later and can bring proposals to Core for feedback.

One point we would like feedback on is with the following specific concern. It’s possible for a SectionDrawing to show an updated view, but the annotations to not be updated yet. This puts the drawing into a concerning “in-between” state. If there is the possibility of a Drawing not getting fully updated before a commit/push, then other (review) applications will also need to warn of such a state. This gives us the requirement that the drawings should persist that they are out of date so that our code can display warning to the users in these cases.

Handling Updating the Drawing (a current priority)

We need help exploring the workflow of updating the drawings once we know they are outdated. There are different parts of drawings that should be considered:

1. SectionDrawings with their SpatialViewDefinition. These can be handled at low cost.
2. Automated Annotations on the Drawings (ex. Labeling). These can be regenerated at a high cost (~20 second + ~1 second additional job).
3. Automated Geometry on the Drawings (ex. Profile). These can be regenerated at low cost.
4. Users placed Annotations. It would be good to preserve as intelligently as possible.

In the case of OS+, it’s highly likely that any change will have widespread effects on the “smart” spatial Model and cause many Drawings to be outdated at once. In an ideal world, the drawing could instantly and automatically be generated to match spatial model, but there are technical limitations preventing that. We need to find a comprise between these.

I have talked with OS+ about their long running editing workflow in and they have 2 types of comparable workflows.

1. There are reactive regenerative changes. The jobs are sent to libraries/computationally intensive algorithms, and the results are persisted in the iModel. These jobs take seconds, and the changes are handled immediately, locking app for the duration. I don’t think this would work for us due to the short job time.
2. They have investigated optimization jobs, where the users explicitly launch a job that can run for a minute. During this time the app is usable to the user and the user can review and accept the results of the job run at their convenience.

I think this second option could act as an example, though it does have the “user pushes a button to regenerate drawings” action we have been trying to avoid.

[Ellord207]

After an off line discussion the following was decided:

• When a Drawing is create or updated it will cache the GeometryGuid's of all models it depends on (which can include itself in the case of Field annotations).
• All values it depends on that are not geometric will be done with Fields.
• If there is a difference between the Drawing's cached GeometryGuids and real models' GeometryGuids, we know the Drawing is outdated and needs to be regenerated.
• After the uses doesn't make any changes to the models a Drawing depends on for a set time (20 seconds?), the app will start a job to update the drawings.
• The results of the of that job will be cached until the drawing is "needed." (When the drawing is viewed, when the app is closed, when the app pushes changes).
• Any cached job results for a Drawing will be thrown out/ignored if there are changes to a model the Drawing depends on.
• When it is "needed," the app will update the Drawing by applying the cached job results.
• After this update, the Drawing will cached the current GeometryGuid's of all models it depends on.

[pmconne]

After an off line discussion the following was decided:

Example in #8864. Please review the PR and close this issue when you are satisfied with the example.