---
id: "0028"
title: "C++ ImPlot3D + surface_plot_3d real + scatter_3d"
status: completado
type: feature
domain:
  - cpp-stack
scope: multi-app
priority: media
depends: []
blocks: []
related: []
created: 2026-05-17
updated: 2026-05-17
tags: []
---
# 0028 — C++ ImPlot3D + surface_plot_3d real + scatter_3d

## APP Metadata

| Campo | Valor |
|-------|-------|
| **ID** | 0028 |
| **Estado** | pendiente |
| **Prioridad** | media |
| **Tipo** | feature — C++ viz (cpp/functions/viz) |

## Dependencias

`surface_plot_3d_cpp_viz` ya existe como **STUB**. Este issue quita el stub.

**Desbloquea:** dashboards 3D (terreno, FFT 2D, height maps, scatter 3D para PCA/clustering visualizations).

---

## Objetivo

1. Vendorear [ImPlot3D](https://github.com/brenocq/implot3d) (MIT, header + cpp) en `cpp/vendor/implot3d/`.
2. Reescribir **`surface_plot_3d_cpp_viz`** (hoy STUB) con implementacion real.
3. Añadir **`scatter_3d_cpp_viz`** — scatter 3D con color/size por punto.
4. Demos en `primitives_gallery`.

## Contexto

`surface_plot_3d_cpp_viz` aparece en el registry pero su `code` es `[STUB] requires ImPlot3D not vendored yet`. Bloquea apps de visualizacion cientifica (heightfield, terreno, superficies parametricas).

ImPlot ya esta vendoreado y se usa para 2D. ImPlot3D es del mismo autor (brenocq), API parejo a ImPlot, con tres-axis y rotacion drag-to-orbit.

## Arquitectura

```
cpp/
├── vendor/implot3d/             # NEW
│   ├── implot3d.h
│   ├── implot3d.cpp
│   ├── implot3d_internal.h
│   ├── implot3d_items.cpp
│   └── implot3d_demo.cpp        # opcional, util como referencia
├── functions/viz/
│   ├── surface_plot_3d.cpp/.h   # MOD — quitar STUB
│   ├── surface_plot_3d.md       # MOD — actualizar tags/notes/code
│   ├── scatter_3d.h             # NEW
│   ├── scatter_3d.cpp           # NEW
│   └── scatter_3d.md            # NEW
└── apps/primitives_gallery/
    ├── demos_3d.cpp             # NEW
    ├── demos.h                  # MOD
    ├── main.cpp                 # MOD
    └── CMakeLists.txt           # MOD
cpp/CMakeLists.txt               # MOD — añadir sources de implot3d
```

### API propuesta

```cpp
namespace fn {

struct SurfacePlot3DConfig {
    const float* z;          // size = nx * ny, row-major
    int nx, ny;
    float x_min = 0.f, x_max = 1.f;
    float y_min = 0.f, y_max = 1.f;
    const char* x_label = "x";
    const char* y_label = "y";
    const char* z_label = "z";
    ImVec2 size = {-1, 400};
    bool show_colormap = true;
};
void surface_plot_3d(const char* title, const SurfacePlot3DConfig& cfg);

struct Scatter3DConfig {
    const float* xs;  // size = n
    const float* ys;
    const float* zs;
    const float* sizes  = nullptr;   // opcional: size = n
    const ImU32* colors = nullptr;   // opcional: size = n
    int n;
    ImVec2 size = {-1, 400};
};
void scatter_3d(const char* title, const Scatter3DConfig& cfg);
}
```

## Tareas

### Fase 1 — Vendor

- 1.1 Clonar ImPlot3D, copiar fuentes a `cpp/vendor/implot3d/`. Pinear a tag/commit conocido.
- 1.2 Inicializar contexto en `app_base` (similar a como ya inicializa ImPlot): `ImPlot3D::CreateContext()` / `DestroyContext()`.
- 1.3 Añadir sources al `cpp/CMakeLists.txt`.

### Fase 2 — surface_plot_3d real

- 2.1 Reescribir `surface_plot_3d.cpp/.h` con la API de arriba usando `ImPlot3D::PlotSurface`.
- 2.2 Actualizar `surface_plot_3d.md`: quitar tag `stub`, actualizar `code`, añadir `uses_functions: []` y `tags: ["3d", "viz"]`.

### Fase 3 — scatter_3d

- 3.1 Implementar `scatter_3d.cpp/.h` con `ImPlot3D::PlotScatter`. Soportar size/color por punto.
- 3.2 `scatter_3d.md` con frontmatter (`kind: component`, `purity: pure`).

### Fase 4 — Gallery demos

- 4.1 `demos_3d.cpp` con dos demos:
  - `demo_surface_plot_3d()`: malla 64×64 con `z = sin(x)*cos(y)`. Sliders para frecuencia.
  - `demo_scatter_3d()`: 500 puntos con clusters sinteticos (3 clusters), colores por cluster.
- 4.2 Registrar en gallery.

### Fase 5 — Tests + docs

- 5.1 Test puro de generacion de datos (la rendering depende del contexto GL, asumir que el smoke-test es la propia gallery).
- 5.2 `./fn index` + verificar `surface_plot_3d_cpp_viz` ya no es STUB.

## Ejemplo de uso

```cpp
std::vector<float> z(64*64);
for (int j=0;j<64;j++) for (int i=0;i<64;i++)
    z[j*64+i] = std::sin(0.2f*i) * std::cos(0.2f*j);

fn::SurfacePlot3DConfig s{};
s.z = z.data(); s.nx = 64; s.ny = 64;
fn::surface_plot_3d("terreno", s);
```

## Decisiones de diseño

- **ImPlot3D vs Plotly export**: ImPlot3D mantiene la coherencia con ImPlot 2D que ya usamos. Sin dependencias extra.
- **Render-only por ahora**: pan/zoom/orbit las aporta ImPlot3D nativo.

## Riesgos

- **ImPlot3D inestable**: pinear commit; documentar version exacta en `cpp/vendor/implot3d/README.md`.
- **Performance con malla grande**: documentar limite practico (~256×256 antes de notar drops).