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