015 - Parameter Visualization

The Parameter Visualization Module enables visual display of parameters.

Why Visualization?

With dozens of Tweakpane sliders, you quickly lose track. Which parameters are actually changing? Which have extreme values?

ParameterVisualization makes parameters visible:

• Artworks as observers of other artworks
• Identifying active/changing parameters via heuristics
• Radial visualization as Mandala or Creature

Components

ParameterHistory

Tracks parameter changes over time.

Concept

Time ─────────────────────────────────────────▶

brush.size:    100 ──▶ 120 ──▶ 115 ──▶ 130 ──▶ 125
brush.color:   #FF0000 (unchanged)
position.x:    0.5 ──▶ 0.52 ──▶ 0.48 ──▶ 0.51 ──▶ 0.53

The history stores the last N values and calculates:

• Variance – How much does the value fluctuate?
• Trend – Rising, falling, or constant?
• Frequency – How often does it change?

API

Options

Smart Filter (ParameterMandala)

The Smart Filter automatically distinguishes between active (changing) and static (unchanging) parameters.

The Problem

A typical artwork has 50+ parameters, but only a few change at runtime:

• ❌ canvas.width = 1920 (never changes)
• ❌ animation.duration = 5000 (constant)
• ✅ entity.stats.centerX = 0.52 → 0.48 → 0.55 (changes every frame)
• ✅ brush.rotation = 45 → 46 → 47 (animated)

The Solution

const mandala = new ParameterMandala({
  smartFilter: true,
  varianceThreshold: 0.01,  // min 1% change
  historyLength: 30,        // watch last 30 frames
});

How it works:

1. Variance Tracking – For each parameter, the history calculates variance
2. Threshold Check – Only parameters with variance > threshold appear
3. Delayed Display – New parameters only appear after they've actually changed

Result

Without Smart Filter:          With Smart Filter:
┌──────────────────────┐       ┌──────────────────────┐
│ canvas.width         │       │                      │
│ canvas.height        │       │ entity.stats.centerX │
│ animation.duration   │       │ entity.stats.centerY │
│ entity.stats.centerX │  ──▶  │ entity.stats.avgSpeed│
│ entity.stats.centerY │       │ entity.e0_x          │
│ entity.stats.avgSpeed│       │ brush.rotation       │
│ entity.e0_x          │       │                      │
│ ... (50 more)        │       │ (only active values) │
└──────────────────────┘       └──────────────────────┘

ParameterMandala

Radial visualization of parameters.

Concept

Each parameter becomes a segment on a radial diagram:

• Angle – Parameter position (sorted by activity)
• Length – Normalized value (0-1)
• Color – From ColorSet or value-based
• Pulse – When value changes

Configuration

const mandala = new ParameterMandala({
  // Layout
  innerRadius: 50,
  outerRadius: 200,
  gapAngle: 2,            // Gap between segments

  // Display
  showLabels: true,
  labelPosition: 'outside',
  colorMode: 'value',     // 'value' | 'fixed' | 'colorset'

  // Animation
  animateChanges: true,
  pulseOnChange: true,
  pulseDuration: 200,

  // Smart Filter
  smartFilter: true,
  varianceThreshold: 0.01,
  maxSegments: 24,
});

Visual Styles

Bulge Effect

The Bulge Effect makes active parameters visually protrude from the Mandala:

const mandala = new ParameterMandala({
  bulgeEffect: true,
  bulgeAmount: 1.5,       // 1.5× larger when active
  bulgeDecay: 0.95,       // Slow decay
});

How it works:

1. Parameter value changes → Bulge increases
2. Bulge slowly decreases (decay)
3. More active parameters pulsate more strongly

ParameterCreature

Organic visualization as "creature."

Concept

Parameters control body parts of an abstract creature:

• Size – Body Size
• Color – Body Color
• Appendages – Number of Extremities
• Movement – Breathing, Pulsing

const creature = new ParameterCreature({
  mapping: {
    'brush.size': 'bodySize',
    'brush.color': 'bodyColor',
    'animation.speed': 'breatheRate',
    'particles.count': 'appendageCount',
  },
  style: 'organic',  // 'organic' | 'geometric' | 'abstract'
});

ParameterMapper

Automatic mapping of parameters to visual properties.

The Problem

New parameters appear (from MIDI, Socket, new agents) – how to visualize them automatically?

The Solution

const mapper = new ParameterMapper({
  autoDetect: true,
  typeMapping: {
    number: 'bar',
    boolean: 'dot',
    string: 'label',
    color: 'swatch',
  },
});

// Auto-detect and map
const mapping = mapper.analyze(parameterObject);

Mapping Rules

ParameterObserver

Socket bridge for observing other artworks.

Concept

┌─────────────────┐      ┌──────────────────┐     ┌─────────────────┐
│   Artwork A     │      │   Socket Server  │     │   Artwork B     │
│ (Entity System) │─────▶│                  │────▶│   (Mandala)     │
│                 │      │                  │     │                 │
│ Emits parameters│      │ Routes messages  │     │ Visualizes      │
└─────────────────┘      └──────────────────┘     └─────────────────┘

Configuration

const observer = new ParameterObserver({
  serverUrl: 'http://localhost:4000',
  targetArtwork: 'item-cc-entities',  // Artwork to observe
  autoConnect: true,
});

observer.onUpdate((params, artworkId) => {
  mandala.updateParameters(params);
});

API

Features

RoomSelector

Tweakpane UI for selecting artwork rooms.

Concept

If multiple artworks are running, you want to quickly switch which one to observe.

const selector = new RoomSelector({
  pane: myTweakpane,
  observer: myParameterObserver,
  serverUrl: 'http://localhost:4000',
});

// UI automatically shows available artworks
// Selection updates the observer target

Features

Usage Example: Complete Setup

import {
  ParameterObserver,
  ParameterMandala,
  RoomSelector,
} from '@carstennichte/cc-toolbox';

// 1. Observer for socket connection
const observer = new ParameterObserver({
  serverUrl: 'http://localhost:4000',
  targetArtwork: 'item-cc-entities',
});

// 2. Mandala for visualization
const mandala = new ParameterMandala({
  smartFilter: true,
  bulgeEffect: true,
  outerRadius: 250,
});

// 3. Connect
observer.onUpdate((params) => {
  mandala.updateParameters(params);
});

// 4. Room selector in Tweakpane
const selector = new RoomSelector({
  pane: myPane,
  observer: observer,
});

// 5. Draw
function draw() {
  mandala.draw(ctx, canvas.width / 2, canvas.height / 2);
}

Combination with Agents

ParameterVisualization works excellently with Entity_Manager:

┌─────────────────────────────────────────────────────────┐
│                     Art.Works! Studio                   │
│  ┌─────────────────┐        ┌─────────────────────────┐ │
│  │   Entity Grid   │───────▶│    Mandala Visualizer   │ │
│  │   item-001      │        │       item-002          │ │
│  │                 │ Socket │                         │ │
│  │  centerX: 0.52  │───────▶│  ┌───────────────────┐  │ │
│  │  centerY: 0.48  │        │  │                   │  │ │
│  │  avgSpeed: 0.02 │        │  │   Smart Mandala   │  │ │
│  │  e0_x: 0.12     │        │  │  with Bulge       │  │ │
│  │  ...            │        │  │                   │  │ │
│  │                 │        │  └───────────────────┘  │ │
│  └─────────────────┘        └─────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

The Mandala automatically filters canvas.width, animation.duration, etc., and only shows the dynamic entity statistics – exactly what is interesting.