@itwin/core-common 4.8.0-dev.4 → 4.8.0-dev.5

package/lib/esm/PlanarClipMask.js

@@ -17,15 +17,24 @@ export var PlanarClipMaskMode;
     /** Mask based on priority. Different types of models have different default priorities as enumerated by [[PlanarClipMaskPriority]].
      * For example, background maps have the lowest priority, so they are masked by all other types, while design models have the highest priority and are therefore never masked.
      * The priority of a reality model can be overridden by [[PlanarClipMaskSettings.priority]]. This is useful to allow one reality model to mask another overlapping one.
+     * Everything visible in the view creates the mask, so turning off models, categories, or elements (via fully transparent overrides) will make things not be in the mask.
      */
     PlanarClipMaskMode[PlanarClipMaskMode["Priority"] = 1] = "Priority";
-    /** Indicates that masks should be produced from the geometry in a set of [GeometricModel]($backend)s. */
+    /** Indicates that masks should be produced from the geometry in a set of [GeometricModel]($backend)s, regardless of what model is on or off in the view.
+     * However, things that are off from category settings or element feature overrides in the view will not be in the mask for these models.
+     */
     PlanarClipMaskMode[PlanarClipMaskMode["Models"] = 2] = "Models";
-    /** Indicates that masks should be produced from geometry belonging to a set of subcategories. */
+    /** Indicates that masks should be produced from geometry belonging to a set of subcategories.
+     * View settings do not affect what is in the mask, unless [[PlanarClipMaskSettings.subCategoryOrElementIds]] is undefined, in which case it behaves like Models mode.
+     */
     PlanarClipMaskMode[PlanarClipMaskMode["IncludeSubCategories"] = 3] = "IncludeSubCategories";
-    /** Indicates that masks should be produced from the geometry of a set of [GeometricElement]($backend)s. */
+    /** Indicates that masks should be produced from the geometry of a set of [GeometricElement]($backend)s.
+     * View settings do not affect what is in the mask, unless [[PlanarClipMaskSettings.subCategoryOrElementIds]] is undefined, in which case it behaves like Models mode.
+     */
     PlanarClipMaskMode[PlanarClipMaskMode["IncludeElements"] = 4] = "IncludeElements";
-    /** Indicates that masks should be produced from the geometry of all [GeometricElement]($backend)s in a view, **except** for a specified set of excluded elements. */
+    /** Indicates that masks should be produced from the geometry of all [GeometricElement]($backend)s in a view, **except** for a specified set of excluded elements.
+     * View settings do not affect what is in the mask, unless [[PlanarClipMaskSettings.subCategoryOrElementIds]] is undefined, in which case it behaves like Models mode.
+     */
     PlanarClipMaskMode[PlanarClipMaskMode["ExcludeElements"] = 5] = "ExcludeElements";
 })(PlanarClipMaskMode || (PlanarClipMaskMode = {}));
 /** The default priority values for a [[PlanarClipMaskSettings]], based on model type. Models with a lower priority are masked by models with a higher priority.

package/lib/esm/PlanarClipMask.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlanarClipMask.js","sourceRoot":"","sources":["../../src/PlanarClipMask.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module DisplayStyles\r\n */\r\n\r\nimport { CompressedId64Set, Id64String, OrderedId64Iterable } from \"@itwin/core-bentley\";\r\n\r\n/** The different modes by which a [[PlanarClipMaskSettings]] collects the geometry used to mask a model.\r\n * @public\r\n * @extensions\r\n */\r\nexport enum PlanarClipMaskMode {\r\n  /** No masking. */\r\n  None = 0,\r\n  /** Mask based on priority. Different types of models have different default priorities as enumerated by [[PlanarClipMaskPriority]].\r\n   * For example, background maps have the lowest priority, so they are masked by all other types, while design models have the highest priority and are therefore never masked.\r\n   * The priority of a reality model can be overridden by [[PlanarClipMaskSettings.priority]]. This is useful to allow one reality model to mask another overlapping one.\r\n   */\r\n  Priority = 1,\r\n  /** Indicates that masks should be produced from the geometry in a set of [GeometricModel]($backend)s. */\r\n  Models = 2,\r\n  /** Indicates that masks should be produced from geometry belonging to a set of subcategories. */\r\n  IncludeSubCategories = 3,\r\n  /** Indicates that masks should be produced from the geometry of a set of [GeometricElement]($backend)s. */\r\n  IncludeElements = 4,\r\n  /** Indicates that masks should be produced from the geometry of all [GeometricElement]($backend)s in a view, **except** for a specified set of excluded elements. */\r\n  ExcludeElements = 5,\r\n}\r\n\r\n/** The default priority values for a [[PlanarClipMaskSettings]], based on model type. Models with a lower priority are masked by models with a higher priority.\r\n * The default can be overridden by [[PlanarClipMaskSettings.priority]].\r\n *  @public\r\n * @extensions\r\n */\r\nexport enum PlanarClipMaskPriority {\r\n  /** Background map. */\r\n  BackgroundMap = -2048,\r\n  /** A reality model that spans the globe - e.g., OpenStreetMaps Buildings. */\r\n  GlobalRealityModel = -1024,\r\n  /** A reality model with a bounded range. */\r\n  RealityModel = 0,\r\n  /** A design model stored in the [IModelDb]($backend). */\r\n  DesignModel = 2048,\r\n}\r\n\r\n/** JSON representation of a [[PlanarClipMaskSettings]].\r\n * @see [[DisplayStyleSettingsProps.planarClipOvr]] and [[ContextRealityModelProps.planarClipMask]].\r\n * @public\r\n * @extensions\r\n */\r\nexport interface PlanarClipMaskProps {\r\n  /** Controls how the mask geometry is collected */\r\n  mode: PlanarClipMaskMode;\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: CompressedId64Set;\r\n  /** See [[PlanarClipMaskSettings.subCategoryOrElementIds]]. */\r\n  subCategoryOrElementIds?: CompressedId64Set;\r\n  /** See [[PlanarClipMaskSettings.priority]]. */\r\n  priority?: number;\r\n  /** See [[PlanarClipMaskSettings.transparency]]. */\r\n  transparency?: number;\r\n  /** See PlanarClipMaskSettings.invert */\r\n  invert?: boolean;\r\n}\r\n\r\n/** Basic arguments supplied to [[PlanarClipMaskSettings.create]].\r\n * @public\r\n */\r\nexport interface BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.transparency]]. */\r\n  transparency?: number;\r\n  /** See [[PlanarClipMaskSettings.invert]]. */\r\n  invert?: boolean;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.Models]].\r\n * @public\r\n */\r\nexport interface ModelPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: Iterable<Id64String>;\r\n  /** @internal */\r\n  exclude?: never;\r\n  /** @internal */\r\n  elementIds?: never;\r\n  /** @internal */\r\n  subCategoryIds?: never;\r\n  /** @internal */\r\n  priority?: never;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.IncludeElements]] or [[PlanarClipMaskMode.ExcludeElements]].\r\n * @public\r\n */\r\nexport interface ElementPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: Iterable<Id64String>;\r\n  /** The elements used by the mask. @see [[PlanarClipMaskSettings.subCategoryOrElementIds]]. */\r\n  elementIds: Iterable<Id64String>;\r\n  /** If true, creates a mask of [[PlanarClipMaskMode.ExcludeElements]]; otherwise, [[PlanarClipMaskMode.IncludeElements]]. */\r\n  exclude?: boolean;\r\n  /** @internal */\r\n  subCategoryIds?: never;\r\n  /** @internal */\r\n  priority?: never;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.IncludeSubCategories]].\r\n * @public\r\n */\r\nexport interface SubCategoryPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: Iterable<Id64String>;\r\n  /** The subcategories used by the mask. @see [[PlanarClipMaskSettings.subCategoryOrElementIds]]. */\r\n  subCategoryIds: Iterable<Id64String>;\r\n  /** @internal */\r\n  exclude?: never;\r\n  /** @internal */\r\n  elementIds?: never;\r\n  /** @internal */\r\n  priority?: never;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.Priority]].\r\n * @public\r\n */\r\nexport interface PriorityPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.priority]]. */\r\n  priority: number;\r\n  /** @internal */\r\n  exclude?: never;\r\n  /** @internal */\r\n  elementIds?: never;\r\n  /** @internal */\r\n  modelIds?: never;\r\n}\r\n\r\n/** Describes how to mask the geometry of one [GeometricModel]($backend) for display. The mask is produced by projecting geometry from any number of other models -\r\n * optionally filtered by [SubCategory]($backend) or by a set of specific [GeometricElement]($backend)s - onto a plane. Regions of the masked model that intersect the\r\n * mask are rendered partially or completely transparent. This is useful for, e.g., making subsurface geometry visible below the background map, or clipping out portions\r\n * of a reality model that intersect a design model.\r\n * @note Currently reality models (including background maps and terrain) can be masked, but design models can only produce masks.\r\n * @see [[DisplayStyleSettings.planarClipMasks]] to define clip masks for a [DisplayStyle]($backend).\r\n * @see [[ContextRealityModel.planarClipMaskSettings]] to apply a clip mask to a context reality model.\r\n * @public\r\n */\r\nexport class PlanarClipMaskSettings {\r\n  /** Specifies how the mask geometry is produced. */\r\n  public readonly mode: PlanarClipMaskMode;\r\n  /** For any mode other than [[PlanarClipMaskMode.Priority]], the Ids of the [GeometricModel]($backend)s containing the geometry used to produce the mask.\r\n   * If `undefined`, the set of all models in the view's [ModelSelector]($backend) is used.\r\n   * The mask geometry can be filtered by [[subCategoryOrElementIds]].\r\n   */\r\n  public readonly modelIds?: OrderedId64Iterable;\r\n  /** For [[PlanarClipMaskMode.IncludeElements]] or [[PlanarClipMaskMode.ExcludedElements]], the Ids of the [GeometricElement]($backend)s to include or exclude from masking;\r\n   * for [[PlanarClipMaskMode.IncludeSubCategories]], the Ids of the subcategories whose geometry contributes to the mask.\r\n   */\r\n  public readonly subCategoryOrElementIds?: OrderedId64Iterable;\r\n  /** For [[PlanarClipMaskMode.Priority]], the priority value. */\r\n  public readonly priority?: number;\r\n  /** A value between 0 and 1 indicating an override for mask transparency. A transparency of 0 indicates complete masking. 1 is completely transparent (no masking).\r\n   If no transparency is defined then the transparencies of the mask elements are used.\r\n   */\r\n  public readonly transparency?: number;\r\n  /** A value of true indicates that the mask should be inverted and only content within the mask should be displayed, in other words the area inside the mask is displayed rather than outside. */\r\n  public readonly invert: boolean;\r\n  private readonly _modelIds?: CompressedId64Set;\r\n  private readonly _subCategoryOrElementIds?: CompressedId64Set;\r\n\r\n  /** The compressed representation of [[modelIds]]. */\r\n  public get compressedModelIds(): CompressedId64Set | undefined {\r\n    return this._modelIds;\r\n  }\r\n\r\n  /** Create a new [[PlanarClipMaskSettings]] object from its JSON representation. */\r\n  public static fromJSON(json?: PlanarClipMaskProps): PlanarClipMaskSettings {\r\n    if (!json || undefined === json.mode)\r\n      return this.defaults;\r\n\r\n    return new PlanarClipMaskSettings(json.mode, json.transparency, json.modelIds, json.subCategoryOrElementIds, json.priority, json.invert);\r\n  }\r\n\r\n  /** Create a new PlanarClipMaskSettings. */\r\n  public static create(args: ModelPlanarClipMaskArgs | ElementPlanarClipMaskArgs | SubCategoryPlanarClipMaskArgs | PriorityPlanarClipMaskArgs): PlanarClipMaskSettings {\r\n    const modelIds = args.modelIds ? CompressedId64Set.sortAndCompress(args.modelIds) : undefined;\r\n    if (undefined !== args.priority)\r\n      return new PlanarClipMaskSettings(PlanarClipMaskMode.Priority, args.transparency, undefined, undefined, args.priority, args.invert);\r\n    else if (undefined !== args.subCategoryIds)\r\n      return new PlanarClipMaskSettings(PlanarClipMaskMode.IncludeSubCategories, args.transparency, modelIds, CompressedId64Set.sortAndCompress(args.subCategoryIds), undefined, args.invert);\r\n    else if (undefined !== args.elementIds)\r\n      return new PlanarClipMaskSettings(args.exclude ? PlanarClipMaskMode.ExcludeElements : PlanarClipMaskMode.IncludeElements, args.transparency, modelIds, CompressedId64Set.sortAndCompress(args.elementIds), undefined, args.invert);\r\n    else\r\n      return new PlanarClipMaskSettings(PlanarClipMaskMode.Models, args.transparency, modelIds, undefined, undefined, args.invert);\r\n  }\r\n\r\n  /** Create JSON object representing this [[PlanarClipMaskSettings]] */\r\n  public toJSON(): PlanarClipMaskProps {\r\n    const props: PlanarClipMaskProps = { mode: this.mode };\r\n    if (undefined !== this._modelIds)\r\n      props.modelIds = this._modelIds;\r\n\r\n    if (undefined !== this._subCategoryOrElementIds)\r\n      props.subCategoryOrElementIds = this._subCategoryOrElementIds;\r\n\r\n    if (undefined !== this.priority)\r\n      props.priority = this.priority;\r\n\r\n    if (undefined !== this.transparency)\r\n      props.transparency = this.transparency;\r\n\r\n    if (this.invert)\r\n      props.invert = true;\r\n\r\n    return props;\r\n  }\r\n\r\n  /** Returns true if masking is enabled. */\r\n  public get isValid(): boolean {\r\n    return this.mode !== PlanarClipMaskMode.None;\r\n  }\r\n\r\n  public equals(other: PlanarClipMaskSettings): boolean {\r\n    return this.mode === other.mode &&\r\n      this.priority === other.priority &&\r\n      this.transparency === other.transparency &&\r\n      this.invert === other.invert &&\r\n      this._modelIds === other._modelIds &&\r\n      this._subCategoryOrElementIds === other._subCategoryOrElementIds;\r\n  }\r\n\r\n  /** Create a copy of this TerrainSettings, optionally modifying some of its properties.\r\n   * @param changedProps JSON representation of the properties to change.\r\n   * @returns A PlanarClipMaskSettings with all of its properties set to match those of`this`, except those explicitly defined in `changedProps`.\r\n   */\r\n  public clone(changedProps?: PlanarClipMaskProps): PlanarClipMaskSettings {\r\n    if (undefined === changedProps)\r\n      return this;\r\n\r\n    return PlanarClipMaskSettings.fromJSON({\r\n      ...this.toJSON(),\r\n      ...changedProps,\r\n    });\r\n  }\r\n\r\n  private constructor(mode: PlanarClipMaskMode, transparency?: number, modelIds?: CompressedId64Set, subCategoryOrElementIds?: CompressedId64Set, priority?: number, invert?: boolean) {\r\n    this.mode = mode;\r\n    this._modelIds = modelIds;\r\n    this._subCategoryOrElementIds = subCategoryOrElementIds;\r\n    this.priority = priority;\r\n    this.invert = true === invert;\r\n    this.transparency = undefined !== transparency ? Math.max(0, Math.min(1, transparency)) : undefined;\r\n\r\n    if (modelIds)\r\n      this.modelIds = CompressedId64Set.iterable(modelIds);\r\n\r\n    if (subCategoryOrElementIds)\r\n      this.subCategoryOrElementIds = CompressedId64Set.iterable(subCategoryOrElementIds);\r\n  }\r\n\r\n  /** A default PlanarClipMask which masks nothing. */\r\n  public static defaults = new PlanarClipMaskSettings(PlanarClipMaskMode.None);\r\n}\r\n"]}
+{"version":3,"file":"PlanarClipMask.js","sourceRoot":"","sources":["../../src/PlanarClipMask.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module DisplayStyles\r\n */\r\n\r\nimport { CompressedId64Set, Id64String, OrderedId64Iterable } from \"@itwin/core-bentley\";\r\n\r\n/** The different modes by which a [[PlanarClipMaskSettings]] collects the geometry used to mask a model.\r\n * @public\r\n * @extensions\r\n */\r\nexport enum PlanarClipMaskMode {\r\n  /** No masking. */\r\n  None = 0,\r\n  /** Mask based on priority. Different types of models have different default priorities as enumerated by [[PlanarClipMaskPriority]].\r\n   * For example, background maps have the lowest priority, so they are masked by all other types, while design models have the highest priority and are therefore never masked.\r\n   * The priority of a reality model can be overridden by [[PlanarClipMaskSettings.priority]]. This is useful to allow one reality model to mask another overlapping one.\r\n   * Everything visible in the view creates the mask, so turning off models, categories, or elements (via fully transparent overrides) will make things not be in the mask.\r\n   */\r\n  Priority = 1,\r\n  /** Indicates that masks should be produced from the geometry in a set of [GeometricModel]($backend)s, regardless of what model is on or off in the view.\r\n   * However, things that are off from category settings or element feature overrides in the view will not be in the mask for these models.\r\n   */\r\n  Models = 2,\r\n  /** Indicates that masks should be produced from geometry belonging to a set of subcategories.\r\n   * View settings do not affect what is in the mask, unless [[PlanarClipMaskSettings.subCategoryOrElementIds]] is undefined, in which case it behaves like Models mode.\r\n   */\r\n  IncludeSubCategories = 3,\r\n  /** Indicates that masks should be produced from the geometry of a set of [GeometricElement]($backend)s.\r\n   * View settings do not affect what is in the mask, unless [[PlanarClipMaskSettings.subCategoryOrElementIds]] is undefined, in which case it behaves like Models mode.\r\n   */\r\n  IncludeElements = 4,\r\n  /** Indicates that masks should be produced from the geometry of all [GeometricElement]($backend)s in a view, **except** for a specified set of excluded elements.\r\n   * View settings do not affect what is in the mask, unless [[PlanarClipMaskSettings.subCategoryOrElementIds]] is undefined, in which case it behaves like Models mode.\r\n   */\r\n  ExcludeElements = 5,\r\n}\r\n\r\n/** The default priority values for a [[PlanarClipMaskSettings]], based on model type. Models with a lower priority are masked by models with a higher priority.\r\n * The default can be overridden by [[PlanarClipMaskSettings.priority]].\r\n *  @public\r\n * @extensions\r\n */\r\nexport enum PlanarClipMaskPriority {\r\n  /** Background map. */\r\n  BackgroundMap = -2048,\r\n  /** A reality model that spans the globe - e.g., OpenStreetMaps Buildings. */\r\n  GlobalRealityModel = -1024,\r\n  /** A reality model with a bounded range. */\r\n  RealityModel = 0,\r\n  /** A design model stored in the [IModelDb]($backend). */\r\n  DesignModel = 2048,\r\n}\r\n\r\n/** JSON representation of a [[PlanarClipMaskSettings]].\r\n * @see [[DisplayStyleSettingsProps.planarClipOvr]] and [[ContextRealityModelProps.planarClipMask]].\r\n * @public\r\n * @extensions\r\n */\r\nexport interface PlanarClipMaskProps {\r\n  /** Controls how the mask geometry is collected */\r\n  mode: PlanarClipMaskMode;\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: CompressedId64Set;\r\n  /** See [[PlanarClipMaskSettings.subCategoryOrElementIds]]. */\r\n  subCategoryOrElementIds?: CompressedId64Set;\r\n  /** See [[PlanarClipMaskSettings.priority]]. */\r\n  priority?: number;\r\n  /** See [[PlanarClipMaskSettings.transparency]]. */\r\n  transparency?: number;\r\n  /** See PlanarClipMaskSettings.invert */\r\n  invert?: boolean;\r\n}\r\n\r\n/** Basic arguments supplied to [[PlanarClipMaskSettings.create]].\r\n * @public\r\n */\r\nexport interface BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.transparency]]. */\r\n  transparency?: number;\r\n  /** See [[PlanarClipMaskSettings.invert]]. */\r\n  invert?: boolean;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.Models]].\r\n * @public\r\n */\r\nexport interface ModelPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: Iterable<Id64String>;\r\n  /** @internal */\r\n  exclude?: never;\r\n  /** @internal */\r\n  elementIds?: never;\r\n  /** @internal */\r\n  subCategoryIds?: never;\r\n  /** @internal */\r\n  priority?: never;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.IncludeElements]] or [[PlanarClipMaskMode.ExcludeElements]].\r\n * @public\r\n */\r\nexport interface ElementPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: Iterable<Id64String>;\r\n  /** The elements used by the mask. @see [[PlanarClipMaskSettings.subCategoryOrElementIds]]. */\r\n  elementIds: Iterable<Id64String>;\r\n  /** If true, creates a mask of [[PlanarClipMaskMode.ExcludeElements]]; otherwise, [[PlanarClipMaskMode.IncludeElements]]. */\r\n  exclude?: boolean;\r\n  /** @internal */\r\n  subCategoryIds?: never;\r\n  /** @internal */\r\n  priority?: never;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.IncludeSubCategories]].\r\n * @public\r\n */\r\nexport interface SubCategoryPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.modelIds]]. */\r\n  modelIds?: Iterable<Id64String>;\r\n  /** The subcategories used by the mask. @see [[PlanarClipMaskSettings.subCategoryOrElementIds]]. */\r\n  subCategoryIds: Iterable<Id64String>;\r\n  /** @internal */\r\n  exclude?: never;\r\n  /** @internal */\r\n  elementIds?: never;\r\n  /** @internal */\r\n  priority?: never;\r\n}\r\n\r\n/** Arguments supplied to [[PlanarClipMaskSettings.create]] to create a mask of [[PlanarClipMaskMode.Priority]].\r\n * @public\r\n */\r\nexport interface PriorityPlanarClipMaskArgs extends BasicPlanarClipMaskArgs {\r\n  /** See [[PlanarClipMaskSettings.priority]]. */\r\n  priority: number;\r\n  /** @internal */\r\n  exclude?: never;\r\n  /** @internal */\r\n  elementIds?: never;\r\n  /** @internal */\r\n  modelIds?: never;\r\n}\r\n\r\n/** Describes how to mask the geometry of one [GeometricModel]($backend) for display. The mask is produced by projecting geometry from any number of other models -\r\n * optionally filtered by [SubCategory]($backend) or by a set of specific [GeometricElement]($backend)s - onto a plane. Regions of the masked model that intersect the\r\n * mask are rendered partially or completely transparent. This is useful for, e.g., making subsurface geometry visible below the background map, or clipping out portions\r\n * of a reality model that intersect a design model.\r\n * @note Currently reality models (including background maps and terrain) can be masked, but design models can only produce masks.\r\n * @see [[DisplayStyleSettings.planarClipMasks]] to define clip masks for a [DisplayStyle]($backend).\r\n * @see [[ContextRealityModel.planarClipMaskSettings]] to apply a clip mask to a context reality model.\r\n * @public\r\n */\r\nexport class PlanarClipMaskSettings {\r\n  /** Specifies how the mask geometry is produced. */\r\n  public readonly mode: PlanarClipMaskMode;\r\n  /** For any mode other than [[PlanarClipMaskMode.Priority]], the Ids of the [GeometricModel]($backend)s containing the geometry used to produce the mask,\r\n   * and if `undefined`, no mask geometry will be created.\r\n   * The mask geometry can be filtered by [[subCategoryOrElementIds]].\r\n   */\r\n  public readonly modelIds?: OrderedId64Iterable;\r\n  /** For [[PlanarClipMaskMode.IncludeElements]] or [[PlanarClipMaskMode.ExcludedElements]], the Ids of the [GeometricElement]($backend)s to include or exclude from masking;\r\n   * for [[PlanarClipMaskMode.IncludeSubCategories]], the Ids of the subcategories whose geometry contributes to the mask.\r\n   * If undefined, Modes IncludeSubCategories, IncludeElements, and ExcludeElements behave like Models mode.\r\n   */\r\n  public readonly subCategoryOrElementIds?: OrderedId64Iterable;\r\n  /** For [[PlanarClipMaskMode.Priority]], the priority value. */\r\n  public readonly priority?: number;\r\n  /** A value between 0 and 1 indicating an override for mask transparency. A transparency of 0 indicates complete masking. 1 is completely transparent (no masking).\r\n   If no transparency is defined then the transparencies of the mask elements are used.\r\n   */\r\n  public readonly transparency?: number;\r\n  /** A value of true indicates that the mask should be inverted and only content within the mask should be displayed, in other words the area inside the mask is displayed rather than outside. */\r\n  public readonly invert: boolean;\r\n  private readonly _modelIds?: CompressedId64Set;\r\n  private readonly _subCategoryOrElementIds?: CompressedId64Set;\r\n\r\n  /** The compressed representation of [[modelIds]]. */\r\n  public get compressedModelIds(): CompressedId64Set | undefined {\r\n    return this._modelIds;\r\n  }\r\n\r\n  /** Create a new [[PlanarClipMaskSettings]] object from its JSON representation. */\r\n  public static fromJSON(json?: PlanarClipMaskProps): PlanarClipMaskSettings {\r\n    if (!json || undefined === json.mode)\r\n      return this.defaults;\r\n\r\n    return new PlanarClipMaskSettings(json.mode, json.transparency, json.modelIds, json.subCategoryOrElementIds, json.priority, json.invert);\r\n  }\r\n\r\n  /** Create a new PlanarClipMaskSettings. */\r\n  public static create(args: ModelPlanarClipMaskArgs | ElementPlanarClipMaskArgs | SubCategoryPlanarClipMaskArgs | PriorityPlanarClipMaskArgs): PlanarClipMaskSettings {\r\n    const modelIds = args.modelIds ? CompressedId64Set.sortAndCompress(args.modelIds) : undefined;\r\n    if (undefined !== args.priority)\r\n      return new PlanarClipMaskSettings(PlanarClipMaskMode.Priority, args.transparency, undefined, undefined, args.priority, args.invert);\r\n    else if (undefined !== args.subCategoryIds)\r\n      return new PlanarClipMaskSettings(PlanarClipMaskMode.IncludeSubCategories, args.transparency, modelIds, CompressedId64Set.sortAndCompress(args.subCategoryIds), undefined, args.invert);\r\n    else if (undefined !== args.elementIds)\r\n      return new PlanarClipMaskSettings(args.exclude ? PlanarClipMaskMode.ExcludeElements : PlanarClipMaskMode.IncludeElements, args.transparency, modelIds, CompressedId64Set.sortAndCompress(args.elementIds), undefined, args.invert);\r\n    else\r\n      return new PlanarClipMaskSettings(PlanarClipMaskMode.Models, args.transparency, modelIds, undefined, undefined, args.invert);\r\n  }\r\n\r\n  /** Create JSON object representing this [[PlanarClipMaskSettings]] */\r\n  public toJSON(): PlanarClipMaskProps {\r\n    const props: PlanarClipMaskProps = { mode: this.mode };\r\n    if (undefined !== this._modelIds)\r\n      props.modelIds = this._modelIds;\r\n\r\n    if (undefined !== this._subCategoryOrElementIds)\r\n      props.subCategoryOrElementIds = this._subCategoryOrElementIds;\r\n\r\n    if (undefined !== this.priority)\r\n      props.priority = this.priority;\r\n\r\n    if (undefined !== this.transparency)\r\n      props.transparency = this.transparency;\r\n\r\n    if (this.invert)\r\n      props.invert = true;\r\n\r\n    return props;\r\n  }\r\n\r\n  /** Returns true if masking is enabled. */\r\n  public get isValid(): boolean {\r\n    return this.mode !== PlanarClipMaskMode.None;\r\n  }\r\n\r\n  public equals(other: PlanarClipMaskSettings): boolean {\r\n    return this.mode === other.mode &&\r\n      this.priority === other.priority &&\r\n      this.transparency === other.transparency &&\r\n      this.invert === other.invert &&\r\n      this._modelIds === other._modelIds &&\r\n      this._subCategoryOrElementIds === other._subCategoryOrElementIds;\r\n  }\r\n\r\n  /** Create a copy of this TerrainSettings, optionally modifying some of its properties.\r\n   * @param changedProps JSON representation of the properties to change.\r\n   * @returns A PlanarClipMaskSettings with all of its properties set to match those of`this`, except those explicitly defined in `changedProps`.\r\n   */\r\n  public clone(changedProps?: PlanarClipMaskProps): PlanarClipMaskSettings {\r\n    if (undefined === changedProps)\r\n      return this;\r\n\r\n    return PlanarClipMaskSettings.fromJSON({\r\n      ...this.toJSON(),\r\n      ...changedProps,\r\n    });\r\n  }\r\n\r\n  private constructor(mode: PlanarClipMaskMode, transparency?: number, modelIds?: CompressedId64Set, subCategoryOrElementIds?: CompressedId64Set, priority?: number, invert?: boolean) {\r\n    this.mode = mode;\r\n    this._modelIds = modelIds;\r\n    this._subCategoryOrElementIds = subCategoryOrElementIds;\r\n    this.priority = priority;\r\n    this.invert = true === invert;\r\n    this.transparency = undefined !== transparency ? Math.max(0, Math.min(1, transparency)) : undefined;\r\n\r\n    if (modelIds)\r\n      this.modelIds = CompressedId64Set.iterable(modelIds);\r\n\r\n    if (subCategoryOrElementIds)\r\n      this.subCategoryOrElementIds = CompressedId64Set.iterable(subCategoryOrElementIds);\r\n  }\r\n\r\n  /** A default PlanarClipMask which masks nothing. */\r\n  public static defaults = new PlanarClipMaskSettings(PlanarClipMaskMode.None);\r\n}\r\n"]}

package/lib/esm/annotation/TextAnnotation.d.ts

@@ -7,6 +7,7 @@ import { TextBlock, TextBlockProps } from "./TextBlock";
  * The anchor point is a point on or inside of the 2d bounding box enclosing the contents of the annotation's [[TextBlock]].
  * The annotation can be rotated and translated relative to the anchor point. The anchor point also serves as the snap point
  * when [AccuSnap]($frontend) is set to [SnapMode.Origin]($frontend).
+ * [[TextAnnotation.computeTransform]] will align the anchor point with (0, 0).
  * @see [[TextAnnotation]] for a description of how the anchor point is computed.
  * @beta
  */
@@ -91,7 +92,8 @@ export declare class TextAnnotation {
     /** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.
      * The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored
      * at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.
-     * The text block will be rotated around the fixed anchor point according to [[orientation]], then the anchor point will be translated by [[offset]].
+     * The text block will be rotated around the fixed anchor point according to [[orientation]], then translated by [[offset]].
+     * The anchor point will coincide with (0, 0, 0).
      * @param boundingBox A box fully containing the [[textBlock]].
      * @see [[computeAnchorPoint]] to compute the transform's anchor point.
      */

package/lib/esm/annotation/TextAnnotation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextAnnotation.d.ts","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAEtC;;;;;OAKG;IACH,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,sEAAsE;IACtE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IACzB;;OAEG;IACI,WAAW,EAAE,kBAAkB,CAAC;IACvC,8BAA8B;IACvB,SAAS,EAAE,SAAS,CAAC;IAC5B,iEAAiE;IAC1D,MAAM,EAAE,oBAAoB,CAAC;IACpC,8IAA8I;IACvI,MAAM,EAAE,OAAO,CAAC;IAEvB,OAAO;IAOP,oCAAoC;WACtB,MAAM,CAAC,IAAI,CAAC,EAAE,wBAAwB,GAAG,cAAc;IASrE;;OAEG;WACW,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,GAAG,cAAc;IAS9E;;OAEG;IACI,MAAM,IAAI,mBAAmB;IAsBpC;;;;;;OAMG;IACI,gBAAgB,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS;IASxD;;;OAGG;IACI,kBAAkB,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO;IAyBxD,0EAA0E;IACnE,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;CAK9C"}
+{"version":3,"file":"TextAnnotation.d.ts","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACpH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAEtC;;;;;OAKG;IACH,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,sEAAsE;IACtE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IACzB;;OAEG;IACI,WAAW,EAAE,kBAAkB,CAAC;IACvC,8BAA8B;IACvB,SAAS,EAAE,SAAS,CAAC;IAC5B,iEAAiE;IAC1D,MAAM,EAAE,oBAAoB,CAAC;IACpC,8IAA8I;IACvI,MAAM,EAAE,OAAO,CAAC;IAEvB,OAAO;IAOP,oCAAoC;WACtB,MAAM,CAAC,IAAI,CAAC,EAAE,wBAAwB,GAAG,cAAc;IASrE;;OAEG;WACW,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,GAAG,cAAc;IAS9E;;OAEG;IACI,MAAM,IAAI,mBAAmB;IAsBpC;;;;;;;OAOG;IACI,gBAAgB,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS;IASxD;;;OAGG;IACI,kBAAkB,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO;IAyBxD,0EAA0E;IACnE,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;CAK9C"}

package/lib/esm/annotation/TextAnnotation.js

@@ -68,7 +68,8 @@ export class TextAnnotation {
     /** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.
      * The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored
      * at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.
-     * The text block will be rotated around the fixed anchor point according to [[orientation]], then the anchor point will be translated by [[offset]].
+     * The text block will be rotated around the fixed anchor point according to [[orientation]], then translated by [[offset]].
+     * The anchor point will coincide with (0, 0, 0).
      * @param boundingBox A box fully containing the [[textBlock]].
      * @see [[computeAnchorPoint]] to compute the transform's anchor point.
      */
@@ -76,7 +77,7 @@ export class TextAnnotation {
         const anchorPt = this.computeAnchorPoint(boundingBox);
         const matrix = this.orientation.toMatrix3d();
         const rotation = Transform.createFixedPointAndMatrix(anchorPt, matrix);
-        const translation = Transform.createTranslation(this.offset);
+        const translation = Transform.createTranslation(this.offset.minus(anchorPt));
         return translation.multiplyTransformTransform(rotation, rotation);
     }
     /** Compute the anchor point of this annotation as specified by [[anchor]].

package/lib/esm/annotation/TextAnnotation.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextAnnotation.js","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Annotation\r\n */\r\n\r\nimport { Point3d, Range2d, Transform, XYZProps, YawPitchRollAngles, YawPitchRollProps } from \"@itwin/core-geometry\";\r\nimport { TextBlock, TextBlockProps } from \"./TextBlock\";\r\n\r\n/** Describes how to compute the \"anchor point\" for a [[TextAnnotation]].\r\n * The anchor point is a point on or inside of the 2d bounding box enclosing the contents of the annotation's [[TextBlock]].\r\n * The annotation can be rotated and translated relative to the anchor point. The anchor point also serves as the snap point\r\n * when [AccuSnap]($frontend) is set to [SnapMode.Origin]($frontend).\r\n * @see [[TextAnnotation]] for a description of how the anchor point is computed.\r\n * @beta\r\n */\r\nexport interface TextAnnotationAnchor {\r\n  /**\r\n   * The vertical alignment of the anchor point.\r\n   * \"top\" aligns the anchor point with the top of the text's bounding box.\r\n   * \"middle\" aligns the anchor point with the middle of the text's bounding box.\r\n   * \"bottom\" aligns the anchor point with the bottom of the text's bounding box.\r\n   */\r\n  vertical: \"top\" | \"middle\" | \"bottom\";\r\n\r\n  /**\r\n   * The horizontal alignment of the anchor point.\r\n   * \"left\" aligns the anchor point with left side of the text's bounding box.\r\n   * \"center\" aligns the anchor point with center of the text with's bounding box.\r\n   * \"right\" aligns the anchor point with right side of the text's bounding box.\r\n   */\r\n  horizontal: \"left\" | \"center\" | \"right\";\r\n}\r\n\r\n/**\r\n * JSON representation of a [[TextAnnotation]].\r\n * @beta\r\n */\r\nexport interface TextAnnotationProps {\r\n  /** See [[TextAnnotation.offset]]. Default: [0, 0, 0]. */\r\n  offset?: XYZProps;\r\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\r\n  orientation?: YawPitchRollProps;\r\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\r\n  textBlock?: TextBlockProps;\r\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\r\n  anchor?: TextAnnotationAnchor;\r\n}\r\n\r\n/** Arguments supplied to [[TextAnnotation.create]].\r\n * @beta\r\n */\r\nexport interface TextAnnotationCreateArgs {\r\n  /** See [[TextAnnotation.offset]]. Default: (0, 0, 0). */\r\n  offset?: Point3d;\r\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\r\n  orientation?: YawPitchRollAngles;\r\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\r\n  textBlock?: TextBlock;\r\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\r\n  anchor?: TextAnnotationAnchor;\r\n}\r\n\r\n/**\r\n * Represents a formatted block of text positioned in 2d or 3d space.\r\n * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a single TextAnnotation from which their geometric representation is generated.\r\n * Other types of elements may store multiple TextAnnotations, positioned relative to one another.\r\n * The annotation's position and orientation relative to the host element's [Placement]($common) is determined as follows:\r\n * - First, a bounding box is computed enclosing the contents of the [[textBlock].\r\n * - Then, an \"anchor point\" is computed based on the bounding box and the [[anchor]] property. The anchor point can be at one of the four corners of the box, in the middle of one of its four\r\n * edges, or in the center of the box.\r\n * - The [[orientation]] is applied to rotate the box around the anchor point.\r\n * - Finally, the [[offset]] is added to the anchor point to apply translation.\r\n * @see [produceTextAnnotationGeometry]($backend) to decompose the annotation into a set of geometric primitives suitable for use with [[GeometryStreamBuilder.appendTextBlock]].\r\n * @beta\r\n */\r\nexport class TextAnnotation {\r\n  /** The rotation of the annotation.\r\n   * @note When defining an annotation for a [TextAnnotation2d]($backend), only the `yaw` component (rotation around the Z axis) is used.\r\n   */\r\n  public orientation: YawPitchRollAngles;\r\n  /** The formatted document. */\r\n  public textBlock: TextBlock;\r\n  /** Describes how to compute the [[textBlock]]'s anchor point. */\r\n  public anchor: TextAnnotationAnchor;\r\n  /** An offset applied to the anchor point that can be used to position annotations within the same geometry stream relative to one another. */\r\n  public offset: Point3d;\r\n\r\n  private constructor(offset: Point3d, angles: YawPitchRollAngles, textBlock: TextBlock, anchor: TextAnnotationAnchor) {\r\n    this.offset = offset;\r\n    this.orientation = angles;\r\n    this.textBlock = textBlock;\r\n    this.anchor = anchor;\r\n  }\r\n\r\n  /** Creates a new TextAnnotation. */\r\n  public static create(args?: TextAnnotationCreateArgs): TextAnnotation {\r\n    const offset = args?.offset ?? new Point3d();\r\n    const angles = args?.orientation ?? new YawPitchRollAngles();\r\n    const textBlock = args?.textBlock ?? TextBlock.createEmpty();\r\n    const anchor = args?.anchor ?? { vertical: \"top\", horizontal: \"left\" };\r\n\r\n    return new TextAnnotation(offset, angles, textBlock, anchor);\r\n  }\r\n\r\n  /**\r\n   * Creates a new TextAnnotation instance from its JSON representation.\r\n   */\r\n  public static fromJSON(props: TextAnnotationProps | undefined): TextAnnotation {\r\n    return TextAnnotation.create({\r\n      offset: props?.offset ? Point3d.fromJSON(props.offset) : undefined,\r\n      orientation: props?.orientation ? YawPitchRollAngles.fromJSON(props.orientation) : undefined,\r\n      textBlock: props?.textBlock ? TextBlock.create(props.textBlock) : undefined,\r\n      anchor: props?.anchor ? { ...props.anchor } : undefined,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Converts this annotation to its JSON representation.\r\n   */\r\n  public toJSON(): TextAnnotationProps {\r\n    const props: TextAnnotationProps = {};\r\n\r\n    // Even if the text block is empty, we want to record its style name and overrides, e.g.,\r\n    // so the user can pick up where they left off editing it next time.\r\n    props.textBlock = this.textBlock.toJSON();\r\n\r\n    if (!this.offset.isZero) {\r\n      props.offset = this.offset.toJSON();\r\n    }\r\n\r\n    if (!this.orientation.isIdentity()) {\r\n      props.orientation = this.orientation.toJSON();\r\n    }\r\n\r\n    if (this.anchor.vertical !== \"top\" || this.anchor.horizontal !== \"left\") {\r\n      props.anchor = { ...this.anchor };\r\n    }\r\n\r\n    return props;\r\n  }\r\n\r\n  /** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.\r\n   * The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored\r\n   * at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.\r\n   * The text block will be rotated around the fixed anchor point according to [[orientation]], then the anchor point will be translated by [[offset]].\r\n   * @param boundingBox A box fully containing the [[textBlock]].\r\n   * @see [[computeAnchorPoint]] to compute the transform's anchor point.\r\n   */\r\n  public computeTransform(boundingBox: Range2d): Transform {\r\n    const anchorPt = this.computeAnchorPoint(boundingBox);\r\n    const matrix = this.orientation.toMatrix3d();\r\n\r\n    const rotation = Transform.createFixedPointAndMatrix(anchorPt, matrix);\r\n    const translation = Transform.createTranslation(this.offset);\r\n    return translation.multiplyTransformTransform(rotation, rotation);\r\n  }\r\n\r\n  /** Compute the anchor point of this annotation as specified by [[anchor]].\r\n   * @param boundingBox A box fully containing the [[textBlock]].\r\n   * @see [[computeTransform]] to compute the transform relative to the anchor point.\r\n   */\r\n  public computeAnchorPoint(boundingBox: Range2d): Point3d {\r\n    let x = boundingBox.low.x;\r\n    let y = boundingBox.high.y;\r\n\r\n    switch (this.anchor.horizontal) {\r\n      case \"center\":\r\n        x += boundingBox.xLength() / 2;\r\n        break;\r\n      case \"right\":\r\n        x += boundingBox.xLength();\r\n        break;\r\n    }\r\n\r\n    switch (this.anchor.vertical) {\r\n      case \"middle\":\r\n        y -= boundingBox.yLength() / 2;\r\n        break;\r\n      case \"bottom\":\r\n        y -= boundingBox.yLength();\r\n        break;\r\n    }\r\n\r\n    return new Point3d(x, y, 0);\r\n  }\r\n\r\n  /** Returns true if this annotation is logically equivalent to `other`. */\r\n  public equals(other: TextAnnotation): boolean {\r\n    return this.anchor.horizontal === other.anchor.horizontal && this.anchor.vertical === other.anchor.vertical\r\n      && this.orientation.isAlmostEqual(other.orientation) && this.offset.isAlmostEqual(other.offset)\r\n      && this.textBlock.equals(other.textBlock);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"TextAnnotation.js","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Annotation\r\n */\r\n\r\nimport { Point3d, Range2d, Transform, XYZProps, YawPitchRollAngles, YawPitchRollProps } from \"@itwin/core-geometry\";\r\nimport { TextBlock, TextBlockProps } from \"./TextBlock\";\r\n\r\n/** Describes how to compute the \"anchor point\" for a [[TextAnnotation]].\r\n * The anchor point is a point on or inside of the 2d bounding box enclosing the contents of the annotation's [[TextBlock]].\r\n * The annotation can be rotated and translated relative to the anchor point. The anchor point also serves as the snap point\r\n * when [AccuSnap]($frontend) is set to [SnapMode.Origin]($frontend).\r\n * [[TextAnnotation.computeTransform]] will align the anchor point with (0, 0).\r\n * @see [[TextAnnotation]] for a description of how the anchor point is computed.\r\n * @beta\r\n */\r\nexport interface TextAnnotationAnchor {\r\n  /**\r\n   * The vertical alignment of the anchor point.\r\n   * \"top\" aligns the anchor point with the top of the text's bounding box.\r\n   * \"middle\" aligns the anchor point with the middle of the text's bounding box.\r\n   * \"bottom\" aligns the anchor point with the bottom of the text's bounding box.\r\n   */\r\n  vertical: \"top\" | \"middle\" | \"bottom\";\r\n\r\n  /**\r\n   * The horizontal alignment of the anchor point.\r\n   * \"left\" aligns the anchor point with left side of the text's bounding box.\r\n   * \"center\" aligns the anchor point with center of the text with's bounding box.\r\n   * \"right\" aligns the anchor point with right side of the text's bounding box.\r\n   */\r\n  horizontal: \"left\" | \"center\" | \"right\";\r\n}\r\n\r\n/**\r\n * JSON representation of a [[TextAnnotation]].\r\n * @beta\r\n */\r\nexport interface TextAnnotationProps {\r\n  /** See [[TextAnnotation.offset]]. Default: [0, 0, 0]. */\r\n  offset?: XYZProps;\r\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\r\n  orientation?: YawPitchRollProps;\r\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\r\n  textBlock?: TextBlockProps;\r\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\r\n  anchor?: TextAnnotationAnchor;\r\n}\r\n\r\n/** Arguments supplied to [[TextAnnotation.create]].\r\n * @beta\r\n */\r\nexport interface TextAnnotationCreateArgs {\r\n  /** See [[TextAnnotation.offset]]. Default: (0, 0, 0). */\r\n  offset?: Point3d;\r\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\r\n  orientation?: YawPitchRollAngles;\r\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\r\n  textBlock?: TextBlock;\r\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\r\n  anchor?: TextAnnotationAnchor;\r\n}\r\n\r\n/**\r\n * Represents a formatted block of text positioned in 2d or 3d space.\r\n * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a single TextAnnotation from which their geometric representation is generated.\r\n * Other types of elements may store multiple TextAnnotations, positioned relative to one another.\r\n * The annotation's position and orientation relative to the host element's [Placement]($common) is determined as follows:\r\n * - First, a bounding box is computed enclosing the contents of the [[textBlock].\r\n * - Then, an \"anchor point\" is computed based on the bounding box and the [[anchor]] property. The anchor point can be at one of the four corners of the box, in the middle of one of its four\r\n * edges, or in the center of the box.\r\n * - The [[orientation]] is applied to rotate the box around the anchor point.\r\n * - Finally, the [[offset]] is added to the anchor point to apply translation.\r\n * @see [produceTextAnnotationGeometry]($backend) to decompose the annotation into a set of geometric primitives suitable for use with [[GeometryStreamBuilder.appendTextBlock]].\r\n * @beta\r\n */\r\nexport class TextAnnotation {\r\n  /** The rotation of the annotation.\r\n   * @note When defining an annotation for a [TextAnnotation2d]($backend), only the `yaw` component (rotation around the Z axis) is used.\r\n   */\r\n  public orientation: YawPitchRollAngles;\r\n  /** The formatted document. */\r\n  public textBlock: TextBlock;\r\n  /** Describes how to compute the [[textBlock]]'s anchor point. */\r\n  public anchor: TextAnnotationAnchor;\r\n  /** An offset applied to the anchor point that can be used to position annotations within the same geometry stream relative to one another. */\r\n  public offset: Point3d;\r\n\r\n  private constructor(offset: Point3d, angles: YawPitchRollAngles, textBlock: TextBlock, anchor: TextAnnotationAnchor) {\r\n    this.offset = offset;\r\n    this.orientation = angles;\r\n    this.textBlock = textBlock;\r\n    this.anchor = anchor;\r\n  }\r\n\r\n  /** Creates a new TextAnnotation. */\r\n  public static create(args?: TextAnnotationCreateArgs): TextAnnotation {\r\n    const offset = args?.offset ?? new Point3d();\r\n    const angles = args?.orientation ?? new YawPitchRollAngles();\r\n    const textBlock = args?.textBlock ?? TextBlock.createEmpty();\r\n    const anchor = args?.anchor ?? { vertical: \"top\", horizontal: \"left\" };\r\n\r\n    return new TextAnnotation(offset, angles, textBlock, anchor);\r\n  }\r\n\r\n  /**\r\n   * Creates a new TextAnnotation instance from its JSON representation.\r\n   */\r\n  public static fromJSON(props: TextAnnotationProps | undefined): TextAnnotation {\r\n    return TextAnnotation.create({\r\n      offset: props?.offset ? Point3d.fromJSON(props.offset) : undefined,\r\n      orientation: props?.orientation ? YawPitchRollAngles.fromJSON(props.orientation) : undefined,\r\n      textBlock: props?.textBlock ? TextBlock.create(props.textBlock) : undefined,\r\n      anchor: props?.anchor ? { ...props.anchor } : undefined,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Converts this annotation to its JSON representation.\r\n   */\r\n  public toJSON(): TextAnnotationProps {\r\n    const props: TextAnnotationProps = {};\r\n\r\n    // Even if the text block is empty, we want to record its style name and overrides, e.g.,\r\n    // so the user can pick up where they left off editing it next time.\r\n    props.textBlock = this.textBlock.toJSON();\r\n\r\n    if (!this.offset.isZero) {\r\n      props.offset = this.offset.toJSON();\r\n    }\r\n\r\n    if (!this.orientation.isIdentity()) {\r\n      props.orientation = this.orientation.toJSON();\r\n    }\r\n\r\n    if (this.anchor.vertical !== \"top\" || this.anchor.horizontal !== \"left\") {\r\n      props.anchor = { ...this.anchor };\r\n    }\r\n\r\n    return props;\r\n  }\r\n\r\n  /** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.\r\n   * The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored\r\n   * at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.\r\n   * The text block will be rotated around the fixed anchor point according to [[orientation]], then translated by [[offset]].\r\n   * The anchor point will coincide with (0, 0, 0).\r\n   * @param boundingBox A box fully containing the [[textBlock]].\r\n   * @see [[computeAnchorPoint]] to compute the transform's anchor point.\r\n   */\r\n  public computeTransform(boundingBox: Range2d): Transform {\r\n    const anchorPt = this.computeAnchorPoint(boundingBox);\r\n    const matrix = this.orientation.toMatrix3d();\r\n\r\n    const rotation = Transform.createFixedPointAndMatrix(anchorPt, matrix);\r\n    const translation = Transform.createTranslation(this.offset.minus(anchorPt));\r\n    return translation.multiplyTransformTransform(rotation, rotation);\r\n  }\r\n\r\n  /** Compute the anchor point of this annotation as specified by [[anchor]].\r\n   * @param boundingBox A box fully containing the [[textBlock]].\r\n   * @see [[computeTransform]] to compute the transform relative to the anchor point.\r\n   */\r\n  public computeAnchorPoint(boundingBox: Range2d): Point3d {\r\n    let x = boundingBox.low.x;\r\n    let y = boundingBox.high.y;\r\n\r\n    switch (this.anchor.horizontal) {\r\n      case \"center\":\r\n        x += boundingBox.xLength() / 2;\r\n        break;\r\n      case \"right\":\r\n        x += boundingBox.xLength();\r\n        break;\r\n    }\r\n\r\n    switch (this.anchor.vertical) {\r\n      case \"middle\":\r\n        y -= boundingBox.yLength() / 2;\r\n        break;\r\n      case \"bottom\":\r\n        y -= boundingBox.yLength();\r\n        break;\r\n    }\r\n\r\n    return new Point3d(x, y, 0);\r\n  }\r\n\r\n  /** Returns true if this annotation is logically equivalent to `other`. */\r\n  public equals(other: TextAnnotation): boolean {\r\n    return this.anchor.horizontal === other.anchor.horizontal && this.anchor.vertical === other.anchor.vertical\r\n      && this.orientation.isAlmostEqual(other.orientation) && this.offset.isAlmostEqual(other.offset)\r\n      && this.textBlock.equals(other.textBlock);\r\n  }\r\n}\r\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itwin/core-common",
-  "version": "4.8.0-dev.4",
+  "version": "4.8.0-dev.5",
   "description": "iTwin.js components common to frontend and backend",
   "main": "lib/cjs/core-common.js",
   "module": "lib/esm/core-common.js",
@@ -27,8 +27,8 @@
     "js-base64": "^3.6.1"
   },
   "peerDependencies": {
-    "@itwin/core-bentley": "^4.8.0-dev.4",
-    "@itwin/core-geometry": "^4.8.0-dev.4"
+    "@itwin/core-bentley": "^4.8.0-dev.5",
+    "@itwin/core-geometry": "^4.8.0-dev.5"
   },
   "devDependencies": {
     "@itwin/eslint-plugin": "^4.0.2",
@@ -43,9 +43,9 @@
     "nyc": "^15.1.0",
     "rimraf": "^3.0.2",
     "typescript": "~5.3.3",
-    "@itwin/build-tools": "4.8.0-dev.4",
-    "@itwin/core-bentley": "4.8.0-dev.4",
-    "@itwin/core-geometry": "4.8.0-dev.4"
+    "@itwin/build-tools": "4.8.0-dev.5",
+    "@itwin/core-bentley": "4.8.0-dev.5",
+    "@itwin/core-geometry": "4.8.0-dev.5"
   },
   "nyc": {
     "extends": "./node_modules/@itwin/build-tools/.nycrc",