facett_graphview/
model.rs

1//! The **domain-agnostic graph model** — the same shape nornir's
2//! `src/viz/graph_render.rs::draw_graph` accepts, so this engine is a future
3//! drop-in for that egui routine. Nodes are laid out in *world space* by the
4//! caller (each domain owns its own layout/columns); edges reference nodes by
5//! id. [`Decorations`] is the **caller-supplied** overlay — facett mustn't know
6//! what a "release gate" is, so rings/badges/emphasis-edges are opaque here.
7//!
8//! Colours are a tiny POD [`Color`] (premultiply-free sRGBA8) with a `From`
9//! conversion off egui's `Color32`, so a caller already speaking egui (exactly
10//! nornir's `draw_graph`) maps straight across with zero glue.
11
12/// A straight sRGBA8 colour (NOT premultiplied). The render backends convert to
13/// their own colour type at the seam.
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub struct Color {
16    pub r: u8,
17    pub g: u8,
18    pub b: u8,
19    pub a: u8,
20}
21
22impl Color {
23    pub const fn rgb(r: u8, g: u8, b: u8) -> Self {
24        Self { r, g, b, a: 255 }
25    }
26    pub const fn rgba(r: u8, g: u8, b: u8, a: u8) -> Self {
27        Self { r, g, b, a }
28    }
29    pub const TRANSPARENT: Color = Color::rgba(0, 0, 0, 0);
30    pub const WHITE: Color = Color::rgb(255, 255, 255);
31    pub const GRAY: Color = Color::rgb(128, 128, 128);
32
33    /// Dim toward transparency (the off-trace fade — mirrors `graph_render::dim`).
34    pub fn dim(self, k: f32) -> Color {
35        Color::rgba(self.r, self.g, self.b, (self.a as f32 * k) as u8)
36    }
37}
38
39impl From<egui::Color32> for Color {
40    fn from(c: egui::Color32) -> Self {
41        let [r, g, b, a] = c.to_srgba_unmultiplied();
42        Color { r, g, b, a }
43    }
44}
45
46impl From<Color> for egui::Color32 {
47    fn from(c: Color) -> Self {
48        egui::Color32::from_rgba_unmultiplied(c.r, c.g, c.b, c.a)
49    }
50}
51
52/// A 2D point in world space (caller-owned layout coordinates).
53#[derive(Clone, Copy, Debug, PartialEq)]
54pub struct Pos {
55    pub x: f32,
56    pub y: f32,
57}
58
59impl Pos {
60    pub const fn new(x: f32, y: f32) -> Self {
61        Self { x, y }
62    }
63}
64
65/// Default node chip size in world units (matches nornir's arch board:
66/// `BOX_W`/`BOX_H`), before any pan/zoom transform.
67pub const BOX_W: f32 = 184.0;
68pub const BOX_H: f32 = 34.0;
69
70/// One laid-out node: stable id, label, chip fill + stroke (the *kind* colour,
71/// caller's choice), and its world-space centre.
72#[derive(Clone, Debug)]
73pub struct GraphNode {
74    pub id: String,
75    pub label: String,
76    pub fill: Color,
77    pub stroke: Color,
78    pub pos: Pos,
79}
80
81/// One edge: endpoints by node id, colour, a `dashed` flag, and an optional
82/// mid-edge label (a cut rationale).
83#[derive(Clone, Debug)]
84pub struct GraphEdge {
85    pub from: String,
86    pub to: String,
87    pub color: Color,
88    pub dashed: bool,
89    pub label: Option<String>,
90}
91
92/// The full graph to paint — nodes (laid out) + edges.
93#[derive(Clone, Debug, Default)]
94pub struct GraphModel {
95    pub nodes: Vec<GraphNode>,
96    pub edges: Vec<GraphEdge>,
97}
98
99impl GraphModel {
100    /// World-space bounding box of all node chips `(min_x, min_y, max_x, max_y)`,
101    /// chip extents included. Used to fit the camera. `None` if empty.
102    pub fn world_bounds(&self) -> Option<(f32, f32, f32, f32)> {
103        let mut it = self.nodes.iter();
104        let first = it.next()?;
105        let (hw, hh) = (BOX_W * 0.5, BOX_H * 0.5);
106        let mut b = (first.pos.x - hw, first.pos.y - hh, first.pos.x + hw, first.pos.y + hh);
107        for n in it {
108            b.0 = b.0.min(n.pos.x - hw);
109            b.1 = b.1.min(n.pos.y - hh);
110            b.2 = b.2.max(n.pos.x + hw);
111            b.3 = b.3.max(n.pos.y + hh);
112        }
113        Some(b)
114    }
115}
116
117/// A per-node decoration layered over the base chip: an optional status **ring**
118/// colour (drawn outside the kind stroke), an optional **badge** (a short glyph/text
119/// at the chip's top-right corner), and an optional **scale** — a multiplier on the
120/// node's marker radius so a caller can size nodes by an importance metric
121/// (population, degree, …) without the engine learning what the metric means. The
122/// L0 lowering reads `scale` (default `1.0`) when it sizes the node marker.
123#[derive(Clone, Debug, Default)]
124pub struct NodeDecoration {
125    pub ring: Option<Color>,
126    pub badge: Option<String>,
127    pub badge_color: Option<Color>,
128    /// Marker-radius multiplier (`None`/`1.0` = the default chip size). Domain-
129    /// agnostic node sizing (e.g. kommun population, node degree).
130    pub scale: Option<f32>,
131}
132
133/// The **caller-supplied** overlay layer (domain-agnostic). Per-node rings/badges
134/// keyed by node id, plus extra emphasis edges painted on top (e.g. a cycle's
135/// suggested cut). Empty = no overlay.
136#[derive(Clone, Debug, Default)]
137pub struct Decorations {
138    /// node id -> its ring/badge overlay.
139    pub nodes: std::collections::HashMap<String, NodeDecoration>,
140    /// Extra emphasis edges painted ON TOP of the base edges (the cut lines).
141    pub edges: Vec<GraphEdge>,
142}
143
144/// The camera transform: pan + zoom over the world. World point `p` projects to
145/// screen as `center + pan + p * zoom` (the same affine nornir's `draw_graph`
146/// applies). Owned by the caller so navigation survives across frames.
147#[derive(Clone, Copy, Debug)]
148pub struct Camera {
149    pub pan_x: f32,
150    pub pan_y: f32,
151    pub zoom: f32,
152}
153
154impl Default for Camera {
155    fn default() -> Self {
156        Self { pan_x: 0.0, pan_y: 0.0, zoom: 1.0 }
157    }
158}
159
160impl Camera {
161    /// A camera that fits `model`'s world bounds into a `w × h` viewport with a
162    /// margin. The "⊙ fit" button, computed once instead of by trial pan/zoom.
163    pub fn fit(model: &GraphModel, w: f32, h: f32, margin: f32) -> Camera {
164        let Some((min_x, min_y, max_x, max_y)) = model.world_bounds() else {
165            return Camera::default();
166        };
167        let (bw, bh) = ((max_x - min_x).max(1.0), (max_y - min_y).max(1.0));
168        let zoom = ((w - 2.0 * margin) / bw).min((h - 2.0 * margin) / bh).clamp(0.05, 4.0);
169        // Pan so the world-bounds centre lands at the viewport centre.
170        let (cx, cy) = ((min_x + max_x) * 0.5, (min_y + max_y) * 0.5);
171        Camera { pan_x: w * 0.5 - cx * zoom, pan_y: h * 0.5 - cy * zoom, zoom }
172    }
173
174    /// Project a world point to screen pixels.
175    #[inline]
176    pub fn project(&self, p: Pos) -> (f32, f32) {
177        (p.x * self.zoom + self.pan_x, p.y * self.zoom + self.pan_y)
178    }
179}
facett_graphview/model.rs

facett_graphview/
model.rs
