@bitbybit-dev/core/lib/api/draw-helper-core.d.ts

Bit By Bit Developers Core CAD API to Program Geometry

import { Base } from "./inputs/base-inputs";
import { Vector } from "@bitbybit-dev/base";
/**
 * Mesh data structure for geometry processing
 */
export interface MeshData {
    positions: number[];
    indices: number[];
    normals: number[];
    uvs?: number[];
}
/**
 * Base class for DrawHelper implementations across all game engines.
 * Contains engine-agnostic utility methods that are shared between
 * PlayCanvas, ThreeJS, and BabylonJS implementations.
 */
export declare class DrawHelperCore {
    readonly vector: Vector;
    constructor(vector: Vector);
    /**
     * Compute the middle position of an edge
     * @param edge - Edge with vertex coordinates
     * @returns Middle point of the edge
     */
    computeEdgeMiddlePos(edge: {
        edgeIndex: number;
        vertexCoord: Base.Point3[];
    }): Base.Point3;
    /**
     * Compute the center position of a face
     * @param vertexCoordVec - Array of vertex coordinates
     * @returns Center point of the face
     */
    computeFaceMiddlePos(vertexCoordVec: number[][]): number[];
    /**
     * Resolve a color for a specific entity index based on the color mapping strategy
     * @param colors - Single color string or array of colors
     * @param entityIndex - Index of the entity that needs a color
     * @param totalEntities - Total number of entities being drawn
     * @param strategy - Color mapping strategy to use
     * @returns Resolved color for the entity
     */
    protected resolveColorForEntity(colors: string | string[], entityIndex: number, totalEntities: number, strategy?: Base.colorMapStrategyEnum): string;
    /**
     * Resolve all colors for a set of entities based on the color mapping strategy
     * @param colors - Single color string or array of colors
     * @param totalEntities - Total number of entities being drawn
     * @param strategy - Color mapping strategy to use
     * @returns Array of colors, one for each entity
     */
    protected resolveAllColors(colors: string | string[], totalEntities: number, strategy?: Base.colorMapStrategyEnum): string[];
    /**
     * Convert RGB values (0-255) to hex color string
     * @param r - Red component (0-255)
     * @param g - Green component (0-255)
     * @param b - Blue component (0-255)
     * @returns Hex color string (e.g., "#ff0000")
     */
    protected colorToHex(r: number, g: number, b: number): string;
    /**
     * Convert normalized RGB values (0-1) to hex color string
     * @param r - Red component (0-1)
     * @param g - Green component (0-1)
     * @param b - Blue component (0-1)
     * @returns Hex color string (e.g., "#ff0000")
     */
    protected normalizedColorToHex(r: number, g: number, b: number): string;
    /**
     * Convert hex color string to RGB object
     * @param hex - Hex color string (e.g., "#ff0000" or "ff0000")
     * @returns RGB object with values 0-1, or null if invalid
     */
    protected hexToRgb(hex: string): {
        r: number;
        g: number;
        b: number;
    } | null;
    /**
     * Normalize color input to hex string with validation
     * @param color - Color as number array [r,g,b], hex string, or undefined
     * @param fallback - Fallback color if input is invalid
     * @returns Normalized hex color string
     */
    protected normalizeColor(color: number[] | string | undefined, fallback: string): string;
    /**
     * Generate a unique key for material caching
     * Uses fixed decimal precision to handle floating-point comparison
     * @param hex - Hex color string
     * @param alpha - Alpha value (0-1)
     * @param zOffset - Z-offset value for depth bias
     * @param unlit - Whether the material is unlit (no lighting)
     * @returns Unique cache key
     */
    protected getMaterialKey(hex: string, alpha: number, zOffset: number, unlit?: boolean): string;
    /**
     * Compute a signature string representing polyline structure
     * This is used to determine if existing geometry can be updated
     * @param polylinePoints - Array of polylines
     * @returns Signature string
     */
    protected computePolylineSignature(polylinePoints: Base.Vector3[][]): string;
    /**
     * Compute arrow head lines for a polyline based on its last segment direction.
     * Creates 4 lines in 3D space forming an arrow head pointing in the direction of the polyline.
     * The arrow is constructed using two perpendicular planes through the direction vector.
     *
     * @param polylinePoints - Array of points forming the polyline [x,y,z][]
     * @param arrowSize - Length of the arrow head lines
     * @param arrowAngleDeg - Angle of the arrow head in degrees (from direction vector)
     * @returns Array of 4 line segments, each as [[startX, startY, startZ], [endX, endY, endZ]], or empty array if not enough points
     */
    protected computeArrowHeadLines(polylinePoints: Base.Point3[], arrowSize: number, arrowAngleDeg: number): Base.Point3[][];
    /**
     * Compute arrow head lines for multiple polylines
     * @param polylines - Array of polylines, each as array of points
     * @param arrowSize - Length of the arrow head lines
     * @param arrowAngleDeg - Angle of the arrow head in degrees
     * @returns Array of all arrow line segments from all polylines
     */
    protected computeArrowHeadLinesForPolylines(polylines: Base.Point3[][], arrowSize: number, arrowAngleDeg: number): Base.Point3[][];
    /**
     * Convert arrow lines to flat polyline format for rendering
     * Each arrow line is converted to a 2-point polyline (start and end)
     * @param arrowLines - Array of line segments [[start], [end]]
     * @returns Array of polylines suitable for drawing
     */
    protected arrowLinesToPolylines(arrowLines: Base.Point3[][]): Base.Point3[][];
    /**
     * Process polyline points, handling closed polylines by adding first point to end
     * @param polylines - Array of polylines
     * @returns Array of processed point arrays
     */
    protected processPolylinePoints(polylines: Base.Polyline3[]): Base.Point3[][];
    /**
     * Compute smooth vertex normals for a mesh when normals are not provided
     * Uses cross product of edge vectors and accumulates per-vertex
     * @param positions - Flat array of vertex positions [x,y,z,x,y,z,...]
     * @param indices - Triangle indices
     * @returns Flat array of normals [nx,ny,nz,nx,ny,nz,...]
     */
    protected computeNormals(positions: number[], indices: number[]): number[];
    /**
     * Expand indexed mesh to non-indexed (flat shaded) mesh with per-face normals
     * This creates unique vertices for each face, allowing flat shading
     * @param positions - Flat array of vertex positions [x,y,z,x,y,z,...]
     * @param indices - Triangle indices
     * @returns Object with expanded positions, new sequential indices, and flat normals
     */
    protected expandToFlatShaded(positions: number[], indices: number[]): {
        positions: number[];
        indices: number[];
        normals: number[];
    };
    /**
     * Prepare mesh data for back face rendering by flipping normals and reversing winding order
     * This is used to create a duplicate mesh that renders the back side with a different material
     * @param meshDataArray - Array of mesh data objects
     * @returns Combined mesh data with flipped normals and reversed indices
     */
    protected prepareBackFaceMeshData(meshDataArray: MeshData[]): MeshData;
    /**
     * Get the default back face color
     * @returns Hex color string for back face
     */
    protected getDefaultBackFaceColor(): string;
}