@mlightcad/mtext-renderer 0.2.0

package/README.md

@@ -0,0 +1,241 @@
+# MText Renderer for Three.js
+
+A flexible and extensible AutoCAD MText renderer implementation using Three.js. This package provides a modular architecture to render AutoCAD MText content with different rendering engines, with a primary focus on Three.js rendering.
+
+## Features
+
+- Render AutoCAD MText content using Three.js
+- Modular font loading system
+- Font management and dynamic font loading
+- Cache parsed fonts to improve rendering performance
+
+## Core Components
+
+### FontManager
+
+The central manager for font operations. It's a singleton class that handles font loading, caching, and text rendering.
+
+**Public Properties:**
+- `unsupportedChars`: Record of characters not supported by any loaded font
+- `missedFonts`: Record of fonts that were requested but not found
+- `enableFontCache`: Flag to enable/disable font caching. If it is true, parsed fonts 
+will be stored in local IndexedDB to improve performance. Default value is true.
+- `defaultFont`: Default font to use when a requested font is not found
+- `events`: Event managers for font-related events
+  - `fontNotFound`: Triggered when a font cannot be found
+  - `fontLoaded`: Triggered when a font is successfully loaded
+
+**Public Methods:**
+- `loadFonts(urls)`: Loads fonts from URLs
+- `getCharShape(char, fontName, size)`: Gets text shape for a character
+- `getFontScaleFactor(fontName)`: Gets scale factor for a font
+- `getNotFoundTextShape(size)`: Gets shape for not found indicator
+- `getUnsupportedChar()`: Gets record of unsupported characters
+- `release()`: Releases all loaded fonts
+
+### FontLoader & DefaultFontLoader
+
+Interface for font loading operations. The default implementation [DefaultFontLoader](./src/font/defaultFontLoader.ts) uses a [CDN-based font repository](https://cdn.jsdelivr.net/gh/mlight-lee/cad-data/fonts/). It loads font metadata from a JSON file and provides access to available fonts. You can implement one font loader by your own if you want to use fonts hosted in your own server.
+
+**Public Methods:**
+- `load(fontNames)`: Loads specified fonts into the system
+- `getAvaiableFonts()`: Retrieves information about available fonts
+
+### BaseFont
+
+Abstract base class for font implementations. Provides common functionality for font handling.
+
+**Public Properties:**
+- `type`: Type of font ('shx' or 'mesh')
+- `data`: Parsed font data
+- `unsupportedChars`: Record of unsupported characters
+
+**Public Methods:**
+- `getCharShape(char, size)`: Gets shape for a character
+- `getScaleFactor()`: Gets font scale factor
+- `getNotFoundTextShape(size)`: Gets shape for not found indicator
+
+### BaseTextShape
+
+Abstract base class for text shape implementations. Provides common functionality for text shape handling.
+
+**Public Properties:**
+- `char`: Character this shape represents
+- `size`: Size of the text shape
+
+**Public Methods:**
+- `getWidth()`: Gets width of text shape
+- `getHeight()`: Gets height of text shape
+- `toGeometry()`: Converts shape to THREE.BufferGeometry
+
+### FontFactory
+
+Singleton factory class for creating font instances. Handles creation of appropriate font objects based on type and data format.
+
+**Public Methods:**
+- `createFont(data)`: Creates font from font data
+- `createFontFromBuffer(fileName, buffer)`: Creates font from file data
+
+### FontCacheManager
+Manages font data caching using IndexedDB. Provides persistent storage for font data.
+
+**Public Methods:**
+- `get(fileName)`: Retrieves font data from cache
+- `set(fileName, fontData)`: Stores font data in cache
+- `getAll()`: Retrieves all cached font data
+- `clear()`: Clears all cached font data
+
+### MText
+Main class for rendering AutoCAD MText content. Extends THREE.Object3D to integrate with Three.js scene graph.
+
+**Public Properties:**
+- `content`: MText content configuration including text, height, width, and position
+- `style`: Text style configuration including font, color, and text generation flags
+- `fontManager`: Reference to FontManager instance for font operations
+- `styleManager`: Reference to StyleManager instance for style operations
+
+**Public Methods:**
+- `update()`: Updates the text rendering based on current content and style
+- `setContent(content)`: Updates the text content
+- `setStyle(style)`: Updates the text style
+- `dispose()`: Cleans up resources when the MText instance is no longer needed
+
+## Class Diagram
+
+```mermaid
+classDiagram
+    class MText {
+        +content: MTextContent
+        +style: MTextStyle
+        +fontManager: FontManager
+        +styleManager: StyleManager
+        +update()
+        +setContent(content)
+        +setStyle(style)
+        +dispose()
+    }
+
+    class FontManager {
+        -_instance: FontManager
+        +unsupportedChars: Record
+        +missedFonts: Record
+        +enableFontCache: boolean
+        +defaultFont: string
+        +events: EventManagers
+        +loadFonts(urls)
+        +getCharShape(char, fontName, size)
+        +getFontScaleFactor(fontName)
+        +getNotFoundTextShape(size)
+        +getUnsupportedChar()
+        +release()
+    }
+
+    class FontLoader {
+        <<interface>>
+        +load(fontNames)
+        +getAvaiableFonts()
+    }
+
+    class DefaultFontLoader {
+        -_avaiableFonts: FontInfo[]
+        +load(fontNames)
+        +getAvaiableFonts()
+    }
+
+    class BaseFont {
+        <<abstract>>
+        +type: FontType
+        +data: unknown
+        +unsupportedChars: Record
+        +getCharShape(char, size)
+        +getScaleFactor()
+        +getNotFoundTextShape(size)
+    }
+
+    class BaseTextShape {
+        <<abstract>>
+        +char: string
+        +size: number
+        +getWidth()
+        +getHeight()
+        +toGeometry()
+    }
+
+    class FontFactory {
+        -_instance: FontFactory
+        +createFont(data)
+        +createFontFromBuffer(fileName, buffer)
+    }
+
+    class FontCacheManager {
+        -_instance: FontCacheManager
+        +get(fileName)
+        +set(fileName, fontData)
+        +getAll()
+        +clear()
+    }
+
+    MText --> FontManager
+    MText --> StyleManager
+    FontManager --> FontFactory
+    FontManager --> FontCacheManager
+    FontManager --> BaseFont
+    DefaultFontLoader ..|> FontLoader
+    BaseFont <|-- MeshFont
+    BaseFont <|-- ShxFont
+    BaseTextShape <|-- MeshTextShape
+    BaseTextShape <|-- ShxTextShape
+```
+
+## Usage
+
+```typescript
+import * as THREE from 'three';
+import { DefaultFontLoader, FontManager, MText, StyleManager } from '@mlightcad/mtext-renderer';
+
+// Initialize core components
+const fontManager = FontManager.instance;
+const styleManager = new StyleManager();
+const fontLoader = new DefaultFontLoader();
+
+// Load fonts needed
+await fontLoader.load(['simsun']);
+
+// Create MText content
+const mtextContent = {
+    text: '{\\fArial|b0|i0|c0|p34;Hello World}',
+    height: 0.1,
+    width: 0,
+    position: new THREE.Vector3(0, 0, 0)
+};
+
+// Create MText instance with style
+const mtext = new MText(
+    mtextContent,
+    {
+        name: 'Standard',
+        standardFlag: 0,
+        fixedTextHeight: 0.1,
+        widthFactor: 1,
+        obliqueAngle: 0,
+        textGenerationFlag: 0,
+        lastHeight: 0.1,
+        font: 'Standard',
+        bigFont: '',
+        color: 0xffffff
+    },
+    styleManager,
+    fontManager
+);
+
+// Add to Three.js scene
+scene.add(mtext);
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines for details. 

package/dist/cache/fontCacheManager.d.ts

@@ -0,0 +1,72 @@
+import { FontData } from '../font';
+
+/**
+ * A simple font cache interface that provides map-like operations for font data
+ */
+export declare class FontCacheManager {
+    private static readonly DATABASE_NAME;
+    private static readonly DATABASE_VERSION;
+    private static _instance;
+    private db;
+    private isClosing;
+    private constructor();
+    /**
+     * Returns the singleton instance of the FontCacheManager
+     */
+    static get instance(): FontCacheManager;
+    /**
+     * Sets a font in the cache
+     * @param fileName The font file name (key)
+     * @param fontData The font data to store
+     */
+    set(fileName: string, fontData: FontData): Promise<void>;
+    /**
+     * Gets a font from the cache
+     * @param fileName The font file name (key)
+     * @returns The font data if found, undefined otherwise
+     */
+    get(fileName: string): Promise<FontData | undefined>;
+    /**
+     * Deletes a font from the cache
+     * @param fileName The font file name (key)
+     */
+    delete(fileName: string): Promise<void>;
+    /**
+     * Gets all fonts from the cache
+     * @returns An array of all font data in the cache
+     */
+    getAll(): Promise<FontData[]>;
+    /**
+     * Clears all fonts from the cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Checks if a font exists in the cache
+     * @param fileName The font file name (key)
+     */
+    has(fileName: string): Promise<boolean>;
+    /**
+     * Closes the database connection and cleans up resources.
+     * After calling this, any further operations will require reopening the database.
+     */
+    close(): void;
+    /**
+     * Destroys the database instance and deletes all data.
+     * Use with caution as this operation cannot be undone.
+     */
+    destroy(): Promise<void>;
+    private getDatabase;
+    /**
+     * Applies all schema versions that are greater than the old version and less than or equal to the new version
+     * @param db The database instance
+     * @param oldVersion The old version of the database
+     * @param newVersion The new version of the database
+     */
+    private handleUpgrade;
+    /**
+     * Applies a single schema version's changes to the database
+     * @param db The database instance
+     * @param schema The schema version to apply
+     */
+    private applySchemaVersion;
+}

package/dist/cache/index.d.ts

@@ -0,0 +1 @@
+export * from './fontCacheManager';

package/dist/cache/schema.d.ts

@@ -0,0 +1,28 @@
+import { DBSchema } from 'idb';
+import { FontData } from '../font/font';
+
+/**
+ * Store name constant
+ */
+export declare const DB_STORES: {
+    readonly fonts: "fonts";
+};
+/**
+ * Database schema interface for the font cache
+ */
+export interface DbFontCacheSchema extends DBSchema {
+    [DB_STORES.fonts]: {
+        key: string;
+        value: FontData;
+    };
+}
+/**
+ * Database schema versions
+ */
+export declare const dbSchema: {
+    version: number;
+    stores: {
+        name: "fonts";
+        keyPath: string;
+    }[];
+}[];

package/dist/common/eventManager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The class representing one event manager
+ */
+export declare class EventManager<T = unknown> {
+    private listeners;
+    /**
+     * Add the event listener
+     * @param listener Input listener to be added
+     */
+    addEventListener(listener: (payload: T) => void): void;
+    /**
+     * Remove the listener
+     * @param listener Input listener to be removed
+     */
+    removeEventListener(listener: (payload: T) => void): void;
+    /**
+     * Remove all listeners bound to the target and add one new listener
+     * @param listener Input listener to be added
+     */
+    replaceEventListener(listener: (payload: T) => void): void;
+    /**
+     * Notify all listeners
+     * @param payload Input payload passed to listener
+     */
+    dispatch(payload?: T, ...args: unknown[]): void;
+}

package/dist/common/index.d.ts

@@ -0,0 +1,2 @@
+export * from './eventManager';
+export * from './utils';

package/dist/common/utils.d.ts

@@ -0,0 +1,11 @@
+export declare const getExtension: (url: string) => string;
+export declare const getFileName: (url: string) => string | undefined;
+export declare const getFileNameWithoutExtension: (url: string) => string;
+/**
+ * AutoCAD files sometimes use an indexed color value between 1 and 255 inclusive.
+ * Each value corresponds to a color. index 1 is red, that is 16711680 or 0xFF0000.
+ * index 0 and 256, while included in this array, are actually reserved for inheritance
+ * values in AutoCAD so they should not be used for index color lookups.
+ */
+export declare const AUTOCAD_COLOR_INDEX: number[];
+export declare const getColorByIndex: (index: number) => number;

package/dist/font/baseFont.d.ts

@@ -0,0 +1,48 @@
+import { BaseTextShape } from './baseTextShape';
+import { FontType } from './font';
+
+/**
+ * Abstract base class for font implementations.
+ * Provides common functionality and interface for font handling.
+ * This class defines the core interface that all font types must implement.
+ */
+export declare abstract class BaseFont {
+    /** The type of font (shx or mesh) */
+    abstract readonly type: FontType;
+    /**
+     * The parsed font data. Different types of fonts have different data structures.
+     * This data is used to render characters and calculate metrics.
+     */
+    abstract readonly data: unknown;
+    /**
+     * Record of characters that are not supported by this font.
+     * Maps character strings to their occurrence count.
+     * Used for tracking and reporting unsupported characters.
+     */
+    unsupportedChars: Record<string, number>;
+    /**
+     * 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
+     */
+    abstract getCharShape(char: string, size: number): BaseTextShape | 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
+     */
+    abstract getScaleFactor(): number;
+    /**
+     * Gets the shape to display when a character is not found in the font.
+     * @param size - The desired size of the not found shape
+     * @returns The shape data for the not found indicator, or undefined if not available
+     */
+    abstract getNotFoundTextShape(size: number): BaseTextShape | undefined;
+    /**
+     * Records an unsupported character in the font.
+     * Increments the count for the given character in unsupportedChars.
+     * @param char - The unsupported character to record
+     */
+    protected addUnsupportedChar(char: string): void;
+}

package/dist/font/baseTextShape.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from 'three';
+/**
+ * Abstract base class for text shape implementations.
+ * Provides common functionality and interface for text shape handling.
+ * This class defines the core interface that all text shape types must implement.
+ */
+export declare abstract class BaseTextShape extends THREE.Shape {
+    /** The character this shape represents */
+    readonly char: string;
+    /**
+     * Width used to render this character
+     */
+    width: number;
+    /**
+     * Creates a new instance of BaseTextShape
+     * @param char - The character this shape represents   */
+    constructor(char: string);
+    /**
+     * Converts the text shape to a THREE.js geometry
+     * @returns A THREE.js BufferGeometry representing the text shape
+     */
+    abstract toGeometry(): THREE.BufferGeometry;
+}

package/dist/font/defaultFontLoader.d.ts

@@ -0,0 +1,34 @@
+import { FontInfo, FontLoader } from './fontLoader';
+
+/**
+ * Default implementation of the FontLoader interface.
+ * This class provides font loading functionality using a [CDN-based font repository](https://cdn.jsdelivr.net/gh/mlight-lee/cad-data/fonts/).
+ * It loads font metadata from a JSON file and provides access to available fonts.
+ */
+export declare class DefaultFontLoader implements FontLoader {
+    /** List of available fonts in the system */
+    private _avaiableFonts;
+    /**
+     * Creates a new instance of DefaultFontLoader
+     */
+    constructor();
+    /**
+     * Gets the list of available fonts
+     * @returns Array of FontInfo objects describing available fonts
+     */
+    get avaiableFonts(): FontInfo[];
+    /**
+     * Retrieves information about all available fonts in the system.
+     * Loads font metadata from a CDN if not already loaded.
+     * @returns Promise that resolves to an array of FontInfo objects
+     * @throws {Error} If font metadata cannot be loaded from the CDN
+     */
+    getAvaiableFonts(): Promise<FontInfo[]>;
+    /**
+     * Loads the specified fonts into the system.
+     * If no font names are provided, loads all available fonts.
+     * @param fontNames - Array of font names to load
+     * @returns Promise that resolves to an array of FontLoadStatus objects
+     */
+    load(fontNames: string[]): Promise<import('./fontLoader').FontLoadStatus[]>;
+}

package/dist/font/font.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Represents the type of font supported by the system
+ * - 'shx': SHX font format commonly used in CAD systems
+ * - 'mesh': Mesh-based font format (e.g., TTF, OTF, WOFF)
+ */
+export type FontType = 'shx' | 'mesh';
+/**
+ * Represents font data stored in the cache database.
+ * This interface defines the structure of font data that is stored and retrieved from the cache.
+ */
+export interface FontData {
+    /** The name of the font */
+    name: string;
+    /** The type of font (shx or mesh) */
+    type: FontType;
+    /** The parsed font data. Different types of fonts have different data structures. */
+    data: unknown;
+}

package/dist/font/fontFactory.d.ts

@@ -0,0 +1,42 @@
+import { BaseFont } from './baseFont';
+import { FontData } from './font';
+
+/**
+ * A singleton factory class for creating font instances.
+ * This factory can create both ShxFont and MeshFont instances based on the provided font data.
+ * It handles the creation of appropriate font objects based on the font type and data format.
+ *
+ * @example
+ * ```typescript
+ * const fontFactory = FontFactory.getInstance();
+ * const font = fontFactory.createFont(fontData);
+ * ```
+ */
+export declare class FontFactory {
+    private static _instance;
+    private constructor();
+    /**
+     * Gets the singleton instance of the FontFactory
+     * @returns The FontFactory instance
+     */
+    static get instance(): FontFactory;
+    /**
+     * Creates a font instance based on the provided font data.
+     * The type of font created (ShxFont or MeshFont) is determined by the font type.
+     *
+     * @param data - The font data to create the font instance from
+     * @returns A new instance of either ShxFont or MeshFont
+     * @throws {Error} If the font data type is not supported
+     */
+    createFont(data: FontData): BaseFont;
+    /**
+     * Creates a font instance from a file name and its ArrayBuffer data.
+     * The type of font created is determined by the file extension.
+     *
+     * @param fileName - The name of the font file
+     * @param buffer - The ArrayBuffer containing the font data
+     * @returns A new instance of either ShxFont or MeshFont
+     * @throws {Error} If the file type is not supported
+     */
+    createFontFromBuffer(fileName: string, buffer: ArrayBuffer): BaseFont;
+}

package/dist/font/fontLoader.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Represents information about a font in the system
+ */
+export interface FontInfo {
+    /** Array of font names/aliases */
+    name: string[];
+    /** Font file name */
+    file: string;
+    /** Type of the font - either mesh or shx format */
+    type: 'woff' | 'shx';
+    /** URL where the font can be accessed */
+    url: string;
+}
+/**
+ * Represents the status of a font loading operation
+ */
+export interface FontLoadStatus {
+    /** Name of the font that was loaded */
+    fontName: string;
+    /** URL from which the font was loaded */
+    url: string;
+    /** Whether the font was successfully loaded */
+    status: boolean;
+}
+/**
+ * Interface that defines font loading functionality.
+ * Applications should implement this interface to provide font loading capabilities.
+ * This interface abstracts the font loading process, allowing different implementations
+ * for different font sources or loading strategies.
+ */
+export interface FontLoader {
+    /**
+     * Loads the specified fonts into the system
+     * @param fontNames - Array of font names to load
+     * @returns Promise that resolves to an array of FontLoadStatus objects indicating the load status of each font
+     */
+    load(fontNames: string[]): Promise<FontLoadStatus[]>;
+    /**
+     * Retrieves information about all available fonts in the system
+     * @returns Promise that resolves to an array of FontInfo objects containing details about available fonts
+     */
+    getAvaiableFonts(): Promise<FontInfo[]>;
+}