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

iTwin.js backend components

/** @packageDocumentation
 * @module ElementGeometry
 */
import { Id64String } from "@itwin/core-bentley";
import { LinePixels } from "@itwin/core-common";
import { IModelDb } from "./IModelDb";
/** A line style definition is a uniquely named pattern that repeats as it is displayed along a curve path. In the absence of a line style, curve display is limited to solid lines with a width in pixels.
 * There are three varieties of line styles:
 * - A style described by a stroke pattern (series of dashes and gaps) that may also include symbol graphics.
 * - A style using pre-defined pixel bit patterns [[LinePixels]] for dashed display (Code1-Code7).
 * - A style that uses a texture.
 *
 * A definition is defined by one or more components. A component is saved as a "file property" and can be referenced by other components. The line style definition references a component
 * by file property id and type and is saved as a dictionary element.
 * @public
 */
export declare namespace LineStyleDefinition {
    /** Line style component type identifiers */
    enum ComponentType {
        /** Component type for [[LineStyleDefinition.PointSymbolProps]] */
        PointSymbol = 1,
        /** Component type for [[LineStyleDefinition.CompoundProps]] */
        Compound = 2,
        /** Component type for [[LineStyleDefinition.StrokePatternProps]] */
        StrokePattern = 3,
        /** Component type for [[LineStyleDefinition.StrokePointProps]] */
        StrokePoint = 4,
        /** Component type for [[LinePixels]], never saved as a file property */
        Internal = 6,
        /** Component type for [[LineStyleDefinition.RasterImageProps]] */
        RasterImage = 7
    }
    /** Mask of values for StrokeMode */
    enum StrokeMode {
        /** Stroke represents a blank space */
        Gap = 0,
        /** Stroke represents a solid dash */
        Dash = 1,
        /** Treat stroke as rigid and continue past a corner to complete the stroke as opposed to breaking at the corner */
        Ray = 2,
        /** Stroke length can be stretched when [[LineStyleDefinition.StrokePatternOptions.Iteration]] and [[LineStyleDefinition.StrokePatternOptions.AutoPhase]] options are set, applicable to both Gap and Dash strokes */
        Scale = 4,
        /** Invert stroke in first stroke pattern */
        FirstInvert = 8,
        /** Invert stroke in last stroke pattern */
        LastInvert = 16
    }
    /** Define constant width or tapered strokes with distance specified in meters */
    enum StrokeWidth {
        /** Stroke draws as one pixel wide line */
        None = 0,
        /** Half [[LineStyleDefinition.StrokeProps.orgWidth]] and [[LineStyleDefinition.StrokeProps.endWidth]] applied to left side of stroke */
        Left = 1,
        /** Half [[LineStyleDefinition.StrokeProps.orgWidth]] and [[LineStyleDefinition.StrokeProps.endWidth]] applied to right side of stroke */
        Right = 2,
        /** Half [[LineStyleDefinition.StrokeProps.orgWidth]] and [[LineStyleDefinition.StrokeProps.endWidth]] applied to both sides of stroke */
        Full = 3
    }
    /** Controls appearance of stroke end caps. If StrokeCap is >= Hexagon, the end cap is stroked as an arc and the value of
     * StrokeCap indicates the number of vectors in the arc.
     */
    enum StrokeCap {
        /** Stroke displays as a closed polygon */
        Closed = 0,
        /** Stroke displays lines at specified width instead of a polygon */
        Open = 1,
        /** Stroke length extended by half the stroke width */
        Extended = 2,
        /** Stroke end cap is a hexagon */
        Hexagon = 3,
        /** Stroke end cap is an octagon */
        Octagon = 4,
        /** Stroke end cap is a decagon */
        Decagon = 5,
        /** Stroke end cap is an arc */
        Arc = 30
    }
    /** A stroke representing either a dash or gap in a stroke pattern */
    interface StrokeProps {
        /** Length of stroke in meters */
        length: number;
        /** Width at start of stroke. Behavior controlled by [[LineStyleDefinition.StrokeWidth]], choose value other than [[LineStyleDefinition.StrokeWidth.None]] */
        orgWidth?: number;
        /** Width at end of stroke, same as start width if not present. Behavior controlled by [[LineStyleDefinition.StrokeWidth]], choose value other than [[LineStyleDefinition.StrokeWidth.None]] */
        endWidth?: number;
        /** Type and behavior of stroke */
        strokeMode?: StrokeMode;
        /** How to apply orgWidth and endWidth to stroke */
        widthMode?: StrokeWidth;
        /** Appearance of stroke end cap */
        capMode?: StrokeCap;
    }
    type Strokes = StrokeProps[];
    /** Options to control how stroke pattern is applied to underlying curve */
    enum StrokePatternOptions {
        /** Use default stroke behavior */
        None = 0,
        /** [[LineStyleDefinition.StrokePatternProps.phase]] represents fractional distance into first stroke of pattern */
        AutoPhase = 1,
        /** Use [[LineStyleDefinition.StrokePatternProps.maxIter]] to limit the number of iterations of the stroke pattern */
        Iteration = 8,
        /** Single segment mode restarts the stroke pattern at corners instead of continuing around corners */
        Segment = 16,
        /** Center the line style and stretch the ends */
        CenterStretch = 32
    }
    /** Stroke pattern component definition [[LineStyleDefinition.ComponentType.StrokePattern]].
     * A stroke pattern component consists of a series of dashes and gaps having specified lengths and widths in meters. Simple dash-dot type line styles that do not
     * include point symbols can be created by referencing a stroke pattern component by its file property id.
     */
    interface StrokePatternProps {
        /** Name for this stroke pattern */
        descr: string;
        /** Skip into the pattern before starting to draw. Value treated as fraction of the first stroke when [[LineStyleDefinition.StrokePatternOptions.AutoPhase]] set. Value used as distance when [[LineStyleDefinition.StrokePatternOptions.CenterStretch]] is not set. */
        phase?: number;
        /** Options mask for this stroke pattern */
        options?: StrokePatternOptions;
        /** The entire stroke pattern will be repeated no more than maxIter on curve or segment when [[LineStyleDefinition.StrokePatternOptions.Iteration]] is set and stroke pattern includes stretchable strokes. */
        maxIter?: number;
        /** Array of strokes, maximum number that will be used is 32 */
        strokes: Strokes;
    }
    /** Flags to identify point symbol behavior */
    enum PointSymbolFlags {
        /** Default symbol behavior */
        None = 0,
        /** Symbol includes 3d geometry */
        Is3d = 1,
        /** Symbol does not allow scaling */
        NoScale = 2
    }
    /** Point symbol component definition [[LineStyleDefinition.ComponentType.PointSymbol]].
     * A point symbol component identifies a GeometryPart for reference by a [[LineStyleDefinition.SymbolProps]].
     */
    interface PointSymbolProps {
        /** GeometryPart Id to use as a pattern symbol */
        geomPartId: Id64String;
        /** GeometryPart.bbox.low.x */
        baseX?: number;
        /** GeometryPart.bbox.low.y */
        baseY?: number;
        /** GeometryPart.bbox.low.z */
        baseZ?: number;
        /** GeometryPart.bbox.high.x */
        sizeX?: number;
        /** GeometryPart.bbox.high.y */
        sizeY?: number;
        /** GeometryPart.bbox.high.z */
        sizeZ?: number;
        /** Symbol behavior flags */
        symFlags?: PointSymbolFlags;
        /** Symbol scale, defaults to 1 */
        scale?: number;
    }
    /** Symbol options for location, orientation, and behavior */
    enum SymbolOptions {
        /** No point symbol */
        None = 0,
        /** Symbol at origin of stroke */
        Origin = 1,
        /** Symbol at end of stroke */
        End = 2,
        /** symbol at center of stroke */
        Center = 3,
        /** Symbol at curve start point */
        CurveOrigin = 4,
        /** Symbol at curve end point */
        CurveEnd = 8,
        /** Symbol at each vertex */
        CurveVertex = 16,
        /** Adjust symbol rotation left->right */
        AdjustRotation = 32,
        /** Angle of symbol not relative to stroke direction */
        AbsoluteRotation = 64,
        /** No scale on variable strokes */
        NoScale = 256,
        /** No clip on partial strokes */
        NoClip = 512,
        /** No partial strokes */
        NoPartial = 1024,
        /** Project partial origin */
        ProjectOrigin = 2048,
        /** Use color from symbol instead of inheriting curve color */
        UseColor = 16384,
        /** Use weight from symbol instead of inheriting curve weight */
        UseWeight = 32768
    }
    /** Identifies a symbol and its location and orientation relative to a stroke pattern */
    interface SymbolProps {
        /** The file property id of the symbol component, assumed to be [[LineStyleDefinition.ComponentType.PointSymbol]] if symType is undefined. */
        symId: number;
        /** The component type, leave undefined if symId is a [[LineStyleDefinition.ComponentType.PointSymbol]] */
        symType?: ComponentType;
        /** The 0 based stroke index for base stroke pattern [[LineStyleDefinition.ComponentType.StrokePattern]] component */
        strokeNum?: number;
        /** Symbol x offset distance in meters */
        xOffset?: number;
        /** Symbol y offset distance in meters */
        yOffset?: number;
        /** Symbol rotation in radians */
        angle?: number;
        /** Must set location for symbol as default value is [[LineStyleDefinition.SymbolOptions.None]] */
        mod1?: SymbolOptions;
    }
    type Symbols = SymbolProps[];
    /** Stroke point component definition [[LineStyleDefinition.ComponentType.StrokePoint]].
     * A stroke point component identifies the locations of point symbol components relative to a base stroke pattern component.
     */
    interface StrokePointProps {
        /** Name for this stroke point component */
        descr: string;
        /** The file property id of the stroke component, assumed to be [[LineStyleDefinition.ComponentType.StrokePattern]] if lcType is undefined */
        lcId: number;
        /** The component type, leave undefined if lcId is a [[LineStyleDefinition.ComponentType.StrokePattern]] */
        lcType?: ComponentType;
        /** Array of symbols */
        symbols: Symbols;
    }
    /** Raster component definition [[LineStyleDefinition.ComponentType.RasterImage]].
     * A raster component identifies a texture for a line style.
     */
    interface RasterImageProps {
        /** Name for this raster image component */
        descr: string;
        /** Raster width */
        x: number;
        /** Raster height */
        y: number;
        /** True width flag */
        trueWidth?: number;
        /** Raster flags */
        flags?: number;
        /** The file property id of raster image */
        imageId?: number;
    }
    /** Identifies a component by file property id and type */
    interface ComponentProps {
        /** The file property id of [[LineStyleDefinition.ComponentType.StrokePattern]] or [[LineStyleDefinition.ComponentType.StrokePoint]] component */
        id: number;
        /** The type of component for specified file property id */
        type: ComponentType;
        /** Offset distance for this component, default is 0 */
        offset?: number;
    }
    type Components = ComponentProps[];
    /** Compound component definition [[LineStyleDefinition.ComponentType.Compound]].
     * A compound component is used to link stroke pattern and stroke point components to create a style that displays dashes, gaps, and symbols.
     */
    interface CompoundProps {
        comps: Components;
    }
    /** Flags to describe a style or control style behavior */
    enum StyleFlags {
        /** Use defaults */
        None = 0,
        /** Only snap to center line and not individual strokes and symbols of line style */
        NoSnap = 4,
        /** Style represents a continuous line with width (determined by looking at components if not set) */
        Continuous = 8,
        /** Style represents physical geometry and should be scaled as such */
        Physical = 128
    }
    /** The line style definition element data */
    interface StyleProps {
        /** The file property id for either a [[LineStyleDefinition.ComponentType.StrokePattern]] or [[LineStyleDefinition.ComponentType.Compound]] component */
        compId: number;
        /** The type of component for specified file property id */
        compType: ComponentType;
        /** Style behavior flags. Defaults to [[LineStyleDefinition.StyleFlags.NoSnap]] if left undefined */
        flags?: StyleFlags;
        /** Style scale, defaults to 1 */
        unitDef?: number;
    }
    /** Helper methods for creating and querying line styles */
    class Utils {
        /** Create a file property for a new stroke pattern component. */
        static createStrokePatternComponent(iModel: IModelDb, props: StrokePatternProps): StyleProps;
        /** Create a file property for a new point symbol component.
         * If base and size parameters are not supplied, queries GeometryPart by id to set them.
         */
        static createPointSymbolComponent(iModel: IModelDb, props: PointSymbolProps): StyleProps | undefined;
        /** Create a file property for a new stroke point component. */
        static createStrokePointComponent(iModel: IModelDb, props: StrokePointProps): StyleProps;
        /** Create a file property for a new compound component. */
        static createCompoundComponent(iModel: IModelDb, props: CompoundProps): StyleProps;
        /** Create a file property for a new raster image component. */
        static createRasterComponent(iModel: IModelDb, props: RasterImageProps, image: Uint8Array): StyleProps | undefined;
        /** Query for an existing line style with the supplied name. */
        static queryStyle(imodel: IModelDb, scopeModelId: Id64String, name: string): Id64String | undefined;
        /** Insert a new line style with the supplied name.
         * @throws [[IModelError]] if unable to insert the line style definition element.
         */
        static createStyle(imodel: IModelDb, scopeModelId: Id64String, name: string, props: StyleProps): Id64String;
        /** Query for a continuous line style that can be used to create curves with physical width instead of weight in pixels and create one if it does not already exist.
         * There are 2 ways to define a continuous line style:
         * - Width is not specified in the style itself and instead will be supplied as an override for each curve that is drawn.
         *  - Defined using [[LineStyleDefinition.ComponentType.Internal]] with component id 0 [[LinePixels.Solid]] which has special behavior of being affected by width overrides.
         * - Width is specified in the style.
         *  - Defined using a single stroke component that is a long dash.
         *
         * @throws [[IModelError]] if unable to insert the line style definition element.
         */
        static getOrCreateContinuousStyle(imodel: IModelDb, scopeModelId: Id64String, width?: number): Id64String;
        /** Query for a line style using the supplied [[LinePixels]] value (Code1-Code7) and create one if it does not already exist.
         * Most applications should instead use [[createStrokePatternComponent]] to define a style with physical dash and gap lengths.
         * Unlike other components, [[LineStyleDefinition.ComponentType.Internal]] uses the line code as the compId instead of a file property id.
         * @throws [[IModelError]] if supplied an invalid [[LinePixels]] value or if unable to insert the line style definition element.
         */
        static getOrCreateLinePixelsStyle(imodel: IModelDb, scopeModelId: Id64String, linePixels: LinePixels): Id64String;
    }
}
//# sourceMappingURL=LineStyle.d.ts.map