@mlightcad/mtext-renderer 0.9.3 → 0.10.0

package/lib/renderer/mtextProcessor.d.ts

@@ -1,244 +0,0 @@
-import { ChangedProperties, MTextParagraphAlignment, MTextToken } from '@mlightcad/mtext-parser';
-import { FontManager } from '../font';
-import { StyleManager } from './styleManager';
-import { 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 _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>[];
-    /**
-     * 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 recordLineBreak;
-    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 startNewLine;
-    private advanceToNextLine;
-    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

@@ -1,20 +0,0 @@
-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

@@ -1,175 +0,0 @@
-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.
- * - `NEW_PARAGRAPH`: `char` is `\n`. The `box` represents a zero-width vertical
- *   line whose height equals the current line height. `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`, `\n` for `NEW_PARAGRAPH`). */
-    char: string;
-    /** Nested token components (currently used by `STACK`). */
-    children: CharBox[];
-}
-/**
- * Type of logical token emitted in {@link CharBox} output.
- */
-export declare enum CharBoxType {
-    /** Regular rendered character token. */
-    CHAR = "CHAR",
-    /** Explicit paragraph break token. */
-    NEW_PARAGRAPH = "NEW_PARAGRAPH",
-    /** 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

@@ -1,91 +0,0 @@
-import { StyleManager } from '../renderer/styleManager';
-import { CharBox, ColorSettings, MTextData, 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;
-    /**
-     * The list of bounding boxes for each glyph in the MText object.
-     */
-    charBoxes: CharBox[];
-}
-/**
- * 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

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

package/lib/worker/mainThreadRenderer.d.ts

@@ -1,49 +0,0 @@
-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

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

package/lib/worker/unifiedRenderer.d.ts

@@ -1,69 +0,0 @@
-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;
-}