semantic-zoom

Exploring hierarchical decomposition and semantic zoom—how the visualization changes at different abstraction levels, from company-wide aggregates down to individual actors.

Like Google Maps, the level of detail changes with scale:

Key insight: The "inside" doesn't need to fit the "outside"—this is semantic space, not physical space. A team cube can expand to reveal 50 apps that take up more space than the original cube.

Composite Pattern

Actor (base)
├── LeafActor (app, service, database, vendor)
└── CompositeActor (team, company, region...)
    └── children: Actor[]  ← can be leaves OR other composites

Visual States

Container Fracturing

When drilling into a composite:

1. Siblings fade/mute (context preserved but de-emphasized)
2. Target cube "fractures" or splits
3. Children emerge and settle into positions
4. Flows re-route from aggregate to detailed endpoints

Flows adapt to the current zoom level:

• Collapsed view: Single thick line Engineering ←→ Vendor
• Expanded view: Line fans out to actual connections (api → Vendor, auth → Vendor)

Aggregate flows "unpack" when their source/target expands.

A positioning system that handles spatial arrangement dynamically.

Triggers & Responses

Algorithm Options

Force-Directed Family

Hierarchical/Layered

Space-Filling

Recommended Approach

Hybrid strategy:

1. Force-directed for positioning siblings (organic, handles unknown cardinality)
2. Hierarchical constraints to keep children within parent bounds
3. Semantic zoom to swap representations at threshold
4. Animation choreography for sequenced transitions

From ZUI research:

• Force-Directed Graph Drawing - Wikipedia
• Layered Graph Drawing - Wikipedia
• Semantic Zoom - InfoVis Wiki
• Zooming User Interface - Wikipedia
• ForceAtlas2 Paper - PLOS One
• Pad++ Implementation Paper

• c1.border-grouping: Zones may become composite actors; ForceClustering strategy is relevant
• c2.entity-meshes: Leaf actors use these meshes; composites need new container representation
• c3.data-flows: Flows must support aggregation/disaggregation based on zoom level

• Test harness: HTML page with zoom radio buttons
• Test data: Hierarchical structure (1 Company → 12 Teams → ~166 Apps)
• Basic zoom level rendering (cubes at each level)
• ContainerRug class: flat labeled planes for parent context
• Grid layout for actors within containers
• Nested rugs at Apps level (company + team rugs)
• Design composite actor data model
• Implement CompositeActor class extending BaseMesh
• Collapsed state rendering (cube + badge)
• Expand/collapse animation
• Layout agent prototype (force-directed with containment)
• Flow aggregation logic
• Semantic zoom thresholds
• Sibling muting on drill-down

Test Data Distribution

Total: ~166 apps

1. What triggers zoom level change? Camera distance? User click? Both?
2. Should expansion be animated or instant with fade?
3. How deep can nesting go before UX degrades?
4. How do zones (c1) and composite actors interact?

Scene Object Cleanup (Three.js + Vue)

Problem: Objects weren't being removed when switching zoom levels, even though tracking arrays were cleared.

Root cause: Relying on tracking arrays (renderedCubes, renderedRugs) to stay in sync with the actual Three.js scene is fragile. The removeObject helper from ExperimentBase wasn't reliably removing objects.

Solution: Clear directly from the scene, not from tracking arrays:

function clearScene() {
  const scene = sceneManager.value?.getScene();
  if (!scene) return;

  // Copy children array before modifying
  const toRemove = [...scene.children].filter(obj => {
    // Keep lights, cameras, grid helpers
    if (obj.isLight || obj.isCamera || obj.isGridHelper) return false;
    return obj.isMesh || obj.isGroup;
  });

  toRemove.forEach(obj => {
    scene.remove(obj);
    // Dispose recursively...
  });
}

Key patterns:

1. Copy scene.children before iterating ([...scene.children])
2. Use Three.js type checks: obj.isMesh, obj.isGroup, obj.isLight, obj.isGridHelper
3. Dispose geometry and materials recursively via obj.traverse()
4. Don't trust wrapper functions—go straight to the scene when debugging