pptx-angular-viewer 1.1.42 → 1.1.43

package/fesm2022/pptx-angular-viewer.mjs

@@ -23966,6 +23966,516 @@ function buildSmartArt3DModel(layout, options = {}) {
     return options.spatial ? applySpatialLayout(model) : model;
 }
 
+/**
+ * Vanilla three.js GLTF/GLB model scene controller (framework-agnostic).
+ *
+ * Mounts an interactive 3D model into a caller-provided container element:
+ * dynamically imports `three` plus its `GLTFLoader` and `OrbitControls` addons,
+ * builds a scene (perspective camera, lights), auto-centres and fits the model
+ * to the view via a `Box3`, renders with a RAF loop, and exposes `resize()` /
+ * `dispose()` for deterministic teardown of GPU resources.
+ *
+ * `three` is an OPTIONAL peer dependency: every import is dynamic and guarded.
+ * When `three` is not installed, {@link mountModel3D} resolves to a sentinel
+ * handle ({@link THREE_UNAVAILABLE}) so the caller can fall back to a poster.
+ * No framework imports - the React, Vue, and Angular bindings can all mount it.
+ */
+/**
+ * Sentinel handle returned when `three` is unavailable or the model fails to
+ * load. All methods are no-ops; `ok` is `false` so callers can show a poster.
+ */
+const THREE_UNAVAILABLE = {
+    ok: false,
+    resize: () => { },
+    setInteractive: () => { },
+    dispose: () => { },
+};
+const FOV$1 = 50;
+/** Dynamically load `three`; returns `null` when the package is not installed. */
+async function loadThree$1() {
+    try {
+        return (await import('three'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Dynamically load the GLTFLoader addon; returns `null` when unavailable. */
+async function loadGltfLoaderCtor() {
+    try {
+        const mod = await import('three/examples/jsm/loaders/GLTFLoader.js');
+        return mod.GLTFLoader;
+    }
+    catch {
+        return null;
+    }
+}
+/** Dynamically load the OrbitControls addon; returns `null` when unavailable. */
+async function loadOrbitControlsCtor$1() {
+    try {
+        const mod = await import('three/examples/jsm/controls/OrbitControls.js');
+        return mod.OrbitControls;
+    }
+    catch {
+        return null;
+    }
+}
+/** Promisified `GLTFLoader.load`. */
+function loadGltf(loader, url) {
+    return new Promise((resolve, reject) => {
+        loader.load(url, resolve, undefined, reject);
+    });
+}
+/**
+ * Auto-centre the model at the origin and uniformly scale it so its largest
+ * dimension fills a 2-unit cube, mirroring the previous react-three-fiber fit.
+ */
+function centerAndFit(three, root) {
+    const box = new three.Box3().setFromObject(root);
+    const size = new three.Vector3();
+    box.getSize(size);
+    const maxDim = Math.max(size.x, size.y, size.z);
+    if (maxDim > 0) {
+        root.scale.setScalar(2 / maxDim);
+    }
+    const center = new three.Vector3();
+    box.getCenter(center);
+    root.position.sub(center.multiplyScalar(root.scale.x));
+}
+/**
+ * Mount an interactive GLTF/GLB model into `container` and start rendering.
+ *
+ * Resolves to {@link THREE_UNAVAILABLE} (a no-op handle with `ok === false`)
+ * when `three` or its addons cannot be loaded, or when the model fails to parse.
+ */
+async function mountModel3D(container, modelUrl, options) {
+    const three = await loadThree$1();
+    const GltfLoaderCtor = three ? await loadGltfLoaderCtor() : null;
+    if (!three || !GltfLoaderCtor) {
+        return THREE_UNAVAILABLE;
+    }
+    const width = Math.max(1, options.width);
+    const height = Math.max(1, options.height);
+    const renderer = new three.WebGLRenderer({ antialias: true, alpha: !options.background });
+    renderer.setPixelRatio(Math.min(typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1, options.maxPixelRatio ?? 2));
+    renderer.setSize(width, height, false);
+    const canvas = renderer.domElement;
+    canvas.style.width = `${width}px`;
+    canvas.style.height = `${height}px`;
+    canvas.style.display = 'block';
+    canvas.style.willChange = 'transform';
+    container.appendChild(canvas);
+    const scene = new three.Scene();
+    if (options.background) {
+        scene.background = new three.Color(options.background);
+    }
+    const camera = new three.PerspectiveCamera(FOV$1, width / height, 0.1, 1000);
+    camera.position.set(0, 0, 5);
+    camera.lookAt(0, 0, 0);
+    scene.add(new three.AmbientLight(0xffffff, 0.5));
+    const key = new three.DirectionalLight(0xffffff, 1);
+    key.position.set(5, 5, 5);
+    scene.add(key);
+    const fill = new three.DirectionalLight(0xffffff, 0.3);
+    fill.position.set(-3, -3, 2);
+    scene.add(fill);
+    let gltf;
+    try {
+        gltf = await loadGltf(new GltfLoaderCtor(), modelUrl);
+    }
+    catch {
+        renderer.dispose();
+        canvas.remove();
+        return THREE_UNAVAILABLE;
+    }
+    const model = gltf.scene;
+    centerAndFit(three, model);
+    scene.add(model);
+    let controls = null;
+    const OrbitCtrlCtor = await loadOrbitControlsCtor$1();
+    const enableControls = (on) => {
+        if (on && !controls && OrbitCtrlCtor) {
+            controls = new OrbitCtrlCtor(camera, canvas);
+            controls.enablePan = false;
+            controls.enableZoom = true;
+            controls.enableRotate = true;
+            controls.minDistance = 2;
+            controls.maxDistance = 20;
+            controls.update();
+        }
+        else if (!on && controls) {
+            controls.dispose();
+            controls = null;
+        }
+    };
+    enableControls(options.interactive ?? true);
+    let frame = 0;
+    let disposed = false;
+    const renderLoop = () => {
+        if (disposed) {
+            return;
+        }
+        frame = requestAnimationFrame(renderLoop);
+        controls?.update();
+        renderer.render(scene, camera);
+    };
+    frame = requestAnimationFrame(renderLoop);
+    /** Recursively dispose every geometry/material/texture under the model. */
+    const disposeModel = () => {
+        model.traverse((obj) => {
+            const mesh = obj;
+            mesh.geometry?.dispose();
+            const material = mesh.material;
+            if (Array.isArray(material)) {
+                for (const m of material) {
+                    m.dispose();
+                }
+            }
+            else {
+                material?.dispose();
+            }
+        });
+    };
+    return {
+        ok: true,
+        resize(w, h) {
+            const nextW = Math.max(1, w);
+            const nextH = Math.max(1, h);
+            camera.aspect = nextW / nextH;
+            camera.updateProjectionMatrix();
+            renderer.setSize(nextW, nextH, false);
+            canvas.style.width = `${nextW}px`;
+            canvas.style.height = `${nextH}px`;
+        },
+        setInteractive(on) {
+            enableControls(on);
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            cancelAnimationFrame(frame);
+            controls?.dispose();
+            disposeModel();
+            scene.clear();
+            renderer.dispose();
+            canvas.remove();
+        },
+    };
+}
+
+/**
+ * Pure surface-chart 3D geometry helpers (framework- and three-agnostic).
+ *
+ * The vanilla three scene controller ({@link mountSurfaceChart3D}) feeds these
+ * the loaded `three` module so the heavy library stays a dynamic, optional
+ * import while the grid maths (plane subdivision -> height/colour displacement,
+ * world-space label anchors) lives here as small, separately testable units.
+ */
+/** Half-unit spacing between adjacent grid points, in world units. */
+const GRID_SPACING = 0.5;
+/** Maximum height displacement (world units) for a normalised value of 1. */
+const MAX_HEIGHT = 1.5;
+/** Compute the world-space width/depth of the data grid. */
+function computeGridExtent(cols, rows) {
+    return {
+        gridWidth: Math.max(cols - 1, 1) * GRID_SPACING,
+        gridDepth: Math.max(rows - 1, 1) * GRID_SPACING,
+    };
+}
+/**
+ * Build the surface mesh + wireframe geometries from the normalised height and
+ * colour maps. The plane is subdivided to match the data grid, rotated into the
+ * XZ plane, then each vertex is displaced in Y by its height and tinted by its
+ * colour. Returns disposable geometries the caller adds to the scene.
+ */
+function buildSurfaceGeometry(three, cols, rows, heightMap, colorMap) {
+    const widthSegs = Math.max(cols - 1, 0);
+    const depthSegs = Math.max(rows - 1, 0);
+    const { gridWidth, gridDepth } = computeGridExtent(cols, rows);
+    const geo = new three.PlaneGeometry(gridWidth, gridDepth, widthSegs, depthSegs);
+    // PlaneGeometry lies in the XY plane by default; rotate it flat into XZ.
+    geo.rotateX(-Math.PI / 2);
+    const pos = geo.attributes.position;
+    const vertexCount = pos.count;
+    const colors = new Float32Array(vertexCount * 3);
+    for (let i = 0; i < vertexCount; i++) {
+        // After the rotation, the (widthSegs+1) x (depthSegs+1) vertices stay in
+        // row-major order, so col = i % cols and row = floor(i / cols) map onto the
+        // data grid directly.
+        const row = Math.floor(i / cols);
+        const col = i % cols;
+        const idx = row * cols + col;
+        const h = idx < heightMap.length ? heightMap[idx] : 0;
+        pos.setY(i, h * MAX_HEIGHT);
+        const ci = idx * 3;
+        colors[i * 3] = ci < colorMap.length ? colorMap[ci] : 0.5;
+        colors[i * 3 + 1] = ci + 1 < colorMap.length ? colorMap[ci + 1] : 0.5;
+        colors[i * 3 + 2] = ci + 2 < colorMap.length ? colorMap[ci + 2] : 0.5;
+    }
+    geo.setAttribute('color', new three.BufferAttribute(colors, 3));
+    geo.computeVertexNormals();
+    pos.needsUpdate = true;
+    const wireGeometry = new three.WireframeGeometry(geo);
+    return { geometry: geo, wireGeometry };
+}
+/**
+ * Build the axis labels (category along the front edge, series along the right
+ * edge, plus a single "Value" Y-axis label) as world-anchored {@link
+ * SurfaceLabel}s. Category/series labels are thinned to at most `maxCat`/`maxSer`
+ * entries to avoid clutter, mirroring the prior drei `Html` layout.
+ */
+function buildSurfaceLabels(cols, rows, categoryLabels, seriesNames, maxCat = 8, maxSer = 6) {
+    const { gridWidth, gridDepth } = computeGridExtent(cols, rows);
+    const labels = [];
+    const catStep = Math.max(1, Math.ceil(categoryLabels.length / maxCat));
+    for (let i = 0; i < categoryLabels.length; i += catStep) {
+        const x = -gridWidth / 2 + (i / Math.max(cols - 1, 1)) * gridWidth;
+        labels.push({
+            key: `cat-${i}`,
+            text: categoryLabels[i],
+            anchor: [x, -0.15, gridDepth / 2 + 0.25],
+            axis: 'category',
+        });
+    }
+    const serStep = Math.max(1, Math.ceil(seriesNames.length / maxSer));
+    for (let i = 0; i < seriesNames.length; i += serStep) {
+        const z = -gridDepth / 2 + (i / Math.max(rows - 1, 1)) * gridDepth;
+        labels.push({
+            key: `ser-${i}`,
+            text: seriesNames[i],
+            anchor: [gridWidth / 2 + 0.3, -0.15, z],
+            axis: 'series',
+        });
+    }
+    labels.push({
+        key: 'value-axis',
+        text: 'Value',
+        anchor: [-gridWidth / 2 - 0.35, 0.75, -gridDepth / 2],
+        axis: 'value',
+    });
+    return labels;
+}
+/** Isometric-like camera placement that frames the whole grid. */
+function computeCameraPlacement(cols, rows) {
+    const { gridWidth, gridDepth } = computeGridExtent(cols, rows);
+    const maxExtent = Math.max(gridWidth, gridDepth, MAX_HEIGHT);
+    const dist = maxExtent * 1.8;
+    return {
+        position: [dist * 0.8, dist * 0.7, dist * 0.8],
+        target: [0, 0.3, 0],
+    };
+}
+
+/**
+ * Vanilla three.js 3D surface-chart scene controller (framework-agnostic).
+ *
+ * Mounts an interactive surface chart into a caller-provided container element:
+ * dynamically imports `three` plus its `OrbitControls` addon, builds a colour-
+ * displaced surface mesh (with optional wireframe), grid floor, lights, and an
+ * isometric camera, renders with a RAF loop, and overlays axis labels as DOM
+ * nodes that are re-projected to screen each frame. Exposes `dispose()` for
+ * deterministic teardown of GPU resources, listeners, and overlay nodes.
+ *
+ * `three` is an OPTIONAL peer dependency: every import is dynamic and guarded.
+ * When `three` (or its OrbitControls addon) is missing, {@link mountSurfaceChart3D}
+ * resolves to a sentinel handle ({@link SURFACE_THREE_UNAVAILABLE}) so the caller
+ * can fall back to the 2D renderer. No framework imports - React, Vue, and
+ * Angular bindings can all mount it.
+ */
+/** No-op sentinel returned when `three` or its OrbitControls addon is missing. */
+const SURFACE_THREE_UNAVAILABLE = {
+    ok: false,
+    resize: () => { },
+    dispose: () => { },
+};
+const FOV = 45;
+/** Dynamically load `three`; returns `null` when the package is not installed. */
+async function loadThree() {
+    try {
+        return (await import('three'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Dynamically load the OrbitControls addon; returns `null` when unavailable. */
+async function loadOrbitControlsCtor() {
+    try {
+        const mod = await import('three/examples/jsm/controls/OrbitControls.js');
+        return mod.OrbitControls;
+    }
+    catch {
+        return null;
+    }
+}
+/** Create the DOM overlay nodes for the axis labels, returned with the layer. */
+function createLabelOverlay(doc, labels) {
+    const layer = doc.createElement('div');
+    Object.assign(layer.style, {
+        position: 'absolute',
+        inset: '0',
+        pointerEvents: 'none',
+        overflow: 'hidden',
+    });
+    const nodes = labels.map((label) => {
+        const node = doc.createElement('div');
+        node.textContent = label.text;
+        const color = label.axis === 'value' ? '#999' : '#666';
+        Object.assign(node.style, {
+            position: 'absolute',
+            fontSize: '9px',
+            color,
+            whiteSpace: 'nowrap',
+            userSelect: 'none',
+            transform: 'translate(-50%, -50%)',
+            willChange: 'left, top',
+        });
+        if (label.axis === 'value') {
+            node.style.writingMode = 'vertical-rl';
+        }
+        layer.appendChild(node);
+        return node;
+    });
+    return { layer, nodes };
+}
+/**
+ * Mount an interactive 3D surface chart into `container` and start rendering.
+ *
+ * Resolves to {@link SURFACE_THREE_UNAVAILABLE} when `three` or its OrbitControls
+ * addon cannot be loaded, so the caller can fall back to a 2D surface renderer.
+ */
+async function mountSurfaceChart3D(container, options) {
+    const three = await loadThree();
+    const OrbitCtrlCtor = three ? await loadOrbitControlsCtor() : null;
+    if (!three || !OrbitCtrlCtor) {
+        return SURFACE_THREE_UNAVAILABLE;
+    }
+    const { cols, rows } = options;
+    let width = Math.max(1, options.width);
+    let height = Math.max(1, options.height);
+    const renderer = new three.WebGLRenderer({ antialias: true, alpha: true });
+    renderer.setPixelRatio(Math.min(typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1, options.maxPixelRatio ?? 2));
+    renderer.setSize(width, height, false);
+    const canvas = renderer.domElement;
+    canvas.style.width = `${width}px`;
+    canvas.style.height = `${height}px`;
+    canvas.style.display = 'block';
+    canvas.style.willChange = 'transform';
+    container.appendChild(canvas);
+    const scene = new three.Scene();
+    scene.add(new three.AmbientLight(0xffffff, 0.6));
+    const key = new three.DirectionalLight(0xffffff, 0.8);
+    key.position.set(5, 8, 5);
+    scene.add(key);
+    const fill = new three.DirectionalLight(0xffffff, 0.3);
+    fill.position.set(-3, 4, -2);
+    scene.add(fill);
+    const camera = new three.PerspectiveCamera(FOV, width / height, 0.1, 1000);
+    const placement = computeCameraPlacement(cols, rows);
+    camera.position.set(...placement.position);
+    const target = new three.Vector3(...placement.target);
+    camera.lookAt(target);
+    // Grid floor under the surface.
+    const { gridWidth, gridDepth } = computeGridExtent(cols, rows);
+    const floorSize = Math.max(gridWidth, gridDepth) * 1.2;
+    const gridFloor = new three.GridHelper(floorSize, Math.max(cols, rows), 0xcccccc, 0xe8e8e8);
+    gridFloor.position.y = -0.02;
+    scene.add(gridFloor);
+    // Surface mesh + optional wireframe.
+    const { geometry, wireGeometry } = buildSurfaceGeometry(three, cols, rows, options.heightMap, options.colorMap);
+    const surfaceMaterial = new three.MeshPhongMaterial({
+        vertexColors: true,
+        side: three.DoubleSide,
+        shininess: 30,
+        transparent: true,
+        opacity: 0.92,
+    });
+    const surfaceMesh = new three.Mesh(geometry, surfaceMaterial);
+    scene.add(surfaceMesh);
+    let wireMaterial = null;
+    if (options.wireframe) {
+        wireMaterial = new three.LineBasicMaterial({
+            color: 0x333333,
+            transparent: true,
+            opacity: 0.25,
+        });
+        scene.add(new three.LineSegments(wireGeometry, wireMaterial));
+    }
+    const controls = new OrbitCtrlCtor(camera, canvas);
+    controls.enablePan = true;
+    controls.enableZoom = true;
+    controls.enableRotate = true;
+    controls.minDistance = 1;
+    controls.maxDistance = 20;
+    controls.maxPolarAngle = Math.PI / 2 + 0.3;
+    controls.target.copy(target);
+    controls.update();
+    // Axis-label DOM overlay, re-projected to screen each frame.
+    const doc = container.ownerDocument ?? document;
+    const labels = buildSurfaceLabels(cols, rows, options.categoryLabels, options.seriesNames);
+    const { layer, nodes } = createLabelOverlay(doc, labels);
+    container.appendChild(layer);
+    const anchors = labels.map((l) => new three.Vector3(...l.anchor));
+    const projected = new three.Vector3();
+    const updateLabels = () => {
+        for (let i = 0; i < nodes.length; i++) {
+            projected.copy(anchors[i]).project(camera);
+            const node = nodes[i];
+            // Hide labels behind the camera.
+            if (projected.z > 1) {
+                node.style.display = 'none';
+                continue;
+            }
+            node.style.display = '';
+            node.style.left = `${((projected.x + 1) / 2) * width}px`;
+            node.style.top = `${((-projected.y + 1) / 2) * height}px`;
+        }
+    };
+    let frame = 0;
+    let disposed = false;
+    const renderLoop = () => {
+        if (disposed) {
+            return;
+        }
+        frame = requestAnimationFrame(renderLoop);
+        controls.update();
+        renderer.render(scene, camera);
+        updateLabels();
+    };
+    frame = requestAnimationFrame(renderLoop);
+    return {
+        ok: true,
+        resize(w, h) {
+            width = Math.max(1, w);
+            height = Math.max(1, h);
+            camera.aspect = width / height;
+            camera.updateProjectionMatrix();
+            renderer.setSize(width, height, false);
+            canvas.style.width = `${width}px`;
+            canvas.style.height = `${height}px`;
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            cancelAnimationFrame(frame);
+            controls.dispose();
+            geometry.dispose();
+            wireGeometry.dispose();
+            surfaceMaterial.dispose();
+            wireMaterial?.dispose();
+            gridFloor.dispose();
+            scene.clear();
+            renderer.dispose();
+            canvas.remove();
+            layer.remove();
+        },
+    };
+}
+
 /**
  * smartart-drawing.ts: Drawing-shape view-model helpers for the SmartArt
  * renderer, shared across the React, Vue, and Angular bindings.