@itwin/core-backend/lib/cjs/ExportGraphics.d.ts

iTwin.js backend components

/** @packageDocumentation
 * @module ExportGraphics
 */
import { Id64Array, Id64String } from "@itwin/core-bentley";
import { IndexedPolyface, Polyface, PolyfaceData, PolyfaceVisitor } from "@itwin/core-geometry";
import { ColorDefProps, GeometryClass } from "@itwin/core-common";
/** A collection of line segments, suitable for direct use with graphics APIs.
 * The structure of this data matches GL_LINES in OpenGL.
 * See [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export interface ExportGraphicsLines {
    /** Zero-based vertex indices, every two indices represent a line segment */
    indices: Int32Array;
    /** Vertices for these lines, laid out in the pattern XYZXYZ */
    points: Float64Array;
}
/** Info provided to ExportLinesFunction about linework graphics.
 * See [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export interface ExportLinesInfo {
    /** The element ID for the element the graphics originated from */
    elementId: Id64String;
    /** ID for the [SubCategory]($core-backend) for these graphics  */
    subCategory: Id64String;
    /** The color and transparency for these graphics */
    color: ColorDefProps;
    /** GeometryClass for these graphics */
    geometryClass: GeometryClass;
    /** The linework for these graphics */
    lines: ExportGraphicsLines;
}
/** A callback function that receives generated line graphics.
 * See [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export type ExportLinesFunction = (info: ExportLinesInfo) => void;
/** A triangulated mesh with unified indices, suitable for direct use with graphics APIs.
 * See [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export interface ExportGraphicsMesh {
    /** Zero-based vertex indices, every three indices represent a triangle */
    indices: Int32Array;
    /** Vertices for this mesh, laid out in the pattern XYZXYZ */
    points: Float64Array;
    /** Normals for this mesh, laid out in the pattern XYZXYZ */
    normals: Float32Array;
    /** Parameters (uvs) for this mesh, laid out in the pattern XYXY */
    params: Float32Array;
    /** If true, clients should assume both sides of the mesh are visible and not cull back faces. */
    isTwoSided: boolean;
}
/** Info provided to ExportGraphicsFunction about graphics.
 * See [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export interface ExportGraphicsInfo {
    /** The element ID for the element the graphics originated from */
    elementId: Id64String;
    /** ID for the [SubCategory]($core-backend) for these graphics  */
    subCategory: Id64String;
    /** The color and transparency for these graphics */
    color: ColorDefProps;
    /** GeometryClass for these graphics */
    geometryClass: GeometryClass;
    /** If defined, ID for the [RenderMaterialElement]($core-backend) for these graphics */
    materialId?: Id64String;
    /** If defined, ID for the [Texture]($core-backend) for these graphics  */
    textureId?: Id64String;
    /** The mesh for these graphics */
    mesh: ExportGraphicsMesh;
}
/** Information about the base display properties when a [GeometryPart]($core-backend) was
 * referenced. This is intended to be used with [IModelDb.exportPartGraphics]($core-backend).
 *  * If two ExportPartInstanceInfo have the same ExportPartDisplayInfos, they will result in the
 *    same graphics (with a different transform).
 *  * If two ExportPartInstanceInfo have different ExportPartDisplayInfos, they may result in different
 *    graphics.
 * @public
 */
export interface ExportPartDisplayInfo {
    categoryId: Id64String;
    subCategoryId: Id64String;
    geometryClass: GeometryClass;
    materialId: Id64String;
    elmTransparency: number;
    lineColor: number;
}
/** Information about references to [GeometryPart]($core-backend) elements found during
 * a call to [IModelDb.exportGraphics]($core-backend).
 * See [IModelDb.exportPartGraphics]($core-backend) for the intended use case.
 * @public
 */
export interface ExportPartInstanceInfo {
    /** ID for the [GeometryPart]($core-backend) */
    partId: Id64String;
    /** ID for the element that contained the reference to the [GeometryPart]($core-backend) */
    partInstanceId: Id64String;
    /** The base display properties when the [GeometryPart]($core-backend) was referenced. */
    displayProps: ExportPartDisplayInfo;
    /** A row-major storage 4x3 transform for this instance.
     *  See export-gltf under test-apps in the iTwin.js monorepo for a working reference.
     */
    transform?: Float64Array;
}
/** A callback function that receives generated graphics.
 * See [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export type ExportGraphicsFunction = (info: ExportGraphicsInfo) => void;
/** Parameters for [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export interface ExportGraphicsOptions {
    /** The source elements for the exported graphics */
    elementIdArray: Id64Array;
    /** A function to call for each unique element ID, color and texture combination */
    onGraphics: ExportGraphicsFunction;
    /** An optional function to call if line graphics are desired. */
    onLineGraphics?: ExportLinesFunction;
    /** If supplied, any references to [GeometryPart]($core-backend) elements found will be
     * recorded in this array. In this case, graphics that would result from the GeometryPart
     * will not be supplied via onGraphics. See [IModelDb.exportPartGraphics]($core-backend)
     */
    partInstanceArray?: ExportPartInstanceInfo[];
    /** Max distance from a face to the original geometry, see [StrokeOptions]($core-geometry).
     * If not supplied, defaults to zero and angleTol will control the quality of the resulting mesh.
     */
    chordTol?: number;
    /** Max angle difference in radians for approximated face, see [StrokeOptions]($core-geometry).
     * If not supplied, defaults to PI/12 (15 degrees).
     */
    angleTol?: number;
    /** Max length of any edge in generated faces, see [StrokeOptions]($core-geometry).
     * If not supplied, there is no maximum length of an edge. Supplying this value can greatly increase the
     * size of the resulting geometry, and should only be done in cases where necessary (if you don't know
     * that it's necessary, it's almost certainly not!)
     */
    maxEdgeLength?: number;
    /** The longest dimension of a line style's largest component must be at least this size in order for
     * exportGraphics to evaluate and generate its graphics. If undefined, this defaults to 0.1.
     * Line styles can evaluate to 3D geometry that clients expect to receive from exportGraphics, but they
     * can also generate gigabytes of mesh data when line styles with small components are applied to long
     * line strings.
     */
    minLineStyleComponentSize?: number;
    /** Max distance between mesh vertices for them to be collapsed.
     * Meshes stored in GeometryStreams are unaffected by StrokeOptions settings. If decimationTol is undefined,
     * they are output from exportGraphics without any reduction in quality and can be too detailed for
     * some uses. However, decimation is a destructive operation that can introduce gaps and other visual
     * anomalies so it is important to choose an appropriate setting for your use case.
     */
    decimationTol?: number;
    /** BRep features with bounding boxes smaller than this size will not generate graphics.
     * This option can be used to ignore expensive details from [BRepEntity.DataProps]($core-common)
     * like screws and screw holes.
     */
    minBRepFeatureSize?: number;
}
/** Info provided to ExportPartFunction about graphics.
 * See [IModelDb.exportPartGraphics]($core-backend)
 * @public
 */
export interface ExportPartInfo {
    /** The color and transparency for these graphics */
    color: ColorDefProps;
    /** GeometryClass for these graphics */
    geometryClass: GeometryClass;
    /** If defined, ID for the [RenderMaterialElement]($core-backend) for these graphics */
    materialId?: Id64String;
    /** If defined, ID for the [Texture]($core-backend) for these graphics  */
    textureId?: Id64String;
    /** The mesh for these graphics */
    mesh: ExportGraphicsMesh;
}
/** A callback function that receives generated graphics for a [GeometryPart]($core-backend).
 * See [IModelDb.exportPartGraphics]($core-backend)
 * @public
 */
export type ExportPartFunction = (info: ExportPartInfo) => void;
/** Info provided to ExportPartFunction about line graphics.
 * See [IModelDb.exportPartGraphics]($core-backend)
 * @public
 */
export interface ExportPartLinesInfo {
    /** The color and transparency for these graphics */
    color: ColorDefProps;
    /** GeometryClass for these graphics */
    geometryClass: GeometryClass;
    /** The linework for these graphics */
    lines: ExportGraphicsLines;
}
/** A callback function that receives generated line graphics for a [GeometryPart]($core-backend).
 * See [IModelDb.exportPartGraphics]($core-backend)
 * @public
 */
export type ExportPartLinesFunction = (info: ExportPartLinesInfo) => void;
/** Parameters for [IModelDb.exportPartGraphics]($core-backend)
 * @public
 */
export interface ExportPartGraphicsOptions {
    /** The ID for the source [GeometryPart]($core-backend) */
    elementId: Id64String;
    /** The base display properties to use for generating the graphics. This should come from an
     * ExportPartInstanceProps generated by [IModelDb.exportGraphics]($core-backend)
     */
    displayProps: ExportPartDisplayInfo;
    /** A function to call for each unique color and texture combination. */
    onPartGraphics: ExportPartFunction;
    /** An optional function to call if line graphics are desired. */
    onPartLineGraphics?: ExportPartLinesFunction;
    /** Max distance from a face to the original geometry, see [StrokeOptions]($core-geometry).
     * If not supplied, defaults to zero and angleTol will control the quality of the resulting mesh.
     */
    chordTol?: number;
    /** Max angle difference in radians for approximated face, see [StrokeOptions]($core-geometry).
     * If not supplied, defaults to PI/12 (15 degrees).
     */
    angleTol?: number;
    /** Max length of any edge in generated faces, see [StrokeOptions]($core-geometry)
     * If not supplied, there is no maximum length of an edge. Supplying this value can greatly increase the
     * size of the resulting geometry, and should only be done in cases where necessary (if you don't know
     * that it's necessary, it's almost certainly not!)
     */
    maxEdgeLength?: number;
    /** The longest dimension of a line style's largest component must be at least this size in order for
     * exportGraphics to evaluate and generate its graphics. If undefined, this defaults to 0.1.
     * Line styles can evaluate to 3D geometry that clients expect to receive from exportGraphics, but they
     * can also generate gigabytes of mesh data when line styles with small components are applied to long
     * line strings.
     */
    minLineStyleComponentSize?: number;
    /** Max distance between mesh vertices for them to be collapsed.
     * Meshes stored in GeometryStreams are unaffected by StrokeOptions settings. If decimationTol is undefined,
     * they are output from exportGraphics without any reduction in quality and can be too detailed for
     * some uses. However, decimation is a destructive operation that can introduce gaps and other visual
     * anomalies so it is important to choose an appropriate setting for your use case.
     */
    decimationTol?: number;
    /** BRep features with bounding boxes smaller than this size will not generate graphics.
     * This option can be used to ignore expensive details from [BRepEntity.DataProps]($core-common)
     * like screws and screw holes.
     */
    minBRepFeatureSize?: number;
}
/** Provides utility functions for working with data generated by [IModelDb.exportGraphics]($core-backend)
 * @public
 */
export declare namespace ExportGraphics {
    /** Test if ExportPartDisplayInfos have exactly the same values.
     * @public
     */
    function arePartDisplayInfosEqual(lhs: ExportPartDisplayInfo, rhs: ExportPartDisplayInfo): boolean;
    /**
     * Convert an ExportGraphicsMesh to an IndexedPolyface usable by the geometry API.
     * @note The resulting IndexedPolyface may have duplicate points, normals and params. If problematic, call [PolyfaceData.compress]($core-geometry)
     * @public
     */
    function convertToIndexedPolyface(mesh: ExportGraphicsMesh): IndexedPolyface;
}
/**
 * * Iterator to walk the facets of an ExportGraphicsMesh and present them to the world as if visiting a Polyface.
 * * Because the ExportGraphicsMesh has limited data:
 *   * There is no auxData in this visitor.
 *   * There is no color in this visitor.
 *   * All edgeVisible are true.
 * @public
 */
export declare class ExportGraphicsMeshVisitor extends PolyfaceData implements PolyfaceVisitor {
    private _currentFacetIndex;
    private _nextFacetIndex;
    private _numWrap;
    private _polyface;
    protected constructor(facets: ExportGraphicsMesh, numWrap: number);
    /** Create a visitor for iterating the facets of `polyface`, with indicated number of points to be added to each facet to produce closed point arrays
     * Typical wrap counts are:
     * * 0 -- leave the point arrays with "missing final edge" (default)
     * * 1 -- add point 0 as closure point
     * * 2 -- add points 0 and 1 as closure and wrap point.  This is useful when vertex visit requires two adjacent vectors, e.g. for cross products.
     */
    static create(polyface: ExportGraphicsMesh, numWrap?: number): ExportGraphicsMeshVisitor;
    /** Restart the visitor at the first facet. */
    reset(): void;
    /** Select a facet by simple index. */
    moveToReadIndex(facetIndex: number): boolean;
    /** Load data for the next facet. */
    moveToNextFacet(): boolean;
    /** Set the number of vertices to replicate in visitor arrays. */
    setNumWrap(numWrap: number): void;
    /** Return the index (in the client polyface) of the current facet */
    currentReadIndex(): number;
    /** Return the point index of vertex i within the currently loaded facet */
    clientPointIndex(i: number): number;
    /** Return the param index of vertex i within the currently loaded facet.
     * Use the artificial paramIndex, which matches pointIndex.
     */
    clientParamIndex(i: number): number;
    /** Return the normal index of vertex i within the currently loaded facet.
     * Use the artificial paramIndex, which matches pointIndex.
     */
    clientNormalIndex(i: number): number;
    /** Always returns -1 since we never have colors. */
    clientColorIndex(_i: number): number;
    /** Always returns -1 since we never have auxiliary data. */
    clientAuxIndex(_i: number): number;
    /** return the client polyface */
    clientPolyface(): Polyface | undefined;
    /** clear the contents of all arrays.  Use this along with transferDataFrom methods to build up new facets */
    clearArrays(): void;
    /** transfer interpolated data from the other visitor.
     * * all data values are interpolated at `fraction` between `other` values at index0 and index1.
     */
    pushInterpolatedDataFrom(other: PolyfaceVisitor, index0: number, fraction: number, index1: number): void;
    /** transfer data from a specified index of the other visitor as new data in this visitor. */
    pushDataFrom(other: PolyfaceVisitor, index: number): void;
    /** Return the number of facets this visitor is able to visit */
    getVisitableFacetCount(): number;
    /** Create a visitor for a subset of the facets visitable by the instance. */
    createSubsetVisitor(facetIndices: number[], numWrap?: number): ExportGraphicsMeshSubsetVisitor;
}
/**
 * An `ExportGraphicsMeshSubsetVisitor` is an `ExportGraphicsMeshVisitor` which only visits a subset of the facets.
 * * The subset is defined by an array of facet indices provided when this visitor is created.
 * * Input indices (e.g., for `moveToReadIndex`) are understood to be indices into the subset array.
 * @public
 */
export declare class ExportGraphicsMeshSubsetVisitor extends ExportGraphicsMeshVisitor {
    private _facetIndices;
    private _currentSubsetIndex;
    private _nextSubsetIndex;
    private constructor();
    private isValidSubsetIndex;
    /**
     * Create a visitor for iterating a subset of the facets of `polyface`.
     * @param polyface reference to the client polyface, supplying facets
     * @param facetIndices array of indices of facets in the client polyface to visit. This array is cloned.
     * @param numWrap number of vertices replicated in the visitor arrays to facilitate simpler caller code. Default is zero.
     */
    static createSubsetVisitor(polyface: ExportGraphicsMesh, facetIndices: number[], numWrap?: number): ExportGraphicsMeshSubsetVisitor;
    /**
     * Advance the iterator to a particular facet in the subset of client polyface facets.
     * @param subsetIndex index into the subset array, not to be confused with the client facet index.
     * @return whether the iterator was successfully moved.
     */
    moveToReadIndex(subsetIndex: number): boolean;
    /**
     * Advance the iterator to the next facet in the subset of client polyface facets.
     * @return whether the iterator was successfully moved.
     */
    moveToNextFacet(): boolean;
    /** Restart the visitor at the first facet. */
    reset(): void;
    /**
     * Return the client polyface facet index (aka "readIndex") for the given subset index.
     * @param subsetIndex index into the subset array. Default is the subset index of the currently visited facet.
     * @return valid client polyface facet index, or `undefined` if invalid subset index.
     */
    parentFacetIndex(subsetIndex?: number): number | undefined;
    /** Return the number of facets this visitor is able to visit. */
    getVisitableFacetCount(): number;
}
//# sourceMappingURL=ExportGraphics.d.ts.map