05_11_11_visualization_system - Sistema de Visualización¶

Estado: 📋 Pendiente Prioridad: MEDIA Estimación: 4-6 semanas Dependencias: Todo el subsistema

🎯 PROPÓSITO¶

El Visualization System permite ver y depurar el grafo visualmente, esencial para entender flujos complejos:

👁️ Renderizado del grafo con layouts inteligentes
📊 Métricas en tiempo real (CPU, levels, latency)
🎨 Color-coding por tipo y estado
🖱️ Interacción (select, drag, edit)
📸 Export a SVG/PNG

Sin visualización: Debug con printf, confusión Con visualización: Entendimiento inmediato, debug 10x más rápido

📐 COMPONENTES¶

1. Graph Renderer¶

class GraphRenderer {
    enum LayoutAlgorithm {
        HIERARCHICAL,      // Layered by dependency
        FORCE_DIRECTED,    // Physics simulation
        CIRCULAR          // Nodes in circle
    };

    void setLayout(LayoutAlgorithm algo);
    void render(const AudioGraph& graph, RenderTarget& target);
};

Layout Algorithms:

Hierarchical (Sugiyama): - Best for: DAGs with clear flow - Pros: Shows dependencies clearly - Cons: Not for cyclic graphs

Force-Directed (Fruchterman-Reingold): - Best for: General graphs - Pros: Works for any graph - Cons: Slow for >100 nodes

Circular: - Best for: Feedback-heavy graphs - Pros: Shows cycles clearly - Cons: Can be cluttered

2. Visual Elements¶

struct NodeVisual {
    Shape shape;           // Circle/Rectangle by type
    Color color;           // By category
    std::string label;
    Position position;

    // Annotations
    float cpuUsage;        // 0-100%
    float peakLevel;       // -inf to 0 dB
    bool isClipping;
    bool isBypassed;
};

struct EdgeVisual {
    LineStyle style;       // Solid=audio, dashed=control
    float width;           // Proportional to channels
    Color color;           // Green=active, gray=muted
    bool animated;         // Show signal flow
};

Visual Language:

Node Shapes: - 🔵 Circle: Sources (input, oscillators) - ▭ Rectangle: Processors (filters, effects) - ⬡ Hexagon: Outputs (DAC, file)

Node Colors: - 🔵 Blue: Input/Source - 🟢 Green: Effects/Processors - 🟡 Yellow: Analysis/Meters - 🔴 Red: Output/Destination - ⚫ Gray: Bypassed

Edge Styles: - ━━━ Solid: Audio signal - ╌╌╌ Dashed: Control signal - ┄┄┄ Dotted: MIDI - ━━━ Thick: Multi-channel

Edge Colors: - 🟢 Green: Active, signal present - ⚫ Gray: Muted or inactive - 🔴 Red: Clipping detected

3. Real-Time Monitor¶

class GraphMonitor {
    struct NodeMetrics {
        float cpuUsage;           // % of total
        float peakLevel;          // dB
        int processCallsPerSec;
        bool isClipping;
        float latencyMs;
    };

    void updateMetrics();
    void renderOverlay(GraphRenderer& renderer);
};

Metrics Displayed: - CPU usage (color intensity) - Audio levels (meter beside node) - Latency (ms on node) - Clipping warnings (red indicator) - Process rate (calls/sec)

4. Interactive Features¶

class GraphInteraction {
    NodeID getNodeAtPosition(Point pos);
    void selectNode(NodeID node);
    void dragNode(NodeID node, Point delta);
    void editParameter(NodeID node, const std::string& param);

    // Connection editing
    void startConnection(NodeID from, PortID port);
    void completeConnection(NodeID to, PortID port);
    void deleteConnection(EdgeID edge);
};

Interactions: - 🖱️ Click node → Select - 🖱️ Drag node → Move - 🖱️ Double-click → Edit parameters - 🖱️ Drag from port → Create connection - ⌨️ Delete key → Remove selected - 🖱️ Scroll → Zoom - 🖱️ Middle-drag → Pan

5. Export System¶

class GraphExporter {
    void exportToSVG(const std::string& path);
    void exportToPNG(const std::string& path, int width, int height);
    void exportToJSON(const std::string& path);  // Structure only
};

📂 ESTRUCTURA¶

05_11_11_visualization_system/
├── include/
│   ├── GraphRenderer.h
│   ├── LayoutAlgorithm.h
│   ├── GraphMonitor.h
│   ├── GraphInteraction.h
│   ├── GraphExporter.h
│   └── RenderTarget.h          # Abstract interface
├── src/
│   ├── GraphRenderer.cpp
│   ├── HierarchicalLayout.cpp
│   ├── ForceDirectedLayout.cpp
│   ├── CircularLayout.cpp
│   ├── GraphMonitor.cpp
│   ├── GraphInteraction.cpp
│   └── GraphExporter.cpp
├── backends/
│   ├── OpenGLRenderTarget.cpp
│   ├── Direct2DRenderTarget.cpp
│   └── SVGRenderTarget.cpp
├── tests/
│   ├── test_layouts.cpp
│   ├── test_rendering.cpp
│   ├── test_interaction.cpp
│   └── test_export.cpp
├── examples/
│   ├── simple_visualizer.cpp
│   ├── interactive_editor.cpp
│   └── metrics_overlay.cpp
└── docs/
    ├── VISUAL_LANGUAGE.md
    ├── LAYOUT_ALGORITHMS.md
    └── INTEGRATION_GUIDE.md

🎯 ENTREGABLES¶

📊 MÉTRICAS DE ÉXITO¶

Visual Quality¶

✅ Clear node separation (no overlaps)
✅ Readable labels at all zoom levels
✅ Intuitive color coding
✅ Smooth animations (60 FPS)

Performance¶

✅ 60 FPS with 100 nodes
✅ 30 FPS with 500 nodes
✅ <100ms layout calculation (100 nodes)

Usability¶

✅ Intuitive without training
✅ Fast navigation (zoom, pan)
✅ Clear visual hierarchy
✅ Helpful tooltips

Accuracy¶

✅ Metrics update 10x/sec
✅ <10ms latency for interaction
✅ Precise export (SVG matches display)

💡 EJEMPLO VISUAL¶

     [Input]──────┐
        │         │
        ↓         ↓
     [Gain]    [Filter]
     32%       45%         ← CPU usage
     -12dB     -18dB       ← Peak level
        │         │
        └────┬────┘
             ↓
          [Output]
          15%
          -6dB

Con colores: - Nodos verdes (procesando) - Edges verdes (señal activa) - Números en blanco (métricas) - Background negro (clarity)

🎨 TEMAS VISUALES¶

Dark Theme (default)¶

Background: #1e1e1e
Nodes: #2d2d2d
Text: #ffffff
Edges: #4a4a4a
Active: #00ff00
Warning: #ffff00
Error: #ff0000

Light Theme¶

Background: #ffffff
Nodes: #e0e0e0
Text: #000000
Edges: #808080
Active: #00aa00
Warning: #ffaa00
Error: #cc0000

High Contrast¶

Background: #000000
Nodes: #ffffff
Text: #000000
Edges: #ffffff
Active: #00ff00
Warning: #ffff00
Error: #ff0000

🖼️ SCREENSHOTS (Conceptual)¶

Simple Chain¶

[Input] → [Gain] → [Filter] → [Output]

Parallel Effects¶

         ┌─ [Reverb] ─┐
[Input] ─┤            ├─ [Mix] → [Output]
         └─ [Delay] ──┘

Feedback Loop¶

[Input] → [Delay] → [Filter] → [Output]
            ↑          │
            └──────────┘

Multi-Band¶

         ┌─ [LowBand] ─┐
[Input] ─┼─ [MidBand] ─┼─ [Sum] → [Output]
         └─ [HiBand] ──┘

🔧 CONFIGURACIÓN¶

GraphVisualizer visualizer;

// Layout
visualizer.setLayout(LayoutAlgorithm::HIERARCHICAL);

// Visual options
visualizer.showMetrics(true);
visualizer.showEdgeFlow(true);    // Animate signal flow
visualizer.setColorScheme(ColorScheme::DARK);

// Interaction
visualizer.enableEditing(true);
visualizer.enableDragging(true);

// Render
while (running) {
    visualizer.update(deltaTime);
    visualizer.render(renderTarget);
}

📈 ROADMAP¶

Fase 1 - Basic Visualization (2 weeks)¶

Static rendering
Hierarchical layout
Basic colors

Fase 2 - Metrics & Animation (2 weeks)¶

Real-time metrics
Animated signal flow
CPU/level displays

Fase 3 - Interaction (2 weeks)¶

Selection
Dragging
Basic editing

Fase 4 - Advanced Features (2 weeks)¶

Additional layouts
Export
Themes
Polish

Creado: 2025-10-14 Versión: 1.0.0