@mlightcad/mtext-renderer 0.10.0 → 0.10.2

package/lib/font/meshFont.d.ts

@@ -0,0 +1,138 @@
+import { FontData as ThreeFontData } from 'three/examples/jsm/loaders/FontLoader.js';
+import { BaseFont } from './baseFont';
+import { FontData } from './font';
+import { MeshTextShape } from './meshTextShape';
+import { ThreeFont } from './threeFont';
+export interface GlyphCommand {
+    type: string;
+    x?: number;
+    y?: number;
+    x1?: number;
+    y1?: number;
+    x2?: number;
+    y2?: number;
+}
+interface MeshGlyph {
+    ha: number;
+    x_min: number;
+    x_max: number;
+    o?: string | undefined;
+}
+/**
+ * Represents the data structure for mesh-based fonts.
+ * Extends the base ThreeFontData interface with additional properties specific to mesh fonts.
+ */
+export interface MeshFontData extends ThreeFontData {
+    /** A map of glyphs keyed by character */
+    glyphs: Record<string, MeshGlyph>;
+    /** The full font family name */
+    familyName: string;
+    /** The font ascender */
+    ascender: number;
+    /** The font descender */
+    descender: number;
+    /** Underline position in font units */
+    underlinePosition: number;
+    /** Underline thickness in font units */
+    underlineThickness: number;
+    /** Font bounding box */
+    boundingBox: {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+    /** Font resolution (usually unitsPerEm) */
+    resolution: number;
+    /** Scale factor used to adjust the size of characters when rendering */
+    scaleFactor: number;
+    /** Original font information table */
+    original_font_information: Record<string, string>;
+}
+/**
+ * Represents a mesh-based font (e.g., TTF, OTF, WOFF).
+ * This class extends BaseFont to provide specific functionality for mesh fonts,
+ * including character shape generation, scale factor management, and
+ * **lazy glyph loading** to reduce memory consumption.
+ */
+export declare class MeshFont extends BaseFont {
+    /** Scale factor used to adjust the size of characters */
+    protected scaleFactor?: number;
+    /** Three.js font instance used for rendering */
+    readonly font: ThreeFont;
+    /** The type of font (always 'mesh' for this class) */
+    readonly type = "mesh";
+    /** The parsed font data */
+    readonly data: MeshFontData;
+    /** Internal opentype.js font instance used for on-demand glyph parsing */
+    private readonly opentypeFont;
+    /** Glyph cache to limit memory usage */
+    private readonly glyphCache;
+    /**
+     * Creates a new instance of MeshFont.
+     * @param fontData - Either a MeshFontData object containing font information or an ArrayBuffer containing raw font data
+     */
+    constructor(fontData: FontData);
+    /**
+     * Parses a mesh font from raw binary data.
+     * This function converts raw font data (e.g., TTF, OTF, WOFF) into a MeshFontData object
+     * that can be used by the MeshFont class.
+     *
+     * @param data - The raw font data as an ArrayBuffer
+     * @returns An object containing the opentype font and parsed metadata
+     */
+    private parseMeshFont;
+    /**
+     * Return true if this font contains glyph of the specified character. Otherwise, return false.
+     * @param char - The character to check
+     * @returns True if this font contains glyph of the specified character. Otherwise, return false.
+     */
+    hasChar(char: string): boolean;
+    /**
+     * Return true if this font contains glyph of the specified character code. Otherwise, return false.
+     * @param code - The character code to check
+     * @returns True if this font contains glyph of the specified character code. Otherwise, return false.
+     */
+    hasCode(code: number): boolean;
+    /**
+     * Loads glyph data lazily when requested.
+     * Parsed glyphs are cached in an LRU cache to limit memory usage.
+     * @param char - The character whose glyph should be loaded
+     */
+    private _loadGlyphIfNeeded;
+    /**
+     * Generates shapes for a text string
+     * @param text - The text to generate shapes for
+     * @param size - The size of the text
+     * @returns Array of shapes representing the text
+     */
+    generateShapes(text: string, size: number): import('three').Shape[];
+    /**
+     * Gets the shape data for a specific character at a given size.
+     * @param char - The character to get the shape for
+     * @param size - The desired size of the character
+     * @returns The shape data for the character, or undefined if not found
+     */
+    getCharShape(char: string, size: number): MeshTextShape | undefined;
+    /**
+     * Gets the shape data for a specific character unicode at a given size.
+     * @param code - The character unicode to get the shape for
+     * @param size - The desired size of the character
+     * @returns The shape data for the character unicode, or undefined if not found
+     */
+    getCodeShape(code: number, size: number): MeshTextShape | undefined;
+    /**
+     * Gets the scale factor for this font.
+     * This is used to adjust the size of characters when rendering.
+     * @returns The scale factor as a number
+     */
+    getScaleFactor(): number;
+    /**
+     * Gets the shape to display when a character is not found in the font.
+     * Uses "?" as a replacement character.
+     * @param size - The desired size of the not found shape
+     * @returns The shape data for the not found indicator
+     */
+    getNotFoundTextShape(size: number): MeshTextShape;
+}
+export {};

package/lib/font/meshFontParser.d.ts

@@ -0,0 +1,10 @@
+import { MeshFontData } from './meshFont';
+/**
+ * Parses a mesh font from raw binary data.
+ * This function converts raw font data (e.g., TTF, OTF, WOFF) into a MeshFontData object
+ * that can be used by the MeshFont class.
+ *
+ * @param data - The raw font data as an ArrayBuffer
+ * @returns A MeshFontData object containing the parsed font information
+ */
+export declare function parseMeshFont(data: ArrayBuffer): MeshFontData;

package/lib/font/meshTextShape.d.ts

@@ -0,0 +1,33 @@
+import { BaseTextShape } from './baseTextShape';
+import { MeshFont } from './meshFont';
+import * as THREE from 'three';
+/**
+ * Represents a text shape for mesh-based fonts (e.g., TTF, OTF, WOFF).
+ * This class extends BaseTextShape to provide specific functionality for mesh fonts,
+ * including 3D geometry generation and character width calculation.
+ */
+export declare class MeshTextShape extends BaseTextShape {
+    /**
+     * Flag to indicate whether the character is found in the font.
+     * Used to track if the character exists in the font's glyph set.
+     */
+    isFound: boolean;
+    private readonly char;
+    private readonly font;
+    private readonly fontSize;
+    constructor(char: string, fontSize: number, font: MeshFont);
+    /**
+     * Converts the text shape to a THREE.js geometry.
+     * This is used for 3D rendering of the text.
+     * @returns A THREE.js BufferGeometry representing the text shape
+     */
+    toGeometry(): THREE.BufferGeometry;
+    /**
+     * Calculates the width of a character in the font.
+     * @param char - The character to calculate width for
+     * @param fontSize - The size of the font in pixels
+     * @param font - The mesh font to use
+     * @returns The width of the character in pixels
+     */
+    private getCharWidth;
+}

package/lib/font/normalComputationToggle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Utility class for temporarily disabling `BufferGeometry.computeVertexNormals`.
+ *
+ * By default, Three.js computes vertex normals for many geometries,
+ * which can be unnecessary (e.g., when using `MeshBasicMaterial` that does not require lighting).
+ * This class lets you temporarily replace `computeVertexNormals` with a no-op
+ * to save CPU time during geometry creation.
+ *
+ * Example:
+ * ```ts
+ * import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry.js";
+ * import { NormalComputationToggle } from "./NormalComputationToggle";
+ *
+ * // Create geometry without computing normals
+ * const textGeom = NormalComputationToggle.runWithoutNormals(() =>
+ *   new TextGeometry("Fast!", { font, size: 1, height: 0.2 })
+ * );
+ * ```
+ */
+export declare class NormalComputationToggle {
+    /**
+     * Stores the original `computeVertexNormals` method from BufferGeometry.
+     */
+    private static originalComputeVertexNormals;
+    /**
+     * Dummy replacement for `computeVertexNormals` that does nothing.
+     */
+    private static dummyComputeVertexNormals;
+    /**
+     * Disable vertex normal computation globally.
+     *
+     * After calling this, all calls to `computeVertexNormals`
+     * will do nothing until {@link restore} is called.
+     */
+    static disable(): void;
+    /**
+     * Restore the original `computeVertexNormals` implementation.
+     */
+    static restore(): void;
+    /**
+     * Execute a function with normal computation disabled,
+     * then automatically restore afterwards.
+     *
+     * This is the safest way to create geometries without normals.
+     *
+     * Example:
+     * ```ts
+     * const geom = NormalComputationToggle.runWithoutNormals(() =>
+     *   new TextGeometry("World", { font, size: 1, height: 0.2 })
+     * );
+     * ```
+     *
+     * @param fn - A callback that creates the geometry.
+     * @returns The result of the callback, e.g., a geometry.
+     */
+    static runWithoutNormals<T>(fn: () => T): T;
+}

package/lib/font/shxFont.d.ts

@@ -0,0 +1,62 @@
+import { ShxFontData } from '@mlightcad/shx-parser';
+import { BaseFont } from './baseFont';
+import { FontData } from './font';
+import { ShxTextShape } from './shxTextShape';
+/**
+ * ShxFont is a class that extends BaseFont and represents a SHX font.
+ * It provides methods to generate shapes for text and retrieve character shapes.
+ */
+export declare class ShxFont extends BaseFont {
+    /** Internal shx font instance */
+    private readonly font;
+    readonly type = "shx";
+    readonly data: ShxFontData;
+    constructor(fontData: FontData);
+    /**
+     * Return true if this font contains glyph of the specified character. Otherwise, return false.
+     * @param char - The character to check
+     * @returns True if this font contains glyph of the specified character. Otherwise, return false.
+     */
+    hasChar(char: string): boolean;
+    /**
+     * Return true if this font contains glyph of the specified character code. Otherwise, return false.
+     * @param code - The character code to check
+     * @returns True if this font contains glyph of the specified character code. Otherwise, return false.
+     */
+    hasCode(code: number): boolean;
+    generateShapes(text: string, size: number): ShxTextShape[];
+    /**
+     * SHX font always has fixed scale factor 1.
+     * @returns Always return value 1
+     */
+    getScaleFactor(): number;
+    /**
+     * Gets the shape data for a specific character at a given size.
+     * If the font type is BIGFONT, please use getCodeShape to get the shape data
+     * because the character code for BIGFONT isn't unicode.
+     * @param char - The character to get the shape for
+     * @param size - The desired size of the character
+     * @returns The shape data for the character, or undefined if not found
+     */
+    getCharShape(char: string, size: number): ShxTextShape | undefined;
+    /**
+     * Gets the shape data for a specific character code at a given size.
+     * The passed code must the code stored in font instead of unicode.
+     * - Unicode shx font uses unicode as character code.
+     * - Bigfont uses a custom encoding for double-byte characters.
+     * @param code - The character code to get the shape for
+     * @param size - The desired size of the character
+     * @returns The shape data for the character code, or undefined if not found
+     */
+    getCodeShape(code: number, size: number): ShxTextShape | undefined;
+    /**
+     * For an unsupported char, use "？" as a replacement.
+     */
+    getNotFoundTextShape(size: number): ShxTextShape | undefined;
+    /**
+     * Gets encoded code of the specified character according to font character encoding
+     * @param char - The character to get its code
+     * @returns Returns encoded code of the specified character
+     */
+    private getCode;
+}

package/lib/font/shxTextShape.d.ts

@@ -0,0 +1,29 @@
+import { Point, ShxShape } from '@mlightcad/shx-parser';
+import { BaseTextShape } from './baseTextShape';
+import { ShxFont } from './shxFont';
+import * as THREE from 'three';
+/**
+ * Represents a text shape for SHX fonts.
+ * This class extends BaseTextShape to provide specific functionality for SHX fonts,
+ * including shape data management and dimension calculations.
+ */
+export declare class ShxTextShape extends BaseTextShape {
+    /** The shape data for this character */
+    private readonly code;
+    private readonly shape;
+    private readonly font;
+    private readonly fontSize;
+    /**
+     * Creates a new instance of ShxTextShape
+     * @param code - The character code this shape represents
+     * @param shape - The shape data for this character
+     */
+    constructor(code: number, fontSize: number, shape: ShxShape, font: ShxFont);
+    protected calcWidth(): number;
+    offset(offset: Point): ShxTextShape;
+    /**
+     * Converts the text shape to a THREE.js geometry
+     * @returns A THREE.js BufferGeometry representing the text shape
+     */
+    toGeometry(): THREE.BufferGeometry<THREE.NormalBufferAttributes>;
+}

package/lib/font/threeFont.d.ts

@@ -0,0 +1,50 @@
+import { Shape } from 'three';
+import { Font } from 'three/examples/jsm/loaders/FontLoader.js';
+type Direction = 'ltr' | 'rtl' | 'tb';
+/**
+ * Extended Font that fixes inner holes for problematic fonts like SimSun.
+ * Certain characters have incorrect inner contours (holes), e.g., 面, 限, 用, 色, 8.
+ */
+export declare class ThreeFont extends Font {
+    /**
+     * Generates geometry shapes from the given text and size.
+     *
+     * Algorithm overview:
+     * 1. Split the input text into individual characters.
+     * 2. For each character:
+     *    a. Retrieve the glyph data from the font.
+     *    b. Convert the glyph outline commands into a ShapePath.
+     *       - 'm' → moveTo
+     *       - 'l' → lineTo
+     *       - 'q' → quadraticCurveTo
+     *       - 'b' → cubic bezierCurveTo
+     *    c. Apply scaling to match the requested font size.
+     *    d. Apply offsets for proper placement (supports multiple lines and directions).
+     * 3. Handle text direction:
+     *    - 'ltr': left-to-right
+     *    - 'rtl': right-to-left (characters reversed)
+     *    - 'tb': top-to-bottom (vertical layout)
+     * 4. Collect all ShapePaths for the text.
+     * 5. Convert each ShapePath into one or more Shape objects:
+     *    a. Sample points along each subPath to approximate geometry.
+     *    b. Determine which subPaths are outer contours and which are holes:
+     *       - For each subPath, check if it is fully contained inside another polygon.
+     *       - Assign the smallest containing polygon as its parent.
+     *    c. Compute the relative depth of each subPath to handle nested holes.
+     *    d. Reverse curves if necessary to maintain correct clockwise/counterclockwise winding:
+     *       - Outer contours: CCW
+     *       - Holes: CW
+     *    e. Build Shape objects with holes properly assigned.
+     * 6. Return the final array of Shape objects ready for geometry creation.
+     *
+     * This algorithm ensures that complex characters with multiple independent contours
+     * (including intersecting subpaths or holes) are rendered correctly.
+     *
+     * @param text - input string to convert to shapes
+     * @param size - font size in units (default 100)
+     * @param direction - text direction ('ltr', 'rtl', 'tb')
+     * @returns array of Shape objects with proper holes and contours
+     */
+    generateShapes(text: string, size?: number, direction?: Direction): Shape[];
+}
+export {};

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { getColorByIndex } from './common';
+export * from './common/eventManager';
+export * from './font';
+export * from './renderer';
+export * from './worker';

package/lib/renderer/charBoxUtils.d.ts

@@ -0,0 +1,4 @@
+import { CharBox, CharBoxType } from './types';
+import * as THREE from 'three';
+export declare function normalizeBox(box?: THREE.Box3): THREE.Box3 | undefined;
+export declare function buildCharBoxesFromObject(objectCharBoxes: CharBox[], matrixWorld: THREE.Matrix4, charBoxType?: CharBoxType): CharBox[];

package/lib/renderer/defaultStyleManager.d.ts

@@ -0,0 +1,18 @@
+import { StyleManager } from './styleManager';
+import { StyleTraits } from './types';
+import * as THREE from 'three';
+/**
+ * Class to manage basic text style
+ */
+export declare class DefaultStyleManager implements StyleManager {
+    private lineBasicMaterials;
+    private meshBasicMaterials;
+    unsupportedTextStyles: Record<string, number>;
+    getMeshBasicMaterial(traits: StyleTraits): THREE.Material;
+    getLineBasicMaterial(traits: StyleTraits): THREE.Material;
+    /**
+     * Builds a stable material key from traits.
+     * Key differs for shader vs basic, ByLayer vs ByEntity.
+     */
+    protected buildKey(traits: StyleTraits): string;
+}

package/lib/renderer/index.d.ts

@@ -0,0 +1,3 @@
+export * from './mtext';
+export * from './styleManager';
+export * from './types';

package/lib/renderer/mtext.d.ts

@@ -0,0 +1,134 @@
+import { FontManager } from '../font';
+import { StyleManager } from './styleManager';
+import { ColorSettings, MTextData, MTextLayout, TextStyle } from './types';
+import * as THREE from 'three';
+/**
+ * Represents an AutoCAD MText object in Three.js.
+ * This class extends THREE.Object3D to provide MText rendering capabilities,
+ * including text layout, alignment, and transformation.
+ */
+export declare class MText extends THREE.Object3D {
+    /** The text style configuration for this MText object */
+    private _style;
+    /** The flag to indicate whether fonts specified in style are loaded */
+    private _fontsInStyleLoaded;
+    /** The style manager instance for handling text styles */
+    private _styleManager;
+    /** The font manager instance for handling font operations */
+    private _fontManager;
+    /** Color settings used to decided font color */
+    private _colorSettings;
+    /** The bounding box of the entire MText object */
+    private _box;
+    /** Lazily built layout data (line geometry + char boxes). */
+    private _layoutData;
+    /** Raw mtext data to draw on demand */
+    private _mtextData;
+    /**
+     * Extracts all unique font names used in an MText string.
+     * This function searches for font commands in the format \f{fontname}| or \f{fontname}; and returns a set of unique font names.
+     * Font names are converted to lowercase to ensure case-insensitive uniqueness.
+     *
+     * @param mtext - The MText string to analyze for font names
+     * @param removeExtension - Whether to remove font file extensions (e.g., .ttf, .shx) from font names. Defaults to false.
+     * @returns A Set containing all unique font names found in the MText string, converted to lowercase
+     * @example
+     * ```ts
+     * const mtext = "\\fArial.ttf|Hello\\fTimes New Roman.otf|World";
+     * const fonts = getFonts(mtext, true);
+     * // Returns: Set(2) { "arial", "times new roman" }
+     * ```
+     */
+    static getFonts(mtext: string, removeExtension?: boolean): Set<string>;
+    /**
+     * Creates a new instance of MText.
+     * @param text - The MText data containing text content and properties
+     * @param style - The text style configuration
+     * @param styleManager - The style manager instance
+     * @param fontManager - The font manager instance
+     * @param colorSettings - Color settings used to decided font color
+     */
+    constructor(text: MTextData, style: TextStyle, styleManager: StyleManager, fontManager: FontManager, colorSettings?: ColorSettings);
+    /**
+     * Gets the font manager instance associated with this MText object.
+     * @returns The FontManager instance
+     */
+    get fontManager(): FontManager;
+    /**
+     * Remove the current object from its parent and release geometry and material resource used
+     * by the current object.
+     */
+    dispose(): void;
+    /**
+     * Draw the MText object. This method loads required fonts on demand and builds the object graph.
+     */
+    asyncDraw(): Promise<void>;
+    /**
+     * Draw the MText object. This method assumes that fonts needed are loaded. If font needed
+     * not found, the default font will be used.
+     */
+    syncDraw(): void;
+    /**
+     * Gets the style manager instance associated with this MText object.
+     * @returns The StyleManager instance
+     */
+    get styleManager(): StyleManager;
+    /**
+     * Gets the text style configuration for this MText object.
+     * @returns The TextStyle configuration
+     */
+    get textStyle(): TextStyle;
+    /**
+     * Gets or sets the bounding box of this MText object.
+     * The bounding box is calculated without considering the transformation matrix.
+     * To get the bounding box with transformation, call `applyMatrix4` on this box.
+     */
+    get box(): THREE.Box3;
+    set box(box: THREE.Box3);
+    /** Creates text layout data for cursor/picking/debug usage on demand. */
+    createLayoutData(): MTextLayout;
+    /**
+     * Calculates intersections between a ray and this MText object.
+     * Overrides the base THREE.Object3D raycast method to use the text's bounding boxes.
+     * @param raycaster - The raycaster to use for intersection testing
+     * @param intersects - Array to store intersection results
+     */
+    raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void;
+    /**
+     * Loads and processes MText data to create a Three.js object.
+     * @param mtextData - The MText data to process
+     * @param style - The text style configuration
+     * @returns The created Three.js object, or undefined if creation fails
+     */
+    private loadMText;
+    /**
+     * Creates a group of text elements from MText data.
+     * @param mtextData - The MText data to process
+     * @param style - The text style configuration
+     * @returns An object containing the created Three.js object and its height
+     */
+    private createMTextGroup;
+    /**
+     * Calculates the anchor point for text positioning based on alignment and flow direction.
+     * @param width - The width of the text
+     * @param height - The height of the text
+     * @param attachmentPoint - The attachment point for text alignment
+     * @param flowDirection - The text flow direction
+     * @returns The calculated anchor point coordinates
+     */
+    private calculateAnchorPoint;
+    /**
+     * Recursively calculates bounding boxes for an object and its children.
+     * @param object - The Three.js object to process
+     * @param boxes - Array to store the calculated bounding boxes
+     */
+    private getLayout;
+    private updateBoxFromObject;
+    /**
+     * Remove the specified object from its parent and release geometry and material resource used
+     * by the object.
+     * @param obj - Input object to dispose
+     */
+    private disposeThreeObject;
+    private getFontName;
+}