visualizador_instanciados/radial_sugiyama/VISUALIZATION_TIMELINE.md

Graph Visualization Improvement Timeline

This document records the main ways the graph visualization pipeline has been refined during the current Rust migration and tuning work.

2026-03-16 — Baseline migration and pipeline setup

• Ported the radial Sugiyama-style layout pipeline from the Java implementation into the Rust crate radial_sugiyama.
• Kept the overall structure:
  • hierarchy leveling
  • dummy-node insertion
  • crossing reduction
  • coordinate assignment
  • radial projection
• Changed the leveling source on purpose for the target use case:
  • instead of centrality-based levels, levels are computed as hierarchy rings for a DAG
  • this guarantees superclass/interface nodes are placed on inner rings and subclasses on outer rings

2026-03-16 — Improve parity with the Java implementation

• Closed Java → Rust gaps in crossing reduction:
  • restored horizontal crossing counting
  • restored mixed horizontal/vertical crossing counting
  • aligned the sifting stage more closely with the active Java implementation
• Added richer layout artifacts so the pipeline outputs not only node coordinates, but also:
  • edge offsets
  • routed edge shapes
  • routed node information
  • layout center
• Ported route generation logic for:
  • spiral inter-level edges
  • intra-level edges
  • straight root-level edges

2026-03-16 — Add ontology input through Turtle

• Added a Turtle import layer using oxttl.
• Imported only rdfs:subClassOf triples.
• Mapped ontology class IRIs to graph nodes.
• Preserved edge direction as:
  • superclass -> subclass
• This made the layout pipeline usable directly from ontology data instead of requiring manual graph construction.

2026-03-16 — Add environment-based execution and layout controls

• Added a .env-driven runner so the pipeline can be configured without recompiling.
• Moved the main geometric drawing constants into env-backed config:
  • input file location
  • output location
  • minimum radius
  • level spacing
  • positive-coordinate shifting
  • spiral sampling quality
  • border and node-distance scaling
• This was the first step toward making the visualization tunable instead of fixed.

2026-03-16 — Add SVG export as the final output step

• Added SVG generation after layout execution.
• Reused the computed graph geometry instead of inventing a separate renderer:
  • node coordinates become SVG circles
  • routed edge points become SVG paths
  • ring levels become background circles
  • labels are drawn from node IRIs
• This made the pipeline produce a directly inspectable visual artifact.

2026-03-16 — Investigate readability problems in the first SVG output

• Observed two major problems in the rendered output:
  • many nodes on the same level were visually packed into a small arc of the ring
  • some edges wrapped around the center with very long spiral paths
• Determined that these were not only SVG issues:
  • node clustering came from the current radial projection rule
  • edge wrapping came from the routed edge model and its offset-based spiral construction
• Compared this behavior with the paper and confirmed:
  • the paper intentionally allows packed angular spans
  • the paper intentionally allows winding spiral edges
  • but these choices may be undesirable for the current ontology-navigation use case

2026-03-16 — Add an SVG straight-edge mode for experimentation

• Added RADIAL_SVG_SHORTEST_EDGES so the SVG renderer could ignore routed edge directions/offsets and draw direct shortest node-to-node segments instead.
• This improved edge length visually, but it introduced a conceptual mismatch:
  • crossing reduction had optimized the graph for wrapped spiral edges
  • rendering direct shortest segments reintroduced many crossings
• Result:
  • useful as a diagnostic/preview mode
  • not a principled replacement for the original routing objective

2026-03-16 — Add configurable ring distribution mode

• Added RADIAL_RING_DISTRIBUTION with two modes:
  • packed
  • distributed
• packed keeps the paper/Java-style projection:
  • one global width is used to derive angular positions
  • narrower levels may occupy only part of the circle
• distributed changes only the projection step:
  • nodes on the same level are spread around the full ring
  • ring order is preserved, but the level fills the full 2π
• This was introduced specifically to improve readability when the packed projection makes ontology branches appear collapsed.

2026-03-16 — Restrict the ontology view to the BFO entity subtree

• Added RADIAL_ROOT_CLASS_IRI.
• Defaulted it to:
  • http://purl.obolibrary.org/obo/BFO_0000001
• Added a preprocessing filter step that:
  • imports the full subClassOf graph
  • finds the configured root class by exact IRI
  • keeps only the root and its descendants
  • discards unrelated ontology branches before layout
• This makes the visualization more focused and reduces clutter for the target ontology exploration workflow.

Current visualization controls

The current pipeline now supports these major readability/behavior controls through .env:

• RADIAL_ROOT_CLASS_IRI — choose the ontology subtree root
• RADIAL_RING_DISTRIBUTION — choose packed vs distributed ring projection
• RADIAL_SVG_SHORTEST_EDGES — choose routed edges vs direct shortest SVG segments
• RADIAL_MIN_RADIUS
• RADIAL_LEVEL_DISTANCE
• RADIAL_NODE_DISTANCE
• RADIAL_SPIRAL_QUALITY

Current tradeoffs

• packed rings are closer to the paper and Java behavior, but can visually cluster nodes.
• distributed rings are more readable, but deviate from the original projection philosophy.
• routed spiral edges are more consistent with the crossing-reduction objective, but can look long and unintuitive.
• shortest SVG edges are visually direct, but may contradict the layout’s crossing-minimization assumptions.
• subtree filtering around BFO entity improves focus, but intentionally hides unrelated ontology regions.

Current direction of improvement

The visualization work is moving toward a readable ontology-browser layout rather than strict reproduction of the original paper. The main current themes are:

1. keep the hierarchical ring semantics
2. reduce clutter by filtering to a meaningful ontology root
3. make projection and rendering behavior configurable
4. improve readability without discarding the useful parts of the original radial Sugiyama pipeline