@mlightcad/mtext-renderer 0.10.0 → 0.10.2

package/lib/renderer/mtextProcessor.d.ts

@@ -0,0 +1,249 @@
+import { ChangedProperties, MTextParagraphAlignment, MTextToken } from '@mlightcad/mtext-parser';
+import { FontManager } from '../font';
+import { StyleManager } from './styleManager';
+import { LineLayout, MTextFlowDirection, TextStyle } from './types';
+import * as THREE from 'three';
+export interface MTextFormatOptions {
+    /**
+     * Font size.
+     */
+    fontSize: number;
+    /**
+     * Scale factor of character width.
+     */
+    widthFactor: number;
+    /**
+     * The line space factor.
+     */
+    lineSpaceFactor: number;
+    /**
+     * The horizontal alignment.
+     */
+    horizontalAlignment: MTextParagraphAlignment;
+    /**
+     * The maximum width of one line of text string.
+     */
+    maxWidth: number;
+    /**
+     * The direction that the text string follows from its start to its finish.
+     */
+    flowDirection: MTextFlowDirection;
+    /**
+     * The color of the current block which is used when the text color is by block.
+     */
+    byBlockColor: number;
+    /**
+     * The color of the current layer which is used when the text color is by layer.
+     */
+    byLayerColor: number;
+    /**
+     * Whether to remove font name extension.
+     */
+    removeFontExtension: boolean;
+    /**
+     * Whether to collect per-character bounding boxes for picking.
+     */
+    collectCharBoxes?: boolean;
+}
+/**
+ * This class represents lines of texts.
+ */
+export declare class MTextProcessor {
+    private _style;
+    private _styleManager;
+    private _fontManager;
+    private _options;
+    private _totalHeight;
+    private _hOffset;
+    private _vOffset;
+    private _lineCount;
+    private _currentLineObjects;
+    private _contextStack;
+    private _currentContext;
+    private _maxFontSize;
+    /**
+     * The current horizontal alignment for the paragraph.
+     *
+     * In AutoCAD MText, paragraph-level formatting commands (such as \pqr, \pql, \pqc)
+     * persist for the entire paragraph and are not scoped to inline formatting groups ({} blocks).
+     * Only character-level formatting (font, bold, italic, color, etc.) is scoped to {} and managed via Context.
+     * Therefore, paragraph alignment is maintained at the MTextProcessor level and not in Context,
+     * so it persists until explicitly changed by another paragraph alignment command.
+     */
+    private _currentHorizontalAlignment;
+    private _lastCharBoxTarget;
+    private _lineHasRenderableChar;
+    private _pendingEmptyLineFontSizeAdjust?;
+    private _lineLayouts;
+    private _lineBreakIndices;
+    private _processedCharCount;
+    private _currentIndent;
+    private _currentLeftMargin;
+    private _currentRightMargin;
+    /**
+     * Construct one instance of this class and initialize some properties with default values.
+     * @param style Input text style
+     * @param styleManager Input text style manager instance
+     * @param fontManager Input font manager instance
+     * @param options Input formating options
+     */
+    constructor(style: TextStyle, styleManager: StyleManager, fontManager: FontManager, options: MTextFormatOptions);
+    get fontManager(): FontManager;
+    get styleManager(): StyleManager;
+    get textStyle(): TextStyle;
+    /**
+     * Total height of all lines of text
+     */
+    get totalHeight(): number;
+    /**
+     * The maximum width of one text line
+     */
+    get maxWidth(): number;
+    /**
+     * The direction that the text string follows from its start to its finish.
+     */
+    get flowDirection(): MTextFlowDirection;
+    /**
+     * The default horizontal alignment of one text line
+     */
+    get defaultHorizontalAlignment(): MTextParagraphAlignment;
+    /**
+     * The default scale factor of character width
+     */
+    get defaultWidthFactor(): number;
+    /**
+     * The default font size of texts
+     */
+    get defaultFontSize(): number;
+    /**
+     * The default line space factor
+     */
+    get defaultLineSpaceFactor(): number;
+    /**
+     * Font name of current character
+     */
+    get currentFont(): string;
+    /**
+     * The current horizontal alignment of one text line
+     */
+    get currentHorizontalAlignment(): MTextParagraphAlignment;
+    /**
+     * Font size of current character
+     */
+    get currentFontSize(): number;
+    /**
+     * The height of current line of texts
+     */
+    get currentLineHeight(): number;
+    /**
+     * The maximum font size in current line. Characters in one line may have different font and font
+     * size. So we need to store the maximum font size in current line in order to calculate the height
+     * of current line.
+     */
+    get currentMaxFontSize(): number;
+    /**
+     * The current space setting between two characters. The meaning of this value is as follows.
+     * - 1: no extra spacing (default tracking)
+     * - 1.2: increases spacing by 20% of the text height
+     * - 0.8: decreases spacing by 20% of the text height
+     */
+    get currentWordSpace(): number;
+    /**
+     * The current scale factor of character width
+     */
+    get currentWidthFactor(): number;
+    /**
+     * All of THREE.js objects in current line. It contains objects in all of sections of this line.
+     */
+    get currentLineObjects(): THREE.Object3D<THREE.Object3DEventMap>[];
+    get lineLayouts(): LineLayout[];
+    /**
+     * The horizental offset of current character in this line
+     */
+    get hOffset(): number;
+    set hOffset(value: number);
+    /**
+     * The vertical offset of current character in this line
+     */
+    get vOffset(): number;
+    set vOffset(value: number);
+    get currentIndent(): number;
+    get currentLeftMargin(): number;
+    get currentRightMargin(): number;
+    get maxLineWidth(): number;
+    /**
+     * Process text format information
+     * @param item Input mtext inline codes
+     */
+    processFormat(item: ChangedProperties): void;
+    /**
+     * Reset paragraph properties to their default values from options.
+     */
+    private resetParagraphProperties;
+    /**
+     * Start a new paragraph by processing current geometries, resetting paragraph properties,
+     * and starting a new line with indent applied.
+     * @param geometries Current text geometries to process
+     * @param lineGeometries Current line geometries to process
+     * @param group The group to add processed geometries to
+     */
+    private startNewParagraph;
+    /**
+     * Render the specified texts
+     * @param item Input texts to render
+     */
+    processText(tokens: Generator<MTextToken>): THREE.Group<THREE.Object3DEventMap>;
+    private processGeometries;
+    private processWord;
+    private processStack;
+    private recordStackDivider;
+    /**
+     * Convert a legacy top-anchored vOffset (used by stack/sub/sup logic) into
+     * the current baseline-anchored coordinate system.
+     */
+    private convertTopAlignedVOffset;
+    private processBlank;
+    private recordVisualLineBreak;
+    private recordCurrentLineLayout;
+    private processChar;
+    private processLastLine;
+    private initLineParams;
+    private changeFont;
+    /**
+     * Calcuate font size, line space, line height and other parameters.
+     */
+    private calcuateLineParams;
+    /**
+     * Get text shape of the specified character
+     * @param char Input one character
+     * @returns Return the text shape of the specified character
+     */
+    private getCharShape;
+    private advanceToNextLine;
+    private countFinalCharBoxes;
+    private applyPendingEmptyLineYAdjust;
+    private resolveCharBoxTarget;
+    /**
+     * Apply translation on the specified buffer geometries according to text alignment setting
+     */
+    private processAlignment;
+    /**
+     * In AutoCAD, the width of a regular space character (ASCII 32, the space key on the keyboard) in MText
+     * depends on the current font and text height, and is not a fixed value.
+     * Specifically:
+     * - Space width ≈ Text height × space width ratio defined by the font
+     * - For common TrueType fonts (like Arial), the space width is typically about 1/4 to 1/3 of the text height.
+     * For example, if the text height is 10 (units), the space width would be approximately 2.5 to 3.3 units.
+     * - For SHX fonts (AutoCAD's built-in vector fonts, such as txt.shx), the space width is often half the text height.
+     * So if the text height is 10, the space width is typically 5 units.
+     */
+    private calculateBlankWidthForFont;
+    /**
+     * Convert the text shape geometries to three.js object
+     * @param geometries Input text shape geometries
+     * @returns Return three.js object created from the specified text shape geometries
+     */
+    private toThreeObject;
+    private changeFontSizeScaleFactor;
+    private changeFontHeight;
+}

package/lib/renderer/styleManager.d.ts

@@ -0,0 +1,20 @@
+import { StyleTraits } from './types';
+import * as THREE from 'three';
+/**
+ * Class to manage materials used by texts
+ */
+export interface StyleManager {
+    unsupportedTextStyles: Record<string, number>;
+    /**
+     * Gets one reusable material for mesh type font. If not found in cache, just create one.
+     * @param traits - Traits to define one mesh basic material
+     * @returns - One reusable material for mesh type font.
+     */
+    getMeshBasicMaterial(traits: StyleTraits): THREE.Material;
+    /**
+     * Gets one reusable material for line type font. If not found in cache, just create one.
+     * @param traits - Traits to define one line basic material
+     * @returns - One reusable material for line type font.
+     */
+    getLineBasicMaterial(traits: StyleTraits): THREE.Material;
+}

package/lib/renderer/types.d.ts

@@ -0,0 +1,199 @@
+import * as THREE from 'three';
+/**
+ * A 3D point in drawing coordinates.
+ */
+export interface Point3d {
+    /** X coordinate */
+    x: number;
+    /** Y coordinate */
+    y: number;
+    /** Z coordinate */
+    z: number;
+}
+/**
+ * A 2D point in drawing coordinates.
+ */
+export interface Point2d {
+    /** X coordinate */
+    x: number;
+    /** Y coordinate */
+    y: number;
+}
+/**
+ * Defines the global text flow direction for MText layout.
+ */
+export declare enum MTextFlowDirection {
+    /** Text flows from left to right. */
+    LEFT_TO_RIGHT = 1,
+    /** Text flows from right to left. */
+    RIGHT_TO_LEFT = 2,
+    /** Text flows from top to bottom. */
+    TOP_TO_BOTTOM = 3,
+    /** Text flows from bottom to top. */
+    BOTTOM_TO_TOP = 4,
+    /** Use the direction defined by the active text style. */
+    BY_STYLE = 5
+}
+/**
+ * Anchor position used to align rendered MText relative to its insertion point.
+ */
+export declare enum MTextAttachmentPoint {
+    /** Top-left corner. */
+    TopLeft = 1,
+    /** Top-center point. */
+    TopCenter = 2,
+    /** Top-right corner. */
+    TopRight = 3,
+    /** Middle-left point. */
+    MiddleLeft = 4,
+    /** Center point. */
+    MiddleCenter = 5,
+    /** Middle-right point. */
+    MiddleRight = 6,
+    /** Bottom-left corner. */
+    BottomLeft = 7,
+    /** Bottom-center point. */
+    BottomCenter = 8,
+    /** Bottom-right corner. */
+    BottomRight = 9
+}
+/**
+ * Logical text token with optional pick box information.
+ *
+ * Semantics by {@link CharBoxType}:
+ * - `CHAR`: `char` is the rendered character, `box` is defined, `children` is empty.
+ * - `STACK`: `char` is `''`, `box` is the union box of stack components, `children` contains stack parts.
+ */
+export interface CharBox {
+    /** Token type. */
+    type: CharBoxType;
+    /** Token bounding box in local MText coordinates. */
+    box: THREE.Box3;
+    /** Token character payload (`''` for `STACK`). */
+    char: string;
+    /** Nested token components (currently used by `STACK`). */
+    children: CharBox[];
+}
+/**
+ * Per-line layout geometry used by text cursor and line hit-testing.
+ */
+export interface LineLayout {
+    /** Line center Y used for cursor placement and hit-testing. */
+    y: number;
+    /** Line height used for cursor size and vertical hit area. */
+    height: number;
+    /**
+     * Visual line-break index in `MTextLayout.chars` for this line.
+     * Index `i` means a break between char `i - 1` and char `i`.
+     *
+     * This is line-boundary data (rendered rows), not paragraph structure.
+     * Duplicated indices are meaningful and represent empty lines.
+     *
+     * This field is `undefined` for the last rendered line.
+     */
+    breakIndex?: number;
+}
+/**
+ * Aggregated layout output for rendered MText.
+ */
+export interface MTextLayout {
+    /** Per-line layout entries. */
+    lines: LineLayout[];
+    /** Logical text token boxes for picking/debug. */
+    chars: CharBox[];
+}
+/**
+ * Type of logical token emitted in {@link CharBox} output.
+ */
+export declare enum CharBoxType {
+    /** Regular rendered character token. */
+    CHAR = "CHAR",
+    /** Stack token (for fraction-style stacked expressions). */
+    STACK = "STACK"
+}
+/**
+ * Sentinel character used internally to represent a stack divider line.
+ */
+export declare const STACK_DIVIDER_CHAR = "\uE000";
+export interface StyleTraits {
+    /**
+     * Optional layer name. Material is identified by layer and color. So it means different
+     * materials are created for the same color and differnt layer.
+     */
+    layer?: string;
+    /**
+     * The color of material
+     */
+    color: number;
+    /**
+     * One flag to indicate whether the color is by layer. If it is true, it means that the
+     * material become invalid once layer color changed.
+     */
+    isByLayer?: boolean;
+}
+/**
+ * Represents the data structure for multiline text (MText) entities.
+ * Contains all necessary properties to define the appearance and positioning of text.
+ */
+export interface MTextData {
+    /** The actual text content to be displayed */
+    text: string;
+    /** The height of the text characters in drawing units */
+    height: number;
+    /** The width of the text box in drawing units. Text will wrap if it exceeds this width */
+    width: number;
+    /** The 3D insertion point coordinates where the text will be placed */
+    position: Point3d;
+    /** The rotation angle of the text in radians. Default is 0 (horizontal) */
+    rotation?: number;
+    /** The normal vector that defines the plane in which the text lies. Used for 3D orientation */
+    directionVector?: Point3d;
+    /** Specifies which point of the text boundary is aligned with the insertion point */
+    attachmentPoint?: MTextAttachmentPoint;
+    /** Determines the primary direction in which text flows */
+    drawingDirection?: MTextFlowDirection;
+    /** Factor that controls the spacing between text lines. Default is 1.0 */
+    lineSpaceFactor?: number;
+    /** The width scaling factor applied to each character. Default is 1.0 */
+    widthFactor?: number;
+    /** Whether to collect per-character bounding boxes for picking. Default is true */
+    collectCharBoxes?: boolean;
+}
+/**
+ * Represents a text style configuration that defines the visual appearance and formatting of text.
+ * This interface contains properties that control various aspects of text rendering including font,
+ * dimensions, and display characteristics.
+ */
+export interface TextStyle extends StyleTraits {
+    /** The unique name identifier for this text style */
+    name: string;
+    /** Flag indicating standard text style settings. Controls various text generation behaviors */
+    standardFlag: number;
+    /** The fixed height of the text in drawing units. Used when text height should remain constant */
+    fixedTextHeight: number;
+    /** The horizontal scaling factor applied to text characters. Default is 1.0 for normal width */
+    widthFactor: number;
+    /** The angle in radians for italic text. 0.0 represents vertical text, positive values slant to the right */
+    obliqueAngle: number;
+    /** Bit-coded flag controlling text generation options (e.g., mirroring, upside-down) */
+    textGenerationFlag: number;
+    /** The most recently used text height for this style */
+    lastHeight: number;
+    /** The primary font name or file to be used for text rendering */
+    font: string;
+    /** The font name or file to be used for wide characters (typically used for CJK characters) */
+    bigFont: string;
+    /** Optional extended font settings or alternative font specification */
+    extendedFont?: string;
+}
+/**
+ * Defines the default color settings for special color modes in text rendering.
+ * These settings are used to resolve color values when text uses layer-dependent
+ * or block-dependent coloring.
+ */
+export interface ColorSettings {
+    /** The color value to use when text is set to "by layer" color mode */
+    byLayerColor: number;
+    /** The color value to use when text is set to "by block" color mode */
+    byBlockColor: number;
+}

package/lib/worker/baseRenderer.d.ts

@@ -0,0 +1,92 @@
+import { StyleManager } from '../renderer/styleManager';
+import { ColorSettings, MTextData, MTextLayout, TextStyle } from '../renderer/types';
+import * as THREE from 'three';
+/**
+ * Represents a rendered MText object that extends THREE.Object3D with additional MText-specific properties.
+ * This interface defines the contract for objects returned by MText renderers.
+ */
+export interface MTextObject extends THREE.Object3D {
+    /**
+     * The bounding box of the MText object in local coordinates.
+     * This box represents the bounds of the text content without considering transformations.
+     * To get the world-space bounding box, apply the object's world matrix to this box.
+     */
+    box: THREE.Box3;
+    /**
+     * Create text layout details (lines and logical char boxes) on demand.
+     * The result may be internally cached and reused by subsequent calls.
+     */
+    createLayoutData(): MTextLayout;
+}
+/**
+ * Defines the common rendering contract for producing Three.js objects from MText content.
+ *
+ * Implementations may render on the main thread or delegate work to a Web Worker,
+ * but they must expose the same high-level API so callers can switch strategies
+ * without changing usage.
+ */
+export interface MTextBaseRenderer {
+    /**
+     * Used to manage materials used by texts
+     */
+    get styleManager(): StyleManager;
+    set styleManager(value: StyleManager);
+    /**
+     * Render the provided MText content into a Three.js object hierarchy asynchronously
+     *
+     * The returned root object contains meshes/lines for glyphs and exposes a
+     * bounding box on `object.box`.
+     *
+     * @param mtextContent Structured MText input (text, height, width, position).
+     * @param textStyle Text style to apply (font, width factor, oblique, etc.).
+     * @param colorSettings Optional color context (ByLayer, ByBlock colors).
+     * @returns A Promise resolving to a populated `MTextObject` ready to add to a scene.
+     */
+    asyncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
+    /**
+     * Render the provided MText content into a Three.js object hierarchy synchronously.
+     *
+     * The returned root object contains meshes/lines for glyphs and exposes a
+     * bounding box on `object.box`.
+     *
+     * @param mtextContent Structured MText input (text, height, width, position).
+     * @param textStyle Text style to apply (font, width factor, oblique, etc.).
+     * @param colorSettings Optional color context (ByLayer, ByBlock colors).
+     * @returns A Promise resolving to a populated `MTextObject` ready to add to a scene.
+     */
+    syncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    /**
+     * Ensure the specified fonts are available to the renderer.
+     *
+     * Implementations should load and cache missing fonts; repeated calls should be cheap.
+     *
+     * @param fonts Font names to load (without extension for built-ins).
+     * @returns A Promise with the list of fonts that were processed.
+     */
+    loadFonts(fonts: string[]): Promise<{
+        loaded: string[];
+    }>;
+    /**
+     * Retrieve the list of fonts that can be used by the renderer.
+     *
+     * The shape of each font entry is implementation-defined but should include a displayable name.
+     *
+     * @returns A Promise with available font metadata.
+     */
+    getAvailableFonts(): Promise<{
+        fonts: Array<{
+            name: string[];
+        }>;
+    }>;
+    /**
+     * Set URL to load fonts
+     * @param value - URL to load fonts
+     */
+    setFontUrl(value: string): Promise<void>;
+    /**
+     * Release any resources owned by the renderer (e.g., terminate Web Workers).
+     *
+     * Safe to call multiple times.
+     */
+    destroy(): void;
+}

package/lib/worker/index.d.ts

@@ -0,0 +1,5 @@
+export * from './webWorkerRenderer';
+export * from './mainThreadRenderer';
+export * from './unifiedRenderer';
+export * from './unifiedRenderer';
+export * from './baseRenderer';

package/lib/worker/mainThreadRenderer.d.ts

@@ -0,0 +1,49 @@
+import { StyleManager } from '../renderer/styleManager';
+import { ColorSettings, MTextData, TextStyle } from '../renderer/types';
+import { MTextBaseRenderer, MTextObject } from './baseRenderer';
+/**
+ * Main thread renderer for MText objects
+ * This provides the same interface as the worker but runs in the main thread
+ */
+export declare class MainThreadRenderer implements MTextBaseRenderer {
+    private fontManager;
+    private defaultStyleManager;
+    private isInitialized;
+    constructor();
+    /**
+     * Used to manage materials used by texts
+     */
+    get styleManager(): StyleManager;
+    set styleManager(value: StyleManager);
+    /**
+     * Set URL to load fonts
+     * @param value - URL to load fonts
+     */
+    setFontUrl(value: string): Promise<void>;
+    /**
+     * Render MText directly in the main thread asynchronously. It will ensure that default font
+     * is loaded. And fonts needed in mtext are loaded on demand.
+     */
+    asyncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
+    /**
+     * Render MText directly in the main thread synchronously. It is user's responsibility to ensure
+     * that default font is loaded and fonts needed in mtext are loaded.
+     */
+    syncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    /**
+     * Load fonts in the main thread
+     */
+    loadFonts(fonts: string[]): Promise<{
+        loaded: string[];
+    }>;
+    /**
+     * Get available fonts from the main thread
+     */
+    getAvailableFonts(): Promise<{
+        fonts: Array<{
+            name: string[];
+        }>;
+    }>;
+    destroy(): void;
+    private ensureInitialized;
+}

package/lib/worker/mtextWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/worker/unifiedRenderer.d.ts

@@ -0,0 +1,69 @@
+import { StyleManager } from '../renderer';
+import { ColorSettings, MTextData, TextStyle } from '../renderer/types';
+import { MTextObject } from './baseRenderer';
+import { WebWorkerRendererConfig } from './webWorkerRenderer';
+export type RenderMode = 'main' | 'worker';
+/**
+ * Unified renderer that can work in both main thread and web worker modes
+ */
+export declare class UnifiedRenderer {
+    private webWorkerRenderer;
+    private mainThreadRenderer;
+    private renderer;
+    private defaultMode;
+    /**
+     * Constructor
+     *
+     * @param defaultMode - Default rendering mode. Default is 'main' which means rendering in main thread.
+     * @param workerConfig - Configuration options for WebWorkerRenderer which is used
+     *                     when render mode is 'worker'.
+     */
+    constructor(defaultMode?: RenderMode, workerConfig?: WebWorkerRendererConfig);
+    /**
+     * Sets one new style manager to override the default style manager
+     * @param value - New style manager
+     */
+    setStyleManager(value: StyleManager): void;
+    /**
+     * Sets the default rendering mmode
+     * @param mode The default rendering mode
+     */
+    setDefaultMode(mode: RenderMode): void;
+    /**
+     * Set URL to load fonts
+     * @param value - URL to load fonts
+     */
+    setFontUrl(value: string): Promise<void>;
+    /**
+     * Get the default rendering mode
+     */
+    getDefaultMode(): RenderMode;
+    /**
+     * Render MText using the current mode asynchronously.
+     * @param mode - Rendering mode used. If undefined, the default rendering mode is used.
+     */
+    asyncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings, mode?: RenderMode): Promise<MTextObject>;
+    /**
+     * Render MText using the current mode synchronously. Main thread render is always used
+     * for this function because web worker renderer doesn't support rendering synchronously.
+     */
+    syncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    /**
+     * Load fonts using the current mode
+     */
+    loadFonts(fonts: string[]): Promise<{
+        loaded: string[];
+    }>;
+    /**
+     * Get available fonts using the current mode
+     */
+    getAvailableFonts(): Promise<{
+        fonts: Array<{
+            name: string[];
+        }>;
+    }>;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}