feat:3D multi dot

test/onlygl/README.md

@@ -26,3 +26,86 @@ make -j
 ```
 
 目前用 `update_demo_values` 生成简单波纹示例数据，如需接入传感器数据，替换 main.cpp 里的该函数并在循环前设置好 `set_spec` / `set_panel_size`。
+
+## Heatmap Demo (Heightmap + Dented Surface)
+
+This demo renders a thick slab with a dented top surface based on sensor values.
+Values are mapped to a depth range (0-500 -> 0..kDentMax), so higher force makes
+the surface go deeper. The side walls follow the dent so it reads as one solid.
+
+### UML (Mermaid)
+```mermaid
+classDiagram
+    class AppState {
+        +int minV
+        +int maxV
+        +mat4 mvp
+        +vec3 cameraPos
+    }
+    class HeightMap {
+        +low_values[12x7]
+        +height_values[1200x700]
+        +update_demo_heightmap(t)
+        +upload_height_texture()
+    }
+    class HeatmapMesh {
+        +meshCols
+        +meshRows
+        +vao/vbo/ibo
+    }
+    class SkirtMesh {
+        +border_uvs
+        +update_skirt_vertices()
+    }
+    class BaseMesh {
+        +thickness
+        +vao/vbo/ibo
+    }
+    class Renderer {
+        +render_background()
+        +render_base()
+        +render_skirt()
+        +render_heatmap()
+    }
+    class Shaders {
+        +heatmap.vert/frag
+        +base.vert/frag
+        +bg.vert/frag
+    }
+
+    AppState --> Renderer
+    HeightMap --> HeatmapMesh
+    HeightMap --> SkirtMesh
+    Renderer --> HeatmapMesh
+    Renderer --> SkirtMesh
+    Renderer --> BaseMesh
+    Renderer --> Shaders
+```
+
+### How It Works (Step-by-Step)
+1) `update_demo_heightmap(t)` generates a slow-changing 12x7 grid using a few
+   Gaussian blobs. This is the "raw sensor" layer.
+2) The 12x7 grid is upsampled to 1200x700 with bilinear filtering, stored in
+   `height_values`.
+3) `height_values` is uploaded into an `GL_R32F` texture (`height_tex`).
+4) `heatmap.vert` samples `height_tex` and displaces the surface in Z:
+   `z = uBaseZ + h`, where `h` is the mapped depth (0..kDentMax).
+5) `heatmap.frag` re-samples neighbor texels to approximate a normal, then applies
+   a simple light + color ramp for readability.
+6) `init_skirt_geometry()` builds a ring of border vertices, and
+   `update_skirt_vertices()` samples the border heights so the side walls "follow"
+   the dent. This keeps the slab looking solid when the edge is depressed.
+7) Render order: background grid -> back face -> skirt -> heatmap surface.
+
+### Key Parameters You Can Tune
+- `kThickness`: slab thickness.
+- `kDentMax`: maximum dent depth (keep <= thickness).
+- `kMeshCols/kMeshRows`: heatmap mesh resolution (visual smoothness).
+- `kHeightW/kHeightH`: texture resolution (sampling detail).
+- `g_state.minV/maxV`: value range (0..500 by default).
+
+### If You Want Real Data
+Replace `update_demo_heightmap()` with your sensor values:
+- Fill `low_values` from your 12x7 data.
+- Run the same upsample step to `height_values`.
+- Call `upload_height_texture_if_needed()` and `update_skirt_vertices()` each frame.