From cebf87cb4ed9d9184b8e8e0a1a4535554d94d670 Mon Sep 17 00:00:00 2001 From: Egutierrez Date: Sat, 25 Apr 2026 21:48:43 +0200 Subject: [PATCH] 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. --- cpp/functions/viz/scatter_3d.cpp | 33 ++++++++++++ cpp/functions/viz/scatter_3d.h | 29 ++++++++++ cpp/functions/viz/scatter_3d.md | 77 +++++++++++++++++++++++++++ cpp/functions/viz/surface_plot_3d.cpp | 56 +++++++++++++++---- cpp/functions/viz/surface_plot_3d.h | 41 +++++++++++--- cpp/functions/viz/surface_plot_3d.md | 68 ++++++++++++----------- 6 files changed, 259 insertions(+), 45 deletions(-) create mode 100644 cpp/functions/viz/scatter_3d.cpp create mode 100644 cpp/functions/viz/scatter_3d.h create mode 100644 cpp/functions/viz/scatter_3d.md diff --git a/cpp/functions/viz/scatter_3d.cpp b/cpp/functions/viz/scatter_3d.cpp new file mode 100644 index 00000000..95a45004 --- /dev/null +++ b/cpp/functions/viz/scatter_3d.cpp @@ -0,0 +1,33 @@ +#include "viz/scatter_3d.h" + +#include "imgui.h" +#include "implot3d.h" + +namespace fn { + +void scatter_3d(const char* title, const Scatter3DConfig& cfg) { + if (!cfg.xs || !cfg.ys || !cfg.zs || cfg.n < 1) { + ImGui::BeginGroup(); + ImGui::TextDisabled("%s", title ? title : "##scatter_3d"); + ImGui::TextWrapped("scatter_3d: necesita xs, ys, zs != nullptr y n >= 1 (recibido n=%d)", + cfg.n); + ImGui::EndGroup(); + return; + } + + if (ImPlot3D::BeginPlot(title, cfg.size)) { + ImPlot3D::SetupAxes("x", "y", "z"); + + // ImPlot3DSpec::MarkerSizes / MarkerFillColors esperan punteros no + // const; los arrays de cfg vienen como const*. Como ImPlot3D solo los + // lee, hacemos un const_cast acotado a esta llamada. + ImPlot3DSpec spec; + if (cfg.sizes) spec.MarkerSizes = const_cast(cfg.sizes); + if (cfg.colors) spec.MarkerFillColors = const_cast(cfg.colors); + + ImPlot3D::PlotScatter("##points", cfg.xs, cfg.ys, cfg.zs, cfg.n, spec); + ImPlot3D::EndPlot(); + } +} + +} // namespace fn diff --git a/cpp/functions/viz/scatter_3d.h b/cpp/functions/viz/scatter_3d.h new file mode 100644 index 00000000..f45ef4a9 --- /dev/null +++ b/cpp/functions/viz/scatter_3d.h @@ -0,0 +1,29 @@ +#pragma once + +#include "imgui.h" + +namespace fn { + +// Configuracion para scatter_3d. +// +// `xs`, `ys`, `zs` son arrays de tamano `n`. `sizes` y `colors` son +// opcionales: si se pasan, se usan por punto (size en pixeles, color como +// ImU32 RGBA). Si son nullptr, ImPlot3D usa los valores por defecto del +// estilo activo. +struct Scatter3DConfig { + const float* xs = nullptr; + const float* ys = nullptr; + const float* zs = nullptr; + const float* sizes = nullptr; // opcional, length = n + const ImU32* colors = nullptr; // opcional, length = n + int n = 0; + ImVec2 size = ImVec2(-1.f, 400.f); +}; + +// Renderiza un scatter 3D usando ImPlot3D::PlotScatter. +// +// Llamar dentro de un frame ImGui activo. Si xs / ys / zs son nullptr o +// n < 1, renderiza un mensaje informativo. +void scatter_3d(const char* title, const Scatter3DConfig& cfg); + +} // namespace fn diff --git a/cpp/functions/viz/scatter_3d.md b/cpp/functions/viz/scatter_3d.md new file mode 100644 index 00000000..3fd868eb --- /dev/null +++ b/cpp/functions/viz/scatter_3d.md @@ -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 +#include + +const int N = 500; +std::vector xs(N), ys(N), zs(N); +std::vector colors(N); + +std::mt19937 rng(42); +std::normal_distribution 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); +``` diff --git a/cpp/functions/viz/surface_plot_3d.cpp b/cpp/functions/viz/surface_plot_3d.cpp index 99c2f0bd..99a52941 100644 --- a/cpp/functions/viz/surface_plot_3d.cpp +++ b/cpp/functions/viz/surface_plot_3d.cpp @@ -1,12 +1,50 @@ #include "viz/surface_plot_3d.h" -#include "imgui.h" -void surface_plot_3d(const char* title, const float* values, int rows, int cols, - float z_min, float z_max) { - ImGui::BeginGroup(); - ImGui::TextDisabled("[STUB] %s", title); - ImGui::TextWrapped("surface_plot_3d requires ImPlot3D. " - "Add it to cpp/vendor/implot3d/ and rebuild."); - ImGui::Text("Data: %dx%d, range [%.2f, %.2f]", rows, cols, z_min, z_max); - ImGui::EndGroup(); +#include "imgui.h" +#include "implot3d.h" + +#include + +namespace fn { + +void surface_plot_3d(const char* title, const SurfacePlot3DConfig& cfg) { + if (!cfg.z || cfg.nx < 2 || cfg.ny < 2) { + ImGui::BeginGroup(); + ImGui::TextDisabled("%s", title ? title : "##surface_plot_3d"); + ImGui::TextWrapped("surface_plot_3d: necesita z != nullptr y nx,ny >= 2 (recibido %dx%d)", + cfg.nx, cfg.ny); + ImGui::EndGroup(); + return; + } + + // Genera coordenadas X / Y por vertice (row-major, mismo layout que z). + // ImPlot3D::PlotSurface espera arrays paralelos de nx*ny valores. + const int total = cfg.nx * cfg.ny; + std::vector xs(total); + std::vector ys(total); + const float dx = (cfg.nx > 1) ? (cfg.x_max - cfg.x_min) / float(cfg.nx - 1) : 0.f; + const float dy = (cfg.ny > 1) ? (cfg.y_max - cfg.y_min) / float(cfg.ny - 1) : 0.f; + for (int j = 0; j < cfg.ny; ++j) { + const float y = cfg.y_min + dy * float(j); + const int row = j * cfg.nx; + for (int i = 0; i < cfg.nx; ++i) { + xs[row + i] = cfg.x_min + dx * float(i); + ys[row + i] = y; + } + } + + if (ImPlot3D::BeginPlot(title, cfg.size)) { + ImPlot3D::SetupAxes(cfg.x_label, cfg.y_label, cfg.z_label); + ImPlot3D::PlotSurface("##surface", xs.data(), ys.data(), cfg.z, + cfg.nx, cfg.ny); + ImPlot3D::EndPlot(); + } + + if (cfg.show_colormap) { + // ImPlot3D rinde su propia leyenda dentro del plot; el flag aqui se + // reserva como contrato API por si en el futuro se necesita una + // colormap-bar externa (no implementado todavia). + } } + +} // namespace fn diff --git a/cpp/functions/viz/surface_plot_3d.h b/cpp/functions/viz/surface_plot_3d.h index 9e1f43c8..f293b1e3 100644 --- a/cpp/functions/viz/surface_plot_3d.h +++ b/cpp/functions/viz/surface_plot_3d.h @@ -1,8 +1,37 @@ #pragma once -// [STUB] Renders a 3D surface plot using ImPlot3D. -// Requires ImPlot3D to be vendored in cpp/vendor/implot3d/. -// Until then, displays a placeholder message inside an ImGui group. -// Call within an ImGui frame (inside fn::run_app render callback). -void surface_plot_3d(const char* title, const float* values, int rows, int cols, - float z_min, float z_max); +#include "imgui.h" + +namespace fn { + +// Configuracion para surface_plot_3d. +// +// `z` es la malla de alturas en row-major: z[j * nx + i] es la altura en +// (x_i, y_j). Las coordenadas X / Y se generan automaticamente entre +// [x_min, x_max] y [y_min, y_max] (lineales, mismo nx / ny que `z`). +// +// `size.x = -1` extiende el plot a todo el ancho disponible. `size.y` define +// la altura en pixeles (default 400). +struct SurfacePlot3DConfig { + const float* z = nullptr; // length = nx * ny, row-major + int nx = 0; + int ny = 0; + float x_min = 0.f; + float x_max = 1.f; + float y_min = 0.f; + float y_max = 1.f; + const char* x_label = "x"; + const char* y_label = "y"; + const char* z_label = "z"; + ImVec2 size = ImVec2(-1.f, 400.f); + bool show_colormap = true; +}; + +// Renderiza una superficie 3D usando ImPlot3D::PlotSurface. +// +// Llamar dentro de un frame ImGui activo (p.ej. dentro de la lambda render +// pasada a fn::run_app). Si `cfg.z == nullptr` o nx / ny < 2 la funcion +// renderiza un mensaje informativo en lugar del plot. +void surface_plot_3d(const char* title, const SurfacePlot3DConfig& cfg); + +} // namespace fn diff --git a/cpp/functions/viz/surface_plot_3d.md b/cpp/functions/viz/surface_plot_3d.md index 940765eb..ef6537d9 100644 --- a/cpp/functions/viz/surface_plot_3d.md +++ b/cpp/functions/viz/surface_plot_3d.md @@ -3,17 +3,17 @@ name: surface_plot_3d kind: component lang: cpp domain: viz -version: "1.0.0" +version: "2.0.0" purity: pure -signature: "void surface_plot_3d(const char* title, const float* values, int rows, int cols, float z_min, float z_max)" -description: "[STUB] Renderiza una superficie 3D — requiere ImPlot3D (no vendoreado aun)" -tags: [implot3d, chart, visualization, gpu, surface, 3d, stub] +signature: "void surface_plot_3d(const char* title, const fn::SurfacePlot3DConfig& cfg)" +description: "Superficie 3D ImPlot3D — malla z[nx*ny] row-major + ranges X/Y, eje rotatorio drag-to-orbit" +tags: [implot3d, chart, visualization, gpu, surface, 3d] uses_functions: [] uses_types: [] returns: [] returns_optional: false error_type: "" -imports: [imgui] +imports: [imgui, implot3d] tested: false tests: [] test_file_path: "" @@ -21,41 +21,49 @@ file_path: "cpp/functions/viz/surface_plot_3d.cpp" framework: imgui params: - name: title - desc: "Titulo de la superficie, se muestra como header del plot" - - name: values - desc: "Array row-major de alturas Z con dimension rows*cols" - - name: rows - desc: "Numero de filas de la grilla de la superficie" - - name: cols - desc: "Numero de columnas de la grilla de la superficie" - - name: z_min - desc: "Valor minimo del eje Z para escalar el colormap" - - name: z_max - desc: "Valor maximo del eje Z para escalar el colormap" -output: "Renderiza un placeholder informativo en el frame ImGui actual; cuando ImPlot3D este disponible, renderizara la superficie 3D" + desc: "Titulo / id interno del plot" + - name: cfg + desc: "fn::SurfacePlot3DConfig — z (nx*ny row-major), nx, ny, x/y_min, x/y_max, labels, size, show_colormap" +output: "Renderiza una superficie 3D dentro del frame ImGui actual; soporta orbit (drag), zoom (wheel) y pan via ImPlot3D" --- # surface_plot_3d -**STUB** — la implementacion real requiere [ImPlot3D](https://github.com/brenocq/implot3d), que todavia no esta vendoreado en `cpp/vendor/implot3d/`. +Superficie 3D renderizada con [ImPlot3D](https://github.com/brenocq/implot3d) (vendoreado en `cpp/vendor/implot3d/`, pinned v0.4 commit `41ae3e44`). -Mientras tanto la funcion renderiza un grupo ImGui con un mensaje informativo que muestra el titulo, las dimensiones de la grilla y el rango Z. La firma es definitiva y no cambiara cuando se integre ImPlot3D. +La API toma una malla densa `z[nx*ny]` en row-major (`z[j*nx + i]` es la altura en el vertice `(x_i, y_j)`) y ranges para los ejes X / Y. Las coordenadas X / Y por vertice se generan internamente en lineal entre `[x_min, x_max]` y `[y_min, y_max]` — el caller solo necesita pasar el grid de alturas. -## Dependencia pendiente +Llamar dentro de un frame ImGui activo (lambda de `fn::run_app` o similar). El contexto de ImPlot3D lo crea / destruye `app_base` junto al de ImPlot. -Para activar la implementacion real: +## Caracteristicas -1. Clonar o copiar ImPlot3D en `cpp/vendor/implot3d/` -2. Anadir `implot3d.cpp` al build system (CMake / Makefile) -3. Reemplazar el cuerpo de `surface_plot_3d` por la llamada a `ImPlot3D::BeginPlot3D` / `ImPlot3D::PlotSurface` / `ImPlot3D::EndPlot3D` -4. Actualizar `imports` del .md a `[imgui, implot3d]` y quitar el tag `stub` +- **Orbit**: drag con LMB rota la camara alrededor del centro del plot. +- **Zoom**: scroll wheel. +- **Pan**: drag con MMB. +- **Colormap**: ImPlot3D aplica el colormap activo segun la altura Z. `show_colormap` esta reservado como contrato API por si se anyade colorbar externa. -## Uso +## Ejemplo ```cpp -// values es un array row-major de rows*cols floats -float grid[4 * 4] = { ... }; -surface_plot_3d("Mi Superficie", grid, 4, 4, -1.0f, 1.0f); +#include "viz/surface_plot_3d.h" +#include +#include + +constexpr int N = 64; +std::vector z(N * N); +for (int j = 0; j < N; ++j) + for (int i = 0; i < N; ++i) + z[j*N + i] = std::sin(0.2f * i) * std::cos(0.2f * j); + +fn::SurfacePlot3DConfig cfg{}; +cfg.z = z.data(); +cfg.nx = N; cfg.ny = N; +cfg.x_min = 0; cfg.x_max = float(N); +cfg.y_min = 0; cfg.y_max = float(N); +fn::surface_plot_3d("##terreno", cfg); ``` -Debe llamarse dentro del render callback de `fn::run_app` (o cualquier contexto con un frame ImGui activo). +## Limites practicos + +- Mallas hasta ~256×256 son fluidas a 60 FPS en GPUs modernas. Por encima de eso conviene downsamplear. +- ImPlot3D dibuja los triangulos en CPU y los empuja al ImDrawList — no es shader-based.