radial sugiyama positioning integration

radial_sugiyama/VISUALIZATION_TIMELINE.md

@@ -0,0 +1,141 @@
+# 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