meshwriter-cudu 3.0.0

package/src/meshSplitter.js

@@ -0,0 +1,337 @@
+import { Mesh, VertexData } from './babylonImports.js'
+
+/**
+ * Split a mesh into two meshes: emissive face geometry and lit rim geometry.
+ * @param {import('@babylonjs/core').Mesh} mesh
+ * @param {import('@babylonjs/core').Scene} scene
+ * @returns {{ rimMesh: import('@babylonjs/core').Mesh, faceMesh: import('@babylonjs/core').Mesh | null }}
+ */
+export function splitMeshByFaceNormals(mesh, scene) {
+    var geometry = mesh.geometry
+    if (!geometry) {
+        return { rimMesh: mesh, faceMesh: null }
+    }
+
+    var positions = geometry.getVerticesData('position')
+    var normals = geometry.getVerticesData('normal')
+    var uvs = geometry.getVerticesData('uv')
+    var indices = geometry.getIndices()
+
+    if (!positions || !normals || !indices || positions.length === 0) {
+        return { rimMesh: mesh, faceMesh: null }
+    }
+
+    var faceData = createEmptyData()
+    var rimData = createEmptyData()
+
+    var axisInfo = detectFaceAxisFromGeometry(positions, normals, indices)
+    if (!axisInfo) {
+        axisInfo = detectFaceAxis(normals)
+    }
+    if (!axisInfo) {
+        axisInfo = detectExtrudeAxisFromPositions(positions)
+    }
+
+    for (var i = 0; i < indices.length; i += 3) {
+        var i0 = indices[i]
+        var i1 = indices[i + 1]
+        var i2 = indices[i + 2]
+        var isFace = triangleIsFrontFace(i0, i1, i2, positions, normals, axisInfo)
+        var target = isFace ? faceData : rimData
+        var v0 = appendVertex(target, i0, positions, normals, uvs)
+        var v1 = appendVertex(target, i1, positions, normals, uvs)
+        var v2 = appendVertex(target, i2, positions, normals, uvs)
+        target.indices.push(v0, v1, v2)
+    }
+
+    mesh.dispose()
+
+    var rimMesh = buildMesh(mesh.name + '_rim', rimData, scene)
+    var faceMesh = buildMesh(mesh.name + '_face', faceData, scene)
+
+    if (!faceMesh) {
+        return { rimMesh: rimMesh || mesh, faceMesh: null }
+    }
+    if (!rimMesh) {
+        return { rimMesh: faceMesh, faceMesh: null }
+    }
+    return { rimMesh, faceMesh }
+}
+
+function detectFaceAxisFromGeometry(positions, normals, indices) {
+    if (!positions || !indices) return null
+
+    var min = [Infinity, Infinity, Infinity]
+    var max = [-Infinity, -Infinity, -Infinity]
+    for (var i = 0; i < positions.length; i += 3) {
+        var x = positions[i]
+        var y = positions[i + 1]
+        var z = positions[i + 2]
+        if (x < min[0]) min[0] = x
+        if (x > max[0]) max[0] = x
+        if (y < min[1]) min[1] = y
+        if (y > max[1]) max[1] = y
+        if (z < min[2]) min[2] = z
+        if (z > max[2]) max[2] = z
+    }
+
+    var epsilons = [
+        Math.max((max[0] - min[0]) * 0.15, 0.001),
+        Math.max((max[1] - min[1]) * 0.15, 0.001),
+        Math.max((max[2] - min[2]) * 0.15, 0.001)
+    ]
+
+    var counts = [
+        { min: 0, max: 0, sumMin: 0, sumMax: 0 },
+        { min: 0, max: 0, sumMin: 0, sumMax: 0 },
+        { min: 0, max: 0, sumMin: 0, sumMax: 0 }
+    ]
+
+    for (var idx = 0; idx < indices.length; idx += 3) {
+        var i0 = indices[idx]
+        var i1 = indices[idx + 1]
+        var i2 = indices[idx + 2]
+
+        for (var axis = 0; axis < 3; axis++) {
+            var epsilon = epsilons[axis]
+            if (epsilon <= 0) continue
+            var minVal = min[axis]
+            var maxVal = max[axis]
+
+            var c0 = positions[i0 * 3 + axis]
+            var c1 = positions[i1 * 3 + axis]
+            var c2 = positions[i2 * 3 + axis]
+
+            var nearMin = Math.abs(c0 - minVal) < epsilon &&
+                Math.abs(c1 - minVal) < epsilon &&
+                Math.abs(c2 - minVal) < epsilon
+            var nearMax = Math.abs(c0 - maxVal) < epsilon &&
+                Math.abs(c1 - maxVal) < epsilon &&
+                Math.abs(c2 - maxVal) < epsilon
+
+            if (nearMin) {
+                counts[axis].min++
+                if (normals) {
+                    counts[axis].sumMin += normals[i0 * 3 + axis] + normals[i1 * 3 + axis] + normals[i2 * 3 + axis]
+                }
+            } else if (nearMax) {
+                counts[axis].max++
+                if (normals) {
+                    counts[axis].sumMax += normals[i0 * 3 + axis] + normals[i1 * 3 + axis] + normals[i2 * 3 + axis]
+                }
+            }
+        }
+    }
+
+    var bestAxis = -1
+    var bestCount = 0
+    for (var axisIdx = 0; axisIdx < 3; axisIdx++) {
+        var total = counts[axisIdx].min + counts[axisIdx].max
+        if (total > bestCount) {
+            bestCount = total
+            bestAxis = axisIdx
+        }
+    }
+
+    if (bestAxis === -1 || bestCount === 0) {
+        return null
+    }
+
+    // For 3D text, extrusion is typically along Y axis (axis=1).
+    // If Y axis has any face triangles and the detected axis is different,
+    // prefer Y unless the detected axis has significantly more triangles.
+    var yTotal = counts[1].min + counts[1].max
+    if (bestAxis !== 1 && yTotal > 0) {
+        // Only switch away from Y if another axis has 2x more triangles
+        if (bestCount < yTotal * 2) {
+            bestAxis = 1
+            bestCount = yTotal
+        }
+    }
+
+    var chosen = counts[bestAxis]
+    var frontSide
+    // For PolygonMeshBuilder extrusions: geometry goes from Y=0 (base) to Y=-depth (extruded end)
+    // After rotation -PI/2 around X: Y=0 → Z=0 (front, facing camera), Y=-depth → Z=+depth (back)
+    // So Y=max (Y=0) is the FRONT face, Y=min (Y=-depth) is the BACK face
+    var maxHasOutwardNormals = chosen.sumMax > 0
+    var minHasOutwardNormals = chosen.sumMin < 0
+
+    // Select MAX as front (the base at Y=0 which faces camera after rotation)
+    if (maxHasOutwardNormals) {
+        frontSide = 'max'
+    } else if (minHasOutwardNormals) {
+        frontSide = 'min'
+    } else {
+        // Fallback to max (the base)
+        frontSide = 'max'
+    }
+
+    return {
+        axis: bestAxis,
+        strategy: 'positions',
+        min: min[bestAxis],
+        max: max[bestAxis],
+        epsilon: epsilons[bestAxis],
+        frontSide
+    }
+}
+
+function detectFaceAxis(normals) {
+    if (!normals || normals.length === 0) {
+        return null
+    }
+    var sumsAbs = [0, 0, 0]
+    var sumsSigned = [0, 0, 0]
+    for (var i = 0; i < normals.length; i += 3) {
+        var nx = normals[i]
+        var ny = normals[i + 1]
+        var nz = normals[i + 2]
+        sumsAbs[0] += Math.abs(nx)
+        sumsAbs[1] += Math.abs(ny)
+        sumsAbs[2] += Math.abs(nz)
+        sumsSigned[0] += nx
+        sumsSigned[1] += ny
+        sumsSigned[2] += nz
+    }
+    var axis = 0
+    var maxSum = sumsAbs[0]
+    for (var j = 1; j < 3; j++) {
+        if (sumsAbs[j] > maxSum) {
+            maxSum = sumsAbs[j]
+            axis = j
+        }
+    }
+    if (maxSum === 0) {
+        return null
+    }
+    var frontSign = sumsSigned[axis] >= 0 ? 1 : -1
+    return {
+        axis,
+        frontSign,
+        strategy: 'normals',
+        min: 0,
+        max: 0,
+        epsilon: 0,
+        frontSide: 'max'
+    }
+}
+
+function detectExtrudeAxisFromPositions(positions) {
+    if (!positions || positions.length === 0) {
+        return null
+    }
+    var min = [Infinity, Infinity, Infinity]
+    var max = [-Infinity, -Infinity, -Infinity]
+    for (var i = 0; i < positions.length; i += 3) {
+        var x = positions[i]
+        var y = positions[i + 1]
+        var z = positions[i + 2]
+        if (x < min[0]) min[0] = x
+        if (x > max[0]) max[0] = x
+        if (y < min[1]) min[1] = y
+        if (y > max[1]) max[1] = y
+        if (z < min[2]) min[2] = z
+        if (z > max[2]) max[2] = z
+    }
+    var ranges = [
+        max[0] - min[0],
+        max[1] - min[1],
+        max[2] - min[2]
+    ]
+    var axis = 0
+    var minRange = ranges[0]
+    for (var j = 1; j < 3; j++) {
+        if (ranges[j] < minRange) {
+            minRange = ranges[j]
+            axis = j
+        }
+    }
+    var epsilon = Math.max(minRange * 0.05, 0.0001)
+    return {
+        axis,
+        strategy: 'positions',
+        min: min[axis],
+        max: max[axis],
+        epsilon,
+        frontSide: 'max'
+    }
+}
+
+function triangleIsFrontFace(i0, i1, i2, positions, normals, axisInfo) {
+    if (!axisInfo) return false
+    var axis = axisInfo.axis || 1
+
+    if (axisInfo.strategy === 'normals' && normals) {
+        var frontSign = axisInfo.frontSign || 1
+        var threshold = 0.5
+        var n0 = normals[i0 * 3 + axis] * frontSign
+        var n1 = normals[i1 * 3 + axis] * frontSign
+        var n2 = normals[i2 * 3 + axis] * frontSign
+        return (n0 > threshold && n1 > threshold && n2 > threshold)
+    }
+
+    if (axisInfo.strategy === 'positions' && positions) {
+        var epsilon = axisInfo.epsilon
+        var limitVal = axisInfo.frontSide === 'min' ? axisInfo.min : axisInfo.max
+        var c0 = positions[i0 * 3 + axis]
+        var c1 = positions[i1 * 3 + axis]
+        var c2 = positions[i2 * 3 + axis]
+        return (
+            Math.abs(c0 - limitVal) < epsilon &&
+            Math.abs(c1 - limitVal) < epsilon &&
+            Math.abs(c2 - limitVal) < epsilon
+        )
+    }
+
+    return false
+}
+
+function createEmptyData() {
+    return {
+        positions: [],
+        normals: [],
+        uvs: [],
+        indices: [],
+        nextIndex: 0
+    }
+}
+
+function appendVertex(target, originalIndex, positions, normals, uvs) {
+    var posOffset = originalIndex * 3
+    var uvOffset = originalIndex * 2
+
+    target.positions.push(
+        positions[posOffset],
+        positions[posOffset + 1],
+        positions[posOffset + 2]
+    )
+    target.normals.push(
+        normals[posOffset],
+        normals[posOffset + 1],
+        normals[posOffset + 2]
+    )
+
+    if (uvs && uvs.length) {
+        target.uvs.push(uvs[uvOffset], uvs[uvOffset + 1])
+    } else {
+        target.uvs.push(0, 0)
+    }
+
+    var newIndex = target.nextIndex
+    target.nextIndex += 1
+    return newIndex
+}
+
+function buildMesh(name, data, scene) {
+    if (!data.positions.length) return null
+    var newMesh = new Mesh(name, scene)
+    var vertexData = new VertexData()
+    vertexData.positions = data.positions
+    vertexData.normals = data.normals
+    vertexData.indices = data.indices
+    vertexData.uvs = data.uvs
+    vertexData.applyToMesh(newMesh, true)
+    newMesh.refreshBoundingInfo()
+    return newMesh
+}

package/src/meshwriter.js

@@ -0,0 +1,303 @@
+/**
+ * MeshWriter Core Class
+ * Main MeshWriter implementation for 3D text rendering in Babylon.js
+ */
+
+import { Vector2 } from './babylonImports.js';
+import { getFont, isFontRegistered } from './fontRegistry.js';
+import {
+    initCSGModule, isCSGReady, getCSGVersion, initializeCSG2,
+    setCSGInitializer, setCSGReadyCheck, onCSGReady, markCSGInitialized
+} from './csg.js';
+import { makeMaterial, makeFaceMaterial, rgb2Color3 } from './material.js';
+import { makeSPS } from './sps.js';
+import { constructLetterPolygons, naturalLetterHeight } from './letterMesh.js';
+import { installCurveExtensions } from './curves.js';
+import {
+    isObject, isNumber, isBoolean, isString, isAmplitude,
+    isPositiveNumber, round, setOption
+} from './utils.js';
+
+/** @typedef {import('@babylonjs/core/scene').Scene} Scene */
+
+/**
+ * @typedef {Object} MeshWriterPreferences
+ * @property {string} [defaultFont] - Default font family
+ * @property {number} [scale=1] - Scale factor
+ * @property {string} [meshOrigin="letterCenter"] - "letterCenter" or "fontOrigin"
+ * @property {boolean} [debug=false] - Enable debug logging
+ * @property {Object} [babylon] - Babylon.js namespace object with CSG classes (for ES module builds)
+ */
+
+// Constants
+const defaultColor = "#808080";
+const defaultOpac = 1;
+
+/**
+ * Create a MeshWriter factory configured for a scene
+ * @param {Scene} scene - Babylon.js scene
+ * @param {MeshWriterPreferences} [preferences={}] - Configuration options
+ * @returns {Function} - MeshWriter constructor
+ */
+export function createMeshWriter(scene, preferences = {}) {
+    // Install curve extensions for Path2
+    installCurveExtensions();
+
+    const defaultFont = isFontRegistered(preferences.defaultFont)
+        ? preferences.defaultFont
+        : (isFontRegistered("Helvetica") ? "Helvetica" : "HelveticaNeue-Medium");
+    const meshOrigin = preferences.meshOrigin === "fontOrigin"
+        ? "fontOrigin"
+        : "letterCenter";
+    const scale = isNumber(preferences.scale) ? preferences.scale : 1;
+    const debug = isBoolean(preferences.debug) ? preferences.debug : false;
+
+    /**
+     * MeshWriter constructor - creates 3D text
+     * @param {string} lttrs - Text to render
+     * @param {Object} opt - Options
+     */
+    function MeshWriter(lttrs, opt) {
+        const options = isObject(opt) ? opt : {};
+        const position = setOption(options, "position", isObject, {});
+        const colors = setOption(options, "colors", isObject, {});
+        const fontFamily = setOption(options, "font-family", isSupportedFont, defaultFont);
+        const anchor = setOption(options, "anchor", isSupportedAnchor, "left");
+        const rawheight = setOption(options, "letter-height", isPositiveNumber, 100);
+        const rawThickness = setOption(options, "letter-thickness", isPositiveNumber, 1);
+        const basicColor = setOption(options, "color", isString, defaultColor);
+        const opac = setOption(options, "alpha", isAmplitude, defaultOpac);
+        const y = setOption(position, "y", isNumber, 0);
+        const x = setOption(position, "x", isNumber, 0);
+        const z = setOption(position, "z", isNumber, 0);
+        const diffuse = setOption(colors, "diffuse", isString, "#404040");    // Dark gray - lets emissive show
+        const specular = setOption(colors, "specular", isString, "#000000");
+        const ambient = setOption(colors, "ambient", isString, "#202020");    // Very dark - minimal ambient response
+        const emissive = setOption(colors, "emissive", isString, basicColor);
+        const emissiveOnly = setOption(options, "emissive-only", isBoolean, false);
+        const fogEnabled = setOption(options, "fog-enabled", isBoolean, true);
+        const letterSpacingRaw = setOption(options, "letter-spacing", isNumber, 0);
+        const wordSpacingRaw = setOption(options, "word-spacing", isNumber, 0);
+        const fontSpec = getFont(fontFamily);
+        const letterScale = round(scale * rawheight / naturalLetterHeight);
+        const thickness = round(scale * rawThickness);
+        const letters = isString(lttrs) ? lttrs : "";
+        // Scale spacing values to match letter scale
+        const letterSpacing = letterSpacingRaw * scale;
+        const wordSpacing = wordSpacingRaw * scale;
+
+        // Create material
+        const material = makeMaterial(scene, letters, emissive, ambient, specular, diffuse, opac, emissiveOnly, fogEnabled);
+
+        // Create letter meshes
+        const meshesAndBoxes = constructLetterPolygons(
+            letters, fontSpec, 0, 0, 0, letterScale, thickness, material, meshOrigin, scene,
+            { letterSpacing, wordSpacing }
+        );
+        const meshes = meshesAndBoxes[0];
+        const lettersBoxes = meshesAndBoxes[1];
+        const lettersOrigins = meshesAndBoxes[2];
+        const xWidth = meshesAndBoxes.xWidth;
+
+        // Convert to SPS
+        const combo = makeSPS(scene, meshesAndBoxes, material);
+        const sps = combo[0];
+        const mesh = combo[1];
+        const faceCombo = combo.face || [];
+        const faceSps = faceCombo[0];
+        const faceMesh = faceCombo[1];
+        let faceMaterial;
+
+        if (faceMesh) {
+            faceMaterial = makeFaceMaterial(scene, letters, emissive, opac, fogEnabled);
+            faceMesh.material = faceMaterial;
+            if (mesh) {
+                faceMesh.parent = mesh;
+                faceMesh.layerMask = mesh.layerMask;
+                faceMesh.renderingGroupId = mesh.renderingGroupId;
+            }
+            // Tiny offset to prevent z-fighting without leaving a visible gap
+            // rotation.x=-PI/2 maps: +Y → -Z (toward camera), -Y → +Z (away)
+            // We want face IN FRONT of rim, so use POSITIVE Y
+            faceMesh.position.y = 0.001;
+            faceMesh.isPickable = false;
+        }
+
+        // Position mesh based on anchor
+        const offsetX = anchor === "right"
+            ? (0 - xWidth)
+            : (anchor === "center" ? (0 - xWidth / 2) : 0);
+
+        if (mesh) {
+            mesh.position.x = scale * x + offsetX;
+            mesh.position.y = scale * y;
+            mesh.position.z = scale * z;
+        }
+
+        // Instance methods
+        let color = basicColor;
+        this.getSPS = () => sps;
+        this.getMesh = () => mesh;
+        this.getMaterial = () => material;
+        this.getFaceMesh = () => faceMesh;
+        this.getFaceMaterial = () => faceMaterial;
+        this.getFaceSPS = () => faceSps;
+        this.getOffsetX = () => offsetX;
+        this.getLettersBoxes = () => lettersBoxes;
+        this.getLettersOrigins = () => lettersOrigins;
+        this.color = c => isString(c) ? color = c : color;
+        this.alpha = o => isAmplitude(o) ? opac : opac;
+        // Track disposed state to prevent double-disposal
+        let _disposed = false;
+
+        this.clearall = function() {
+            // Mark as disposed - getters will return null after this
+            _disposed = true;
+        };
+
+        this.isDisposed = function() {
+            return _disposed;
+        };
+    }
+
+    // Prototype methods
+    MeshWriter.prototype.setColor = function(color) {
+        const material = this.getMaterial();
+        if (material && isString(color)) {
+            const next = rgb2Color3(this.color(color));
+            material.emissiveColor = next;
+            const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+            if (faceMaterial) {
+                faceMaterial.emissiveColor = next;
+            }
+        }
+    };
+
+    MeshWriter.prototype.setAlpha = function(alpha) {
+        const material = this.getMaterial();
+        if (material && isAmplitude(alpha)) {
+            const next = this.alpha(alpha);
+            material.alpha = next;
+            const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+            if (faceMaterial) {
+                faceMaterial.alpha = next;
+            }
+        }
+    };
+
+    MeshWriter.prototype.overrideAlpha = function(alpha) {
+        const material = this.getMaterial();
+        if (material && isAmplitude(alpha)) {
+            material.alpha = alpha;
+            const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+            if (faceMaterial) {
+                faceMaterial.alpha = alpha;
+            }
+        }
+    };
+
+    MeshWriter.prototype.resetAlpha = function() {
+        const material = this.getMaterial();
+        const alpha = this.alpha();
+        if (material) {
+            material.alpha = alpha;
+        }
+        const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+        if (faceMaterial) {
+            faceMaterial.alpha = alpha;
+        }
+    };
+
+    MeshWriter.prototype.getLetterCenter = function(ix) {
+        return new Vector2(0, 0);
+    };
+
+    MeshWriter.prototype.dispose = function() {
+        // Prevent double-disposal
+        if (this.isDisposed && this.isDisposed()) {
+            return;
+        }
+
+        // Dispose TextFogPlugin before materials to break circular references
+        const material = this.getMaterial();
+        if (material) {
+            if (material._textFogPlugin && typeof material._textFogPlugin.dispose === 'function') {
+                material._textFogPlugin.dispose();
+            }
+            material.dispose();
+        }
+
+        const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+        if (faceMaterial) {
+            if (faceMaterial._textFogPlugin && typeof faceMaterial._textFogPlugin.dispose === 'function') {
+                faceMaterial._textFogPlugin.dispose();
+            }
+            faceMaterial.dispose();
+        }
+
+        // Dispose SolidParticleSystem (which also disposes its mesh)
+        const sps = this.getSPS();
+        if (sps) {
+            sps.dispose();
+        }
+
+        // Dispose face mesh (merged mesh, not SPS-based)
+        const faceMesh = this.getFaceMesh && this.getFaceMesh();
+        if (faceMesh && typeof faceMesh.dispose === 'function') {
+            faceMesh.dispose();
+        }
+
+        // Mark as disposed
+        this.clearall();
+    };
+
+    return MeshWriter;
+
+    // Helper functions
+    function isSupportedFont(ff) {
+        return isFontRegistered(ff);
+    }
+
+    function isSupportedAnchor(a) {
+        return a === "left" || a === "right" || a === "center";
+    }
+}
+
+/**
+ * Async factory for Babylon 8+ with CSG2
+ * Handles CSG2 initialization automatically
+ * @param {Scene} scene - Babylon.js scene
+ * @param {MeshWriterPreferences} [preferences={}] - Configuration options
+ * @returns {Promise<Function>} - MeshWriter constructor
+ */
+export async function createMeshWriterAsync(scene, preferences = {}) {
+    // Initialize CSG module with Babylon methods
+    if (preferences.babylon) {
+        initCSGModule(preferences.babylon);
+    } else {
+        // Check for BABYLON global (UMD bundle usage)
+        /** @type {any} */
+        const globalBabylon = typeof globalThis !== 'undefined' ? globalThis.BABYLON : undefined;
+        if (globalBabylon) {
+            initCSGModule(globalBabylon);
+        }
+    }
+
+    // Initialize CSG2 if needed
+    if (getCSGVersion() === 'CSG2' && !isCSGReady()) {
+        await initializeCSG2();
+    }
+
+    return createMeshWriter(scene, preferences);
+}
+
+// Re-export CSG control functions for static API
+export {
+    isCSGReady,
+    getCSGVersion,
+    setCSGInitializer,
+    setCSGReadyCheck,
+    onCSGReady,
+    markCSGInitialized as markCSGReady,
+    initCSGModule
+};