simview 3.2__py3-none-any.whl

simview/static/js/objects/StaticObject.js

@@ -0,0 +1,181 @@
+import * as THREE from "three";
+import { STATIC_OBJECT_CONFIG } from "../config.js"; // Assuming this exists
+import {
+    createGeometry,
+    createMesh,
+    createPoints,
+    createWireframe,
+} from "./utils.js";
+
+export class StaticObject {
+    constructor(objectData, app) {
+        this.app = app;
+        this.name = objectData.name;
+        this.isSingleton = objectData.isSingleton || false; // Default to false if not specified
+        this.batchSize = app.batchManager.simBatches;
+        this.representations = { mesh: [], wireframe: [], points: [] }; // For visualization modes
+        this.batchGroups = []; // Store batch groups
+
+        // Validate input data
+        if (this.isSingleton) {
+            if (!objectData.shape || !objectData.shape.type) {
+                throw new Error(
+                    "Singleton static object requires a 'shape' definition."
+                );
+            }
+            this.type = objectData.shape.type;
+        } else {
+            if (
+                !Array.isArray(objectData.shapes) ||
+                objectData.shapes.length !== this.batchSize
+            ) {
+                throw new Error(
+                    `Batched static object requires a 'shapes' array of length ${this.batchSize}.`
+                );
+            }
+            this.type = objectData.shapes[0].type; // Assume consistent types for simplicity
+        }
+
+        // Initialize and create visual objects
+        this.initializeGroup();
+        this.createBatchGroups(objectData);
+    }
+
+    /** Initialize the main Three.js group */
+    initializeGroup() {
+        this.group = new THREE.Group();
+        this.group.name = this.name;
+    }
+
+    createBatchGroups(objectData) {
+        const geometryConfig = STATIC_OBJECT_CONFIG.geometry || {};
+
+        if (this.isSingleton) {
+            const shape = objectData.shape;
+            const meshConfig = {
+                ...STATIC_OBJECT_CONFIG.mesh,
+                color: shape.color || STATIC_OBJECT_CONFIG.color || 0xffffff,
+            };
+            const pointsConfig = {
+                ...STATIC_OBJECT_CONFIG.points,
+                color: shape.color || STATIC_OBJECT_CONFIG.color || 0xffffff,
+            };
+
+            if (shape.type === "pointcloud") {
+                for (let i = 0; i < this.batchSize; i++) {
+                    const points = createPoints(shape.points, pointsConfig);
+                    if (points) {
+                        points.visible = this.app.uiState.bodyVisualizationMode === "points";
+                        const offset = this.app.batchManager.getBatchOffset(i);
+                        points.position.set(offset.x, offset.y, offset.z);
+                        this.group.add(points);
+                        this.representations["points"].push(points);
+                    }
+                }
+            } else {
+                const geometry = createGeometry(shape, geometryConfig);
+                const meshMaterial = createMesh(geometry, meshConfig).material;
+                const wireframeMaterial = new THREE.MeshBasicMaterial({
+                    color: STATIC_OBJECT_CONFIG.wireframe?.color || 0x4080ff,
+                    wireframe: true,
+                    transparent: true,
+                    opacity: 0.2
+                });
+
+                const instancedMesh = new THREE.InstancedMesh(geometry, meshMaterial, this.batchSize);
+                const instancedWireframe = new THREE.InstancedMesh(geometry, wireframeMaterial, this.batchSize);
+
+                for (let i = 0; i < this.batchSize; i++) {
+                    const offset = this.app.batchManager.getBatchOffset(i);
+                    const matrix = new THREE.Matrix4().makeTranslation(offset.x, offset.y, offset.z);
+                    instancedMesh.setMatrixAt(i, matrix);
+                    instancedWireframe.setMatrixAt(i, matrix);
+                }
+
+                instancedMesh.visible = this.app.uiState.bodyVisualizationMode === "mesh";
+                instancedWireframe.visible = this.app.uiState.bodyVisualizationMode === "wireframe";
+
+                this.group.add(instancedMesh);
+                this.group.add(instancedWireframe);
+
+                this.representations["mesh"] = instancedMesh;
+                this.representations["wireframe"] = instancedWireframe;
+            }
+        } else {
+            // Non-singleton: reuse geometry if possible (if all shapes are same type and same dimensions)
+            // For now, keep as is but optimize material/geometry creation if they are identical
+            for (let i = 0; i < this.batchSize; i++) {
+                const batchGroup = new THREE.Group();
+                batchGroup.name = `${this.name}_batch_${i}`;
+                this.group.add(batchGroup);
+                this.batchGroups.push(batchGroup);
+
+                const shape = objectData.shapes[i];
+                const meshConfig = {
+                    ...STATIC_OBJECT_CONFIG.mesh,
+                    color: shape.color || STATIC_OBJECT_CONFIG.color || 0xffffff,
+                };
+                const pointsConfig = {
+                    ...STATIC_OBJECT_CONFIG.points,
+                    color: shape.color || STATIC_OBJECT_CONFIG.color || 0xffffff,
+                };
+
+                if (shape.type === "pointcloud") {
+                    const points = createPoints(shape.points, pointsConfig);
+                    if (points) {
+                        points.visible = this.app.uiState.bodyVisualizationMode === "points";
+                        batchGroup.add(points);
+                        this.representations["points"].push(points);
+                    }
+                } else {
+                    const geometry = createGeometry(shape, geometryConfig);
+                    const mesh = createMesh(geometry, meshConfig);
+                    mesh.visible = this.app.uiState.bodyVisualizationMode === "mesh";
+                    batchGroup.add(mesh);
+                    this.representations["mesh"].push(mesh);
+                    const wireframe = createWireframe(geometry, STATIC_OBJECT_CONFIG.wireframe);
+                    wireframe.visible = this.app.uiState.bodyVisualizationMode === "wireframe";
+                    batchGroup.add(wireframe);
+                    this.representations["wireframe"].push(wireframe);
+                }
+
+                const offset = this.app.batchManager.getBatchOffset(i);
+                batchGroup.position.set(offset.x, offset.y, offset.z);
+            }
+        }
+    }
+
+    /** Update visualization mode (mesh, wireframe, points) */
+    updateVisualizationMode(mode) {
+        for (const [type, obj] of Object.entries(this.representations)) {
+            if (obj instanceof THREE.InstancedMesh) {
+                obj.visible = type === mode;
+            } else if (Array.isArray(obj)) {
+                obj.forEach((o) => (o.visible = type === mode));
+            }
+        }
+    }
+
+    /** Return the Three.js group for scene integration */
+    getObject3D() {
+        return this.group;
+    }
+
+    /** Clean up resources */
+    dispose() {
+        if (this.group) {
+            if (
+                this.app.scene &&
+                typeof this.app.scene.removeObject3D === "function"
+            ) {
+                this.app.scene.removeObject3D(this.group);
+            } else if (this.group.parent) {
+                this.group.parent.remove(this.group);
+            }
+
+            this.group = null;
+            this.representations = { mesh: [], wireframe: [], points: [] };
+            this.batchGroups = [];
+        }
+    }
+}

simview/static/js/objects/Terrain.js

@@ -0,0 +1,514 @@
+import * as THREE from "three";
+import { TERRAIN_CONFIG } from "../config.js";
+import { colorMapOptions, evaluate_cmap } from "../../lib/js-colormaps.js";
+
+export class Terrain {
+    constructor(terrainData, app) {
+        this.app = app; // Store reference to app for accessing batch manager
+        this.bounds = terrainData.bounds;
+        this.dimensions = terrainData.dimensions;
+        this.group = null;
+
+        this.heightData = this.#normalizeScalarField(terrainData.heightData, true);
+        this.frictionData = this.#normalizeScalarField(terrainData.frictionData);
+        this.stiffnessData = this.#normalizeScalarField(terrainData.stiffnessData);
+        this.isSingleton = terrainData.isSingleton;
+
+        const normals = this.#normalizeNormals(terrainData.normals);
+
+        this.#createVisualRepresentations(this.heightData, normals);
+    }
+
+    // Reshapes a flat Float32Array of `batchSize` concatenated per-vertex
+    // records (`width` floats each) into one subarray view per batch.
+    #splitIntoBatches(flatArray, width) {
+        const batchSize = this.app.batchManager.simBatches;
+        const resolution = this.dimensions.resolutionX * this.dimensions.resolutionY;
+        const perBatch = resolution * width;
+        const batches = [];
+        for (let i = 0; i < batchSize; i++) {
+            batches.push(flatArray.subarray(i * perBatch, (i + 1) * perBatch));
+        }
+        return batches;
+    }
+
+    // Normalizes a per-vertex scalar terrain field (heightData/frictionData/
+    // stiffnessData) to an array of one entry per batch. Passes through
+    // unchanged if already batched, or if absent (friction/stiffness are
+    // optional).
+    #normalizeScalarField(data, logNormalization = false) {
+        if (data instanceof Float32Array) {
+            return this.#splitIntoBatches(data, 1);
+        }
+        if (Array.isArray(data) && data.length > 0 && typeof data[0] === "number") {
+            if (logNormalization) {
+                console.debug("Normalizing flat heightData to single batch");
+            }
+            return [data];
+        }
+        return data;
+    }
+
+    // Normalizes terrain normals (per-vertex 3-vectors) to an array of one
+    // batch of vectors.
+    #normalizeNormals(data) {
+        if (data instanceof Float32Array) {
+            return this.#splitIntoBatches(data, 3);
+        }
+        if (Array.isArray(data) && data.length > 0) {
+            if (typeof data[0] === "number") {
+                // Case: Flat array [x, y, z, x, y, z...]
+                console.debug("Normalizing flat normals array to single batch of vectors");
+                const vectors = [];
+                for (let i = 0; i < data.length; i += 3) {
+                    vectors.push([data[i], data[i + 1], data[i + 2]]);
+                }
+                return [vectors];
+            }
+            if (
+                Array.isArray(data[0]) &&
+                data[0].length > 0 &&
+                typeof data[0][0] === "number"
+            ) {
+                // Case: Array of vectors [[x,y,z], ...] -> Wrap in batch
+                console.debug("Normalizing list of normal vectors to single batch");
+                return [data];
+            }
+        }
+        return data;
+    }
+
+    #createMaterials() {
+        // Create materials for the surface and wireframe
+        const surfaceMaterial = new THREE.MeshPhongMaterial({
+            vertexColors: true,
+            side: THREE.DoubleSide,
+            flatShading: TERRAIN_CONFIG.flatShading || false,
+            shininess: TERRAIN_CONFIG.shininess || 10,
+        });
+
+        const wireframeMaterial = new THREE.MeshBasicMaterial({
+            color: 0xffffff,
+            wireframe: true,
+            opacity: 0.2,
+            transparent: true,
+        });
+
+        return { surfaceMaterial, wireframeMaterial };
+    }
+
+    #createVisualRepresentations(heightData, normals) {
+        console.debug(
+            `Creating terrain geometry: ${this.dimensions.sizeX}x${this.dimensions.sizeY} m, resolution: ${this.dimensions.resolutionX}x${this.dimensions.resolutionY}`
+        );
+        const { surfaceMaterial, wireframeMaterial } = this.#createMaterials();
+
+        let singletonSurfaceGeometry = null;
+        let singletonNormals = null;
+
+        if (this.isSingleton) {
+            singletonSurfaceGeometry = this.#createSurfaceGeometryFromHeightData(
+                heightData[0],
+                0
+            );
+            singletonNormals = this.#createNormalVectors(
+                heightData[0],
+                normals[0]
+            );
+        }
+
+        // Create geometry for each batch
+        this.group = new THREE.Group();
+        for (let i = 0; i < this.app.batchManager.simBatches; i++) {
+            const batchGroup = new THREE.Group();
+            batchGroup.name = `batch${i}`;
+
+            const surfaceGeometry = this.isSingleton
+                ? singletonSurfaceGeometry
+                : this.#createSurfaceGeometryFromHeightData(heightData[i], i);
+
+            const surfaceMesh = new THREE.Mesh(surfaceGeometry, surfaceMaterial);
+            surfaceMesh.name = "surface";
+            surfaceMesh.receiveShadow = true;
+            surfaceMesh.castShadow = true;
+            batchGroup.add(surfaceMesh);
+
+            const wireframeMesh = new THREE.Mesh(surfaceGeometry, wireframeMaterial);
+            wireframeMesh.name = "wireframe";
+            batchGroup.add(wireframeMesh);
+
+            const surfaceNormals = this.isSingleton
+                ? singletonNormals.clone()
+                : this.#createNormalVectors(heightData[i], normals[i]);
+
+            surfaceNormals.name = "normals";
+            batchGroup.add(surfaceNormals);
+
+            for (const [key, value] of Object.entries(
+                this.app.uiState.terrainVisualizationModes
+            )) {
+                const obj = batchGroup.getObjectByName(key);
+                if (obj) obj.visible = value;
+            }
+            // translate by the batch offset
+            const batch_offset = this.app.batchManager.getBatchOffset(i);
+            batchGroup.position.set(batch_offset.x, batch_offset.y, batch_offset.z);
+            this.group.add(batchGroup);
+        }
+    }
+
+    // Normalize a value into [0, 1] against an explicit [min, max] range.
+    // Falls back to [0, 1] clamping when the range is missing or degenerate.
+    #normalizeToRange(value, min, max) {
+        if (
+            typeof min !== "number" ||
+            typeof max !== "number" ||
+            max - min === 0
+        ) {
+            return Math.max(0, Math.min(1, value));
+        }
+        const normalized = (value - min) / (max - min);
+        return Math.max(0, Math.min(1, normalized));
+    }
+
+    calculateNormalizedHeight(height) {
+        var normalizedHeight =
+            (height - this.bounds.minZ) / (this.bounds.maxZ - this.bounds.minZ);
+        normalizedHeight = Number.isFinite(normalizedHeight) ? normalizedHeight : 0;
+        normalizedHeight = Math.max(0, Math.min(1, normalizedHeight));
+        return normalizedHeight;
+    }
+
+    /**
+     *
+     * @param {array} heightData - Height data for the terrain, a flattened array
+     * @returns
+     */
+    #createSurfaceGeometryFromHeightData(heightData, batchIndex) {
+        const { sizeX, sizeY, resolutionX, resolutionY } = this.dimensions;
+        const { minX, minY, maxX, maxY } = this.bounds;
+        // Create a plane geometry with the right number of segments
+        const geometry = new THREE.PlaneGeometry(
+            sizeX,
+            sizeY,
+            resolutionX - 1,
+            resolutionY - 1
+        );
+        // Center the geometry based on bounds
+        const centerX = (minX + maxX) / 2;
+        const centerY = (minY + maxY) / 2;
+        geometry.translate(centerX, centerY, 0);
+        // Get attributes for direct manipulation
+        const position = geometry.attributes.position;
+        // Create color buffer
+        const colorAttribute = new THREE.BufferAttribute(
+            new Float32Array(position.count * 3),
+            3
+        );
+        geometry.setAttribute("color", colorAttribute);
+
+        // Apply height data to geometry
+        // NOTE: THREE.js PlaneGeometry vertices are arranged in rows from bottom to top (Y increases)
+        const callableColormap = this.getCallableFromColorMapName(
+            this.app.uiState.terrainColorMap
+        );
+
+        for (let i = 0; i < position.count; i++) {
+            // Convert vertex index to grid coordinates
+            const col = i % resolutionX;
+            const invertedRow = Math.floor(i / resolutionX);
+            const row = resolutionY - invertedRow - 1; // Invert row index
+            // Calculate index in the flattened height data array
+            const dataIndex = row * resolutionX + col;
+            // Set Z coordinate (height)
+            position.setZ(i, heightData[dataIndex]);
+        }
+
+        // Apply colors
+        this.#updateSurfaceColor(batchIndex, geometry, callableColormap);
+
+        // Make sure changes are applied
+        position.needsUpdate = true;
+        return geometry;
+    }
+
+    getCallableFromColorMapName(cmapName) {
+        let reversed = false;
+        // Check if this is a reversed colormap request
+        if (cmapName.endsWith("_r")) {
+            cmapName = cmapName.substring(0, cmapName.length - 2);
+            reversed = true;
+        }
+        if (colorMapOptions.includes(cmapName))
+            return (value) => {
+                const [r, g, b] = evaluate_cmap(value, cmapName, reversed);
+                return new THREE.Color(r / 255, g / 255, b / 255);
+            };
+        console.log(
+            `Colormap ${cmapName} not found in colorMapOptions. Using default colormap instead.`
+        );
+        // Fallback
+        switch (cmapName) {
+            case "grayscale":
+                return (value) => new THREE.Color(value, value, value);
+            case "heatmap":
+                // Simple heatmap: blue->cyan->green->yellow->red
+                return (value) => {
+                    if (value < 0.25) {
+                        return new THREE.Color(0, value * 4, 1);
+                    } else if (value < 0.5) {
+                        return new THREE.Color(0, 1, 1 - (value - 0.25) * 4);
+                    } else if (value < 0.75) {
+                        return new THREE.Color((value - 0.5) * 4, 1, 0);
+                    } else {
+                        return new THREE.Color(1, 1 - (value - 0.75) * 4, 0);
+                    }
+                };
+            case "terrain":
+                // Terrain color map - blues for low areas, greens for middle, browns/whites for high
+                return (value) => {
+                    if (value < 0.2) {
+                        return new THREE.Color(0.0, 0.2, 0.5 + value); // Deep to shallow water
+                    } else if (value < 0.4) {
+                        const t = (value - 0.2) * 5; // 0-1 within this range
+                        return new THREE.Color(0.2 * t, 0.5 + 0.2 * t, 0.7 - 0.2 * t); // Shore transition
+                    } else if (value < 0.75) {
+                        const t = (value - 0.4) / 0.35; // 0-1 within this range
+                        return new THREE.Color(0.2 + 0.3 * t, 0.7 - 0.2 * t, 0.5 - 0.4 * t); // Green to brown
+                    } else {
+                        const t = (value - 0.75) * 4; // 0-1 within this range
+                        return new THREE.Color(0.5 + 0.5 * t, 0.5 + 0.5 * t, 0.1 + 0.9 * t); // Brown to white (snow)
+                    }
+                };
+            default:
+                // Default blue to red gradient
+                return (value) => new THREE.Color(value, 0.2, 1 - value);
+        }
+    }
+
+    /**
+     *
+     * @param {array} heightData - Height data for the terrain, a flattened array
+     * @param {array} normals - Normal data for the terrain, an array of 3D vectors
+     * @returns {THREE.Group} - Group containing normal vectors
+     */
+    #createNormalVectors(heightData, normals) {
+        const { sizeX, sizeY, resolutionX, resolutionY } = this.dimensions;
+        const { minX, minY } = this.bounds;
+
+        const normalVectors = new THREE.Group();
+        normalVectors.visible =
+            this.app.uiState.terrainVisualizationModes.normals || false;
+
+        // Create a helper arrow for each normal
+        const normalLength = TERRAIN_CONFIG.normalLength || 0.5;
+        const skipFactor = Math.max(
+            1,
+            Math.floor(resolutionX / TERRAIN_CONFIG.skipNormalCells)
+        ); // Adaptive skip factor based on resolution
+
+        // Sample normals at regular intervals
+        for (let row = 0; row < resolutionY; row += skipFactor) {
+            for (let col = 0; col < resolutionX; col += skipFactor) {
+                const dataIndex = row * resolutionX + col;
+
+                if (dataIndex < heightData.length) {
+                    // Calculate real-world coordinates
+                    const x = minX + col * (sizeX / (resolutionX - 1));
+                    const y = minY + row * (sizeY / (resolutionY - 1));
+                    const z = heightData[dataIndex];
+
+                    // Get normal data
+                    let nx, ny, nz;
+                    if (normals instanceof Float32Array) {
+                        nx = normals[dataIndex * 3];
+                        ny = normals[dataIndex * 3 + 1];
+                        nz = normals[dataIndex * 3 + 2];
+                    } else {
+                        [nx, ny, nz] = normals[dataIndex];
+                    }
+
+                    const origin = new THREE.Vector3(x, y, z);
+                    const direction = new THREE.Vector3(nx, ny, nz);
+
+                    const arrowHelper = new THREE.ArrowHelper(
+                        direction.normalize(),
+                        origin,
+                        normalLength,
+                        0xff0000
+                    );
+
+                    normalVectors.add(arrowHelper);
+                }
+            }
+        }
+        return normalVectors;
+    }
+
+    // Toggle methods for visualizations - now updated to support batched terrains
+    toggleVisualization(type, visible) {
+        // Toggle in the original terrain
+        for (const batchGroup of this.group.children) {
+            const object = batchGroup.getObjectByName(type);
+            if (object) {
+                object.visible = visible;
+            }
+        }
+    }
+
+    #updateSurfaceColor(batchIndex, geometry, callableColormap) {
+        if (!geometry) return;
+        const position = geometry.attributes.position;
+        const colorAttribute = geometry.attributes.color;
+        if (!position || !colorAttribute) return;
+
+        const { resolutionX, resolutionY } = this.dimensions;
+        const mode = this.app.uiState.terrainColorMode || "height";
+
+        // Update all colors based on the new colormap
+        for (let i = 0; i < position.count; i++) {
+            let value;
+            if (mode === "height") {
+                value = this.calculateNormalizedHeight(position.getZ(i));
+            } else {
+                const col = i % resolutionX;
+                const invertedRow = Math.floor(i / resolutionX);
+                const row = resolutionY - invertedRow - 1;
+                const dataIndex = row * resolutionX + col;
+
+                if (mode === "friction" && this.frictionData && this.frictionData[batchIndex]) {
+                    // Normalize against the data range shipped in bounds (falls back to [0, 1]).
+                    value = this.#normalizeToRange(
+                        this.frictionData[batchIndex][dataIndex],
+                        this.bounds.minFriction,
+                        this.bounds.maxFriction
+                    );
+                } else if (mode === "stiffness" && this.stiffnessData && this.stiffnessData[batchIndex]) {
+                    // Normalize against the data range shipped in bounds (falls back to [0, 1]).
+                    value = this.#normalizeToRange(
+                        this.stiffnessData[batchIndex][dataIndex],
+                        this.bounds.minStiffness,
+                        this.bounds.maxStiffness
+                    );
+                } else {
+                    value = this.calculateNormalizedHeight(position.getZ(i));
+                }
+            }
+            const color = callableColormap(value);
+            colorAttribute.setXYZ(i, color.r, color.g, color.b);
+        }
+        // Update the buffer
+        colorAttribute.needsUpdate = true;
+    }
+
+    // Update terrain colors with current colormap
+    setColorMap(colormapName) {
+        // Update the main terrain surface
+        const callableColormap = this.getCallableFromColorMapName(colormapName);
+        const batchesToUpdate = this.isSingleton ? 1 : this.app.batchManager.simBatches;
+
+        for (let i = 0; i < batchesToUpdate; i++) {
+            const batchGroup = this.group.getObjectByName(`batch${i}`);
+            const surfaceMesh = batchGroup.getObjectByName("surface");
+            const geometry = surfaceMesh.geometry;
+            this.#updateSurfaceColor(i, geometry, callableColormap);
+        }
+    }
+
+    // Update terrain colors with current mode
+    setColorMode(mode) {
+        const callableColormap = this.getCallableFromColorMapName(this.app.uiState.terrainColorMap);
+        const batchesToUpdate = this.isSingleton ? 1 : this.app.batchManager.simBatches;
+
+        for (let i = 0; i < batchesToUpdate; i++) {
+            const batchGroup = this.group.getObjectByName(`batch${i}`);
+            const surfaceMesh = batchGroup.getObjectByName("surface");
+            const geometry = surfaceMesh.geometry;
+            this.#updateSurfaceColor(i, geometry, callableColormap);
+        }
+    }
+
+    getAvailableColorModes() {
+        const modes = [];
+        if (this.heightData && this.heightData.length > 0) {
+            modes.push("height");
+        }
+        if (this.frictionData && this.frictionData.length > 0) {
+            modes.push("friction");
+        }
+        if (this.stiffnessData && this.stiffnessData.length > 0) {
+            modes.push("stiffness");
+        }
+        return modes;
+    }
+
+    getPropertiesAt(x, y, batchIndex) {
+        const batchOffset = this.app.batchManager.getBatchOffset(batchIndex);
+        const localX = x - batchOffset.x;
+        const localY = y - batchOffset.y;
+
+        const { sizeX, sizeY, resolutionX, resolutionY } = this.dimensions;
+        const { minX, minY, maxX, maxY } = this.bounds;
+
+        if (localX < minX || localX > maxX || localY < minY || localY > maxY) {
+            return null;
+        }
+
+        const col = Math.round(((localX - minX) / sizeX) * (resolutionX - 1));
+        const row = Math.round(((localY - minY) / sizeY) * (resolutionY - 1));
+
+        if (col < 0 || col >= resolutionX || row < 0 || row >= resolutionY) return null;
+
+        const dataIndex = row * resolutionX + col;
+        const props = {};
+        
+        const dataBatchIndex = this.isSingleton ? 0 : batchIndex;
+
+        if (this.heightData && this.heightData[dataBatchIndex]) {
+            props.height = this.heightData[dataBatchIndex][dataIndex];
+        } else {
+            return null;
+        }
+
+        if (this.frictionData && this.frictionData[dataBatchIndex]) {
+            props.friction = this.frictionData[dataBatchIndex][dataIndex];
+        }
+        
+        if (this.stiffnessData && this.stiffnessData[dataBatchIndex]) {
+            props.stiffness = this.stiffnessData[dataBatchIndex][dataIndex];
+        }
+
+        return props;
+    }
+
+    // Get THREE.js group containing all visualizations
+    getObject3D() {
+        return this.group;
+    }
+
+    // Clean up resources when terrain is no longer needed
+    dispose() {
+        const geometries = new Set();
+        const materials = new Set();
+
+        for (const batchGroup of this.group.children) {
+            batchGroup.traverse((child) => {
+                if (child.geometry) geometries.add(child.geometry);
+                if (child.material) {
+                    if (Array.isArray(child.material)) {
+                        child.material.forEach((m) => materials.add(m));
+                    } else {
+                        materials.add(child.material);
+                    }
+                }
+            });
+            if (this.app && this.app.scene) {
+                this.app.scene.removeObject3D(batchGroup);
+            }
+        }
+
+        geometries.forEach((g) => g.dispose());
+        materials.forEach((m) => m.dispose());
+        this.group = null;
+    }
+}