@mlightcad/mtext-renderer 0.6.4 → 0.7.0

package/lib/font/baseFont.d.ts

@@ -1,6 +1,6 @@
 import { BaseTextShape } from './baseTextShape';
 import { CharGeometryCache } from './charGeometryCache';
-import { FontType } from './font';
+import { FontData, FontType } from './font';
 /**
  * Abstract base class for font implementations.
  * Provides common functionality and interface for font handling.
@@ -14,17 +14,32 @@ export declare abstract class BaseFont {
      * This data is used to render characters and calculate metrics.
      */
     abstract readonly data: unknown;
+    /**
+     * Font names. One font may have multiple names.
+     */
+    names: Set<string>;
+    /**
+     * Encoding used by character code. Please refer to the following link for encoding name.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
+     */
+    encoding?: string;
     /**
      * Caching of font character geometries to improve text rendering performance.
      */
     cache: CharGeometryCache;
-    constructor();
+    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.
      */
     abstract 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.
+     */
+    abstract hasCode(code: number): boolean;
     /**
      * Record of characters that are not supported by this font.
      * Maps character strings to their occurrence count.
@@ -38,6 +53,13 @@ export declare abstract class BaseFont {
      * @returns The shape data for the character, or undefined if not found
      */
     abstract getCharShape(char: string, size: number): BaseTextShape | undefined;
+    /**
+     * Gets the shape data for a specific character code at a given size.
+     * @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
+     */
+    abstract getCodeShape(code: number, size: number): BaseTextShape | undefined;
     /**
      * Gets the scale factor for this font.
      * This is used to adjust the size of characters when rendering.

package/lib/font/baseTextShape.d.ts

@@ -5,16 +5,10 @@ import * as THREE from 'three';
  * 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

package/lib/font/charGeometryCache.d.ts

@@ -6,37 +6,37 @@ export declare class CharGeometryCache {
     private cache;
     constructor();
     /**
-     * Returns true if the geometry of the specified character exists in the cache.
+     * Returns true if the geometry of the specified character code exists in the cache.
      * Otherwise, returns false.
-     * @param char One character.
+     * @param code One character code.
      * @param size The font size.
-     * @returns True if the geometry of the specified character exists in the cache.
+     * @returns True if the geometry of the specified character code exists in the cache.
      * Otherwise, returns false.
      */
-    hasGeometry(char: string, size: number): boolean;
+    hasGeometry(code: number, size: number): boolean;
     /**
      * Get the geometry for a single character from cache if available.
-     * The cache key includes both character and size.
-     * @param char The character to get geometry from cache.
+     * The cache key includes both character codeand size.
+     * @param code The character code to get geometry from cache.
      * @param size The font size.
      * @returns The geometry for a single character from cache if avaiable.
      * Return undefined if the character not found in cache.
      */
-    getGeometry(char: string, size: number): THREE.BufferGeometry | undefined;
+    getGeometry(code: number, size: number): THREE.BufferGeometry | undefined;
     /**
      * Set the geometry to cache for a single character.
      * @param char The character to set geometry for.
      * @param size The font size.
      * @param geometry The geometry to set.
      */
-    setGeometry(char: string, size: number, geometry: THREE.BufferGeometry): void;
+    setGeometry(code: number, size: number, geometry: THREE.BufferGeometry): void;
     /**
      * Dispose all cached geometries.
      */
     dispose(): void;
     /**
      * Generates cache key by character and font size.
-     * @param char One character.
+     * @param char One character code.
      * @param size The font size.
      */
     private generateKey;

package/lib/font/defaultFontLoader.d.ts

@@ -1,13 +1,14 @@
 import { FontInfo, FontLoader, FontLoadStatus } 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/).
+ * This class provides font loading functionality using [this font repository](https://mlightcad.gitlab.io/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;
     private _baseUrl;
+    private _avaiableFontMap;
     /**
      * Creates a new instance of DefaultFontLoader
      */
@@ -22,13 +23,18 @@ export declare class DefaultFontLoader implements FontLoader {
      * @returns Array of FontInfo objects describing available fonts
      */
     get avaiableFonts(): FontInfo[];
+    /**
+     * Triggered when font url changed
+     * @param url - New font url value
+     */
+    onFontUrlChanged(url: string): void;
     /**
      * 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[]>;
+    getAvailableFonts(): Promise<FontInfo[]>;
     /**
      * Loads the specified fonts into the system. If one font is already loaded,
      * the font will not be loaded again. If no font names are provided, just loads
@@ -37,4 +43,8 @@ export declare class DefaultFontLoader implements FontLoader {
      * @returns Promise that resolves to an array of FontLoadStatus objects
      */
     load(fontNames: string[]): Promise<FontLoadStatus[]>;
+    /**
+     * Build one font map. The key is font name. The value is font info.
+     */
+    private buildFontMap;
 }

package/lib/font/font.d.ts

@@ -9,10 +9,17 @@ export type FontType = 'shx' | 'mesh';
  * This interface defines the structure of font data that is stored and retrieved from the cache.
  */
 export interface FontData {
-    /** The name of the font */
+    /** The font name */
     name: string;
+    /** The alias names of the font */
+    alias: string[];
     /** The type of font (shx or mesh) */
     type: FontType;
+    /**
+     * Encoding used by character code. Please refer to the following link for encoding name.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
+     */
+    encoding?: string;
     /** The parsed font data. Different types of fonts have different data structures. */
     data: unknown;
 }

package/lib/font/fontFactory.d.ts

@@ -28,14 +28,4 @@ export declare class FontFactory {
      * @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/lib/font/fontLoader.d.ts

@@ -7,9 +7,14 @@ export interface FontInfo {
     /** Font file name */
     file: string;
     /** Type of the font - either mesh or shx format */
-    type: 'woff' | 'shx';
+    type: 'mesh' | 'shx';
     /** URL where the font can be accessed */
     url: string;
+    /**
+     * Encoding used by character code. Please refer to the following link for encoding name.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
+     */
+    encoding?: string;
 }
 /**
  * Represents the status of a font loading operation
@@ -19,8 +24,13 @@ export interface FontLoadStatus {
     fontName: string;
     /** URL from which the font was loaded */
     url: string;
-    /** Whether the font was successfully loaded */
-    status: boolean;
+    /**
+     * The status to load font
+     * - Success
+     * - Font not found in font repository
+     * - Failed to load font from font repository
+     */
+    status: 'Success' | 'NotFound' | 'FailedToLoad';
 }
 /**
  * Interface that defines font loading functionality.
@@ -39,5 +49,10 @@ export interface FontLoader {
      * 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[]>;
+    getAvailableFonts(): Promise<FontInfo[]>;
+    /**
+     * Base URL to load fonts
+     */
+    get baseUrl(): string;
+    set baseUrl(value: string);
 }

package/lib/font/fontManager.d.ts

@@ -2,7 +2,7 @@ import { EventManager } from '../common';
 import { BaseFont } from './baseFont';
 import { BaseTextShape } from './baseTextShape';
 import { FontType } from './font';
-import { FontLoader, FontLoadStatus } from './fontLoader';
+import { FontInfo, FontLoader, FontLoadStatus } from './fontLoader';
 /**
  * Font mappings configuration.
  * Maps original font names to their replacement font names.
@@ -60,6 +60,11 @@ export declare class FontManager {
      * @returns The FontManager instance
      */
     static get instance(): FontManager;
+    /**
+     * Base URL to load fonts
+     */
+    get baseUrl(): string;
+    set baseUrl(value: string);
     /**
      * Sets the font mapping configuration
      * @param mapping - The font mapping to set
@@ -76,7 +81,7 @@ export declare class FontManager {
      * @returns Promise that resolves to an array of FontInfo objects
      * @throws {Error} If font metadata cannot be loaded from the CDN
      */
-    getAvaiableFonts(): Promise<import('./fontLoader').FontInfo[]>;
+    getAvailableFonts(): Promise<FontInfo[]>;
     /**
      * Return true if the default font was loaded.
      * @returns True if the default font was loaded. False otherwise.
@@ -86,19 +91,19 @@ export declare class FontManager {
      * Loads the default font
      * @returns Promise that resolves to the font load statuses
      */
-    loadDefaultFont(): Promise<FontLoadStatus>;
+    loadDefaultFont(): Promise<FontLoadStatus[]>;
     /**
      * Loads the specified fonts from font names
      * @param names - Font names to load.
      * @returns Promise that resolves to an array of font load statuses
      */
-    loadFontsByNames(names: string | string[]): Promise<FontLoadStatus>;
+    loadFontsByNames(names: string | string[]): Promise<FontLoadStatus[]>;
     /**
      * Loads the specified fonts from URLs
      * @param urls - URLs of font files to load.
      * @returns Promise that resolves to an array of font load statuses
      */
-    loadFontsByUrls(urls: string | string[]): Promise<FontLoadStatus[]>;
+    loadFonts(fonts: FontInfo | FontInfo[]): Promise<FontLoadStatus[]>;
     /**
      * Tries to find the specified font. If not found, uses a replacement font and returns its name.
      * @param fontName - The font name to find
@@ -116,8 +121,6 @@ export declare class FontManager {
     /**
      * Gets the first font which contains the specified character.
      * @param char - The character to get the shape for
-     * @param fontName - The name of the font to use
-     * @param size - The size of the character
      * @returns The text shape for the character, or undefined if not found
      */
     getFontByChar(char: string): BaseFont | undefined;
@@ -159,10 +162,11 @@ export declare class FontManager {
      */
     private recordMissedFonts;
     /**
-     * Loads a single font from a URL
-     * @param url - The URL of the font file to load
+     * Loads a single font
+     * @param fontInfo - The matadata of the font to be loaded
      */
     private loadFont;
+    private fontInfoToFontData;
     /**
      * Loads all fonts from the cache
      */

package/lib/font/meshFont.d.ts

@@ -1,11 +1,12 @@
-import { Font, FontData } from 'three/examples/jsm/loaders/FontLoader.js';
+import { Font, FontData as ThreeFontData } from 'three/examples/jsm/loaders/FontLoader.js';
 import { BaseFont } from './baseFont';
+import { FontData } from './font';
 import { MeshTextShape } from './meshTextShape';
 /**
  * Represents the data structure for mesh-based fonts.
- * Extends the base FontData interface with additional properties specific to mesh fonts.
+ * Extends the base ThreeFontData interface with additional properties specific to mesh fonts.
  */
-export interface MeshFontData extends FontData {
+export interface MeshFontData extends ThreeFontData {
     /** Scale factor used to adjust the size of characters when rendering */
     scaleFactor: number;
 }
@@ -27,13 +28,19 @@ export declare class MeshFont extends BaseFont {
      * Creates a new instance of MeshFont.
      * @param data - Either a MeshFontData object containing font information or an ArrayBuffer containing raw font data
      */
-    constructor(data: MeshFontData | ArrayBuffer);
+    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;
     /**
      * Generates shapes for a text string
      * @param text - The text to generate shapes for
@@ -48,6 +55,13 @@ export declare class MeshFont extends BaseFont {
      * @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.

package/lib/font/meshTextShape.d.ts

@@ -12,6 +12,7 @@ export declare class MeshTextShape extends BaseTextShape {
      * 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);

package/lib/font/shxFont.d.ts

@@ -1,5 +1,6 @@
 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.
@@ -10,13 +11,19 @@ export declare class ShxFont extends BaseFont {
     private readonly font;
     readonly type = "shx";
     readonly data: ShxFontData;
-    constructor(data: ShxFontData | ArrayBuffer);
+    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.
@@ -25,14 +32,31 @@ export declare class ShxFont extends BaseFont {
     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

@@ -9,15 +9,16 @@ import * as THREE from 'three';
  */
 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 char - The character this shape represents
+     * @param code - The character code this shape represents
      * @param shape - The shape data for this character
      */
-    constructor(char: string, fontSize: number, shape: ShxShape, font: ShxFont);
+    constructor(code: number, fontSize: number, shape: ShxShape, font: ShxFont);
     protected calcWidth(): number;
     offset(offset: Point): ShxTextShape;
     /**

package/lib/renderer/mtext.d.ts

@@ -52,6 +52,11 @@ export declare class MText extends THREE.Object3D {
      * @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.
      */
@@ -114,4 +119,10 @@ export declare class MText extends THREE.Object3D {
      * @param boxes - Array to store the calculated bounding boxes
      */
     private getBoxes;
+    /**
+     * 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;
 }

package/lib/worker/baseRenderer.d.ts

@@ -67,6 +67,11 @@ export interface MTextBaseRenderer {
             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).
      *

package/lib/worker/mainThreadRenderer.d.ts

@@ -9,6 +9,11 @@ export declare class MainThreadRenderer implements MTextBaseRenderer {
     private styleManager;
     private isInitialized;
     constructor();
+    /**
+     * 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.

package/lib/worker/unifiedRenderer.d.ts

@@ -23,6 +23,11 @@ export declare class UnifiedRenderer {
      * @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
      */

package/lib/worker/webWorkerRenderer.d.ts

@@ -111,13 +111,25 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
     private styleManager;
     constructor(config?: WebWorkerRendererConfig);
     private ensureInitialized;
+    /**
+     * Handles messages coming from any worker.
+     */
     private handleWorkerMessage;
+    /**
+     * Attaches message and error handlers to a worker.
+     */
     private attachWorkerHandlers;
     private pickLeastLoadedWorker;
-    private sendMessage;
+    private sendMessageToAllWorkers;
+    private sendMessageToOneWorker;
     private ensureTasksFinished;
     /**
-     * Render MText in the worker and return serialized data asynchronously.
+     * Set URL to load fonts
+     * @param value - URL to load fonts
+     */
+    setFontUrl(value: string): Promise<void>;
+    /**
+     * Render MText in one worker and return serialized data asynchronously.
      */
     asyncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
     /**
@@ -125,15 +137,9 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * Notes: It isn't supported yet.
      */
     syncRenderMText(_mtextContent: MTextData, _textStyle: TextStyle, _colorSettings?: ColorSettings): MTextObject;
-    /**
-     * Load fonts in the worker
-     */
     loadFonts(fonts: string[]): Promise<{
         loaded: string[];
     }>;
-    /**
-     * Get available fonts from the worker
-     */
     getAvailableFonts(): Promise<{
         fonts: Array<{
             name: string[];

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/mlightcad/mtext-renderer"
+  },
+  "homepage": "https://gitlab.com/mlightcad/mtext-renderer",
   "main": "./dist/index.umd.cjs",
   "module": "./dist/index.js",
   "types": "./lib/index.d.ts",
@@ -24,14 +29,15 @@
     "mtext",
     "three.js",
     "renderer",
-    "3d",
-    "text"
+    "webgl",
+    "3d-text"
   ],
   "dependencies": {
     "@mlightcad/mtext-parser": "^1.2.0",
-    "@mlightcad/shx-parser": "^1.2.0",
-    "opentype.js": "^1.3.4",
-    "idb": "^8.0.3"
+    "@mlightcad/shx-parser": "^1.3.0",
+    "iconv-lite": "^0.7.0",
+    "idb": "^8.0.3",
+    "opentype.js": "^1.3.4"
   },
   "devDependencies": {
     "@types/opentype.js": "^1.3.8",