dataforge/fn_registry
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Egutierrez
2026-04-25 21:48:43 +02:00
parent b3e55f7abe
commit cebf87cb4e
6 changed files with 259 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cpp/functions/viz/scatter_3d.cpp
+33
View File
@@ -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<float*>(cfg.sizes);
if (cfg.colors) spec.MarkerFillColors = const_cast<ImU32*>(cfg.colors);
ImPlot3D::PlotScatter("##points", cfg.xs, cfg.ys, cfg.zs, cfg.n, spec);
ImPlot3D::EndPlot();
}
}
} // namespace fn
cpp/functions/viz/scatter_3d.h
+29
View File
@@ -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
cpp/functions/viz/scatter_3d.md
+77
View File
@@ -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);
```
cpp/functions/viz/surface_plot_3d.cpp
+47 -9
View File
@@ -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 <vector>
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<float> xs(total);
std::vector<float> 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
cpp/functions/viz/surface_plot_3d.h
+35 -6
View File
@@ -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
cpp/functions/viz/surface_plot_3d.md
+38 -30
View File
@@ -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 <vector>
#include <cmath>
constexpr int N = 64;
std::vector<float> 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.