feat(viz): surface_plot_3d real (ImPlot3D) + scatter_3d nuevo

surface_plot_3d (v2.0.0): quita el STUB. API basada en SurfacePlot3DConfig (z[nx*ny] row-major + ranges X/Y) que delega en ImPlot3D::PlotSurface. Las coordenadas X/Y por vertice se generan internamente desde [x_min, x_max] x [y_min, y_max]. scatter_3d (v1.0.0): nuevo primitivo. Scatter 3D con tamano y color opcionales por punto via ImPlot3DSpec::MarkerSizes / MarkerFillColors. Util para PCA / clustering / nubes de puntos sinteticas. Ambos namespace fn::, kind component, purity pure. Orbit / zoom / pan los aporta ImPlot3D nativo. Issue 0028.
2026-04-25 21:48:43 +02:00
parent b3e55f7abe
commit cebf87cb4e
6 changed files with 259 additions and 45 deletions
@@ -0,0 +1,77 @@
+---
+name: scatter_3d
+kind: component
+lang: cpp
+domain: viz
+version: "1.0.0"
+purity: pure
+signature: "void scatter_3d(const char* title, const fn::Scatter3DConfig& cfg)"
+description: "Scatter 3D ImPlot3D con tamano y color opcional por punto, orbit/zoom/pan nativos"
+tags: [implot3d, chart, visualization, gpu, scatter, 3d, points]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: ""
+imports: [imgui, implot3d]
+tested: false
+tests: []
+test_file_path: ""
+file_path: "cpp/functions/viz/scatter_3d.cpp"
+framework: imgui
+params:
+  - name: title
+    desc: "Titulo / id interno del plot"
+  - name: cfg
+    desc: "fn::Scatter3DConfig — xs, ys, zs (length n), sizes opcional, colors opcional (ImU32 RGBA), size del plot"
+output: "Renderiza una nube de puntos 3D dentro del frame ImGui actual; soporta orbit (drag), zoom (wheel) y pan"
+---
+
+# scatter_3d
+
+Scatter 3D usando `ImPlot3D::PlotScatter`. Soporta tamano y color opcional por punto via `ImPlot3DSpec::MarkerSizes` / `MarkerFillColors`.
+
+Util para visualizaciones de PCA / clustering / nubes de puntos sinteticas. Llamar dentro de un frame ImGui activo.
+
+## Caracteristicas
+
+- **Per-point size**: pasar `cfg.sizes` (length = n, en pixeles) o dejar `nullptr` para usar el tamano del estilo activo.
+- **Per-point color**: pasar `cfg.colors` (length = n, ImU32 RGBA) o dejar `nullptr` para que ImPlot3D use el color del colormap activo.
+- **Orbit / zoom / pan**: nativos de ImPlot3D.
+
+## Ejemplo
+
+```cpp
+#include "viz/scatter_3d.h"
+#include "imgui.h"
+#include <vector>
+#include <random>
+
+const int N = 500;
+std::vector<float> xs(N), ys(N), zs(N);
+std::vector<ImU32> colors(N);
+
+std::mt19937 rng(42);
+std::normal_distribution<float> g(0.f, 0.4f);
+const ImU32 palette[3] = {
+    IM_COL32(255, 99,  71, 255),  // tomate
+    IM_COL32( 65,170,255, 255),   // azul
+    IM_COL32(120,220,120, 255),   // verde
+};
+const float cx[3] = {-1.5f, 1.5f, 0.f};
+const float cy[3] = { 0.f,   0.f, 2.0f};
+const float cz[3] = { 0.f,   1.0f,-1.0f};
+for (int i = 0; i < N; ++i) {
+    int c = i % 3;
+    xs[i] = cx[c] + g(rng);
+    ys[i] = cy[c] + g(rng);
+    zs[i] = cz[c] + g(rng);
+    colors[i] = palette[c];
+}
+
+fn::Scatter3DConfig cfg{};
+cfg.xs = xs.data(); cfg.ys = ys.data(); cfg.zs = zs.data();
+cfg.colors = colors.data();
+cfg.n = N;
+fn::scatter_3d("##clusters", cfg);
+```