Skip to content

995 3d network - #1816

Open
glstott wants to merge 9 commits into
CDCgov:devfrom
glstott:995-3d_network
Open

glstott wants to merge 9 commits into
CDCgov:devfrom
glstott:995-3d_network

Conversation

@glstott

@glstott glstott commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator

Addresses #995: Where is the 3D network view?

Summary

Add View > 3D Network to explore the visible network in an interactive 3D scene, with navigation and styling consistent with other MicrobeTrace views.

  • Implement a separate 3D component using lazy-loaded Three.js and 3d-force-graph. Keep camera state, coordinates, and appearance settings independent of 2D Network.
  • Add trackball rotation, panning, wheel and keyboard zoom, fit/reset controls, layout freezing, and recalculation.
  • Add automatic camera rotation with play/pause controls and an XYZ orientation compass.
  • Add a Heatmap-style Rotate / Pan toggle, accessible labels, and mode-aware help. Remove redundant zoom buttons.
  • Align settings tabs, controls, and legend tables with 2D Network. Support node/link labels and tooltips, mapped sizes and widths, transparency, and neighbor highlighting.
  • Add six 3D node shapes, Shape By assignments, configurable frame-edge widths, and an independent shape legend with docking, sorting, editable headings, counts, and frequencies.
  • Support dual-origin link colors, directed/bidirectional arrowheads visible on opaque links, and consistent distance formatting.
  • Integrate shared selection and filtering, pane/session restoration, Classic session compatibility, graphics recovery, and resource cleanup.
  • Export PNG, JPEG, and WebP images with optional legends, and preserve the 3D frame in dashboard exports.
  • Repair the Cypress dashboard helper to wait for completed restoration and preserve saved pane state.

Documentation and performance

  • Draft 3D Network View wiki guide with example screenshots, including the development-only availability notice.
  • Include the wiki draft assets, offline preview, product documentation, and an opt-in capacity benchmark.
  • Document workstation-specific recommendations of approximately 750 nodes / 1,500 links during layout and 2,000 / 4,000 for frozen navigation.

- Add 3D navigation, selection, styling and layout controls.
- Isolate 3D settings, camera state and coordinates from 2D.
- Support shared filtering, session restoration and PNG/dashboard exports.
- Align pane tabs with other views and handle hidden 2D selection updates.
- Fix dashboard test setup to wait for restoration and reuse restored panes.
- Add 3D documentation and regression coverage.
…tch the styling of other views.

- Add trackball navigation with saved camera roll and improved reset and resize handling.
- Match the toolbar and tabbed settings dialog to the 2D network view.
- Preserve independent 3D settings and improve accessible controls.
- Add opt-in capacity benchmarks, deterministic fixtures, and graph-size recommendations.

Validate camera behavior, repeated performance measurements, and toolbar/settings interactions in Chrome.
- Add a play/pause toolbar control for automatic camera rotation.
- Stop playback during manual navigation and when hiding or closing the view.
- Add a colored X/Y/Z compass that follows orbiting, camera roll, and playback.
- Show axis depth with dashed arrows and end-on markers, and restore compass orientation with saved camera state.

Verified in Chrome and with TypeScript checks. Cypress was not run.
- Match 2D settings styling while keeping 3D appearance settings independent
- Add labels, multi-field tooltips, bounded sizing, and mapped link widths
- Add a dockable 3D shape legend with editable names and shape previews
- Render shape borders as frame edges and correct transparency slider direction
- Support dual-origin link colors and outlined directional arrows
- Share distance formatting across 2D and 3D
- Expand image exports with shape legends, unit coverage, and documentation

Validation: 101 Cypress specs; 395 passed, 5 pre-existing failures reproduced on the base revision, and 14 skipped.
Retain independent 3D Network and Transmission Chain Explorer components, registrations, and session launch options while incorporating upstream Sigma, legend, import, and dependency updates.
- Add a styled Rotate/Pan toggle with accessible labels and mode-aware help.
- Remove redundant zoom buttons while retaining wheel and keyboard zoom.
- Pause camera rotation when switching modes and preserve the mode after graphics recovery.
- Update the 3D navigation documentation.
@glstott

glstott commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

Feedback from email

Before merging, I recommend addressing the following:

  1. Performance: The benchmarks demonstrate good responsiveness for smaller networks but substantial degradation as network size increases. Please add an advisory pop-up for larger networks and recommend filtering or freezing the layout when appropriate. We should position 3D as a complementary visualization rather than a replacement for the existing 2D network.
  2. Scientific interpretation: Please clarify in the documentation that the force-directed 3D coordinates and apparent spatial distances are visualization properties and do not necessarily represent genetic distance, transmission direction, or epidemiologic relationships. Directional arrows should be used only when supported by source data.
  3. Reproducibility: Please consider deterministic layout initialization or an explicit random seed, along with export of the coordinates and camera settings. This would help investigators reproduce figures and analyses.
  4. Integration and testing: Please verify shared selection, filtering, session restoration, and dashboard exports after resolving the current merge conflicts. Additional testing for graphics-resource cleanup and performance with realistic network styling would be valuable.
  5. Navigation: Consider adding preset camera orientations (XY, XZ, YZ, and isometric) for easier navigation and reproducible views.

I also reviewed the six node shapes implemented in the 3D network view. The current geometries provide a good foundation, but I recommend improving their visual quality and distinguishability before release. Please evaluate the following enhancements:

  1. Geometry: Improve the resolution of spheres, cones, and cylinders while preserving performance. Ensure cubes, diamonds, and pyramids have clearly distinguishable faces.
  2. Lighting and shading: Evaluate improved directional and ambient lighting, with better facet contrast. Compare the existing Lambert materials with Standard materials before selecting the final implementation.
  3. Outlines: Improve silhouette and structural-edge rendering so that nodes remain recognizable during camera rotation. Avoid excessive edge lines on smooth shapes.
  4. Node size: Evaluate perceptual size normalization across the six shapes. Nodes mapped to the same size value should have reasonably comparable visual prominence.
  5. Selection: Improve selected-node visibility using a halo or contrasting outline rather than relying solely on node color.
  6. Legends: Ensure the shape previews accurately represent the actual rendered geometry, including proportions, orientation, and shading.
  7. Performance: Benchmark these changes at the existing 750-node and 2,000-node performance tiers. Consider adaptive geometry detail or quality settings if necessary.

The priority should be visual clarity, consistent size interpretation, and maintaining interactive performance of the node shapes. Please include side-by-side before-and-after screenshots of all six shapes, both individually and within a representative network, so we can assess the improvements.

- Refine geometry, lighting, structural edges, and size normalization;
  add torus, capsule, and five-point star shapes.
- Optimize rendering with batching, shared resources, adaptive detail,
  and cached legend previews.
- Add deterministic layouts, compass camera presets, and JSON export
  and restoration of coordinates, camera, and rendering settings.
- Align image exports with 2D and prevent camera shifts during initial
  rendering and legend docking.
- Add large-network guidance, document performance measurements, and
  expand regression coverage for sessions, exports, and resource cleanup.
- Move temporary review tools and generated artifacts outside the
  repository; update documentation and ignore rules.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant