Struct Node 

pub struct Node<I, G = DAffine3> {
    pub id: Option<String>,
    pub item: Option<I>,
    pub children: Vec<Transformed<Node<I, G>, G>>,
}

A node of a scene-graph tree: pure structure — an external id, an optional payload, and a list of placed children.

Placement is not stored on the node: each child sits inside a [Transformed] wrapper carrying its local-to-parent transform, so the doctrine “placement lives in Transformed only” holds for trees too. All pose algebra (composition, lerp, AABB corners, widening, root posing) comes from [Transformed]’s own implementations instead of being duplicated here, and a whole tree is placed by wrapping it: Transformed::new(tree, pose) or tree.transformed(pose).

This is the same division as reading a glTF scene structurally: the node’s name/mesh map to the payload and id, while its matrix|TRS maps to the wrapper around the node.

Examples

Build trees with Node::leaf, Node::group, Node::branch, and the builders; place a child with transformed:

use ranim_core::transformed::TransformedExt;
use ranim_core::glam::dvec3;
use ranim_core::traits::Translation;
use ranim_items::hierarchy::Node;

let tree = Node {
    id: Some("outer".into()),
    item: None,
    children: vec![
        Node::leaf("geometry".to_string())
            .transformed(Translation(dvec3(1.0, 0.0, 0.0))),
    ],
};
assert_eq!(tree.children[0].inner.item(), Some(&"geometry".to_string()));

Fields

id: Option<String>

External identifier carried from the source format (e.g. SVG element id, glTF node name). Ignored by rendering beyond being transported: alignment preserves it, and lerping switches ids at the mid-point exactly like other front-loaded fields in ranim.

item: Option<I>

The payload carried by this node, in canonical local coordinates.

children: Vec<Transformed<Node<I, G>, G>>

The placed child nodes, living in this node’s local space. Stored in source order; render extraction preserves that order depth-first so downstream consumers see painter’s-algorithm ordering, and a node’s own payload paints before its descendants.

Implementations

impl<I, G> Node<I, G>

pub fn new(item: Option<I>, children: Vec<Transformed<Self, G>>) -> Self

Pair a payload (if any) with placed children, without an external id.

pub fn with_id(self, id: impl Into<String>) -> Self

Attach an external id, consuming and returning the node.

pub fn is_leaf(&self) -> bool

Whether this node is a bare leaf: a payload with no children.

pub fn is_group(&self) -> bool

Whether this node is a pure frame: no payload, only (possibly empty) children.

pub fn item(&self) -> Option<&I>

The payload carried by this node, if any.

pub fn item_mut(&mut self) -> Option<&mut I>

The payload mutably, if any.

pub fn children(&self) -> &[Transformed<Self, G>]

The placed children.

pub fn children_mut(&mut self) -> &mut [Transformed<Self, G>]

The placed children mutably.

pub fn first_leaf(&self) -> Option<&I>

The first leaf payload in depth-first order, without composing any transforms. This backs the color/stroke-width getters; None means the tree has no payloads at all.

pub fn get(&self, path: &[usize]) -> Option<&Transformed<Self, G>>

Look up a placement by walking child indices: [i] returns child i (including its pose), [i, j] returns child j of child i’s frame, and so on. Paths must be non-empty — the receiver is the frame itself, not a placement — and None is returned when an index is out of bounds.

pub fn get_mut(&mut self, path: &[usize]) -> Option<&mut Transformed<Self, G>>

Mutable variant of Node::get.

pub fn by_id(&self, id: &str) -> Option<&Transformed<Self, G>>

The first placement (depth-first preorder) whose id equals id.

Ids are external labels (SVG ids, glTF node names) and are not guaranteed unique, so duplicates resolve to the preorder-first match; see Node::by_ids for every match and Node::by_id_path for a reusable address. Placements are searched, not the receiver — the receiver is the frame they live in. None when no placement carries the id.

pub fn by_id_mut(&mut self, id: &str) -> Option<&mut Transformed<Self, G>>

Mutable variant of Node::by_id.

pub fn by_ids(&self, id: &str) -> Vec<&Transformed<Self, G>>

Every placement whose id equals id, in depth-first order.

fn collect_by_id<'a>( &'a self, id: &str, matches: &mut Vec<&'a Transformed<Self, G>>, )

pub fn by_id_path(&self, id: &str) -> Option<Vec<usize>>

The index path (see Node::get) of the first placement in depth-first order whose id equals id. Useful to reuse an address across frames without re-searching.

pub fn first_leaf_mut(&mut self) -> Option<&mut I>

The first leaf payload in depth-first order, mutably.

pub fn leaves(&self) -> Leaves<'_, I, G>

where G: Clone + Into<DAffine3>,

Iterate over flattened leaf payloads with their accumulated world affine, yielding (world_affine, &item) pairs in depth-first order — i.e. painter’s-algorithm draw order.

The world affine composes top-down through every placement’s transform, starting from the identity at the receiver: the receiver is an unplaced frame, so wrapping the tree in [Transformed] places it (see PlacedLeaves). Render extraction composes the same placement into typed frame entries. Implemented with an explicit stack, so deep trees cannot overflow the call stack.

pub fn leaves_mut(&mut self) -> LeavesMut<'_, I, G>

Iterate over mutable references to all leaf payloads in depth-first order. Unlike Node::leaves, no transforms are composed: callers mutate canonical local data only.

pub fn map_inner<U>(self, f: impl FnMut(I) -> U) -> Node<U, G>

Map every leaf payload to a new type, keeping ids, poses, and the tree shape unchanged. This is the recursive analog of [Transformed::map_inner].

pub fn map_transform<H>(self, f: impl FnMut(G) -> H) -> Node<I, H>

Map the transform storage of every placement to a new type while keeping everything else unchanged. This mirrors [Transformed::map_transform] and is the general form of converting between transform groups — including widening, which intentionally has no blanket From impl on Node.

impl<I, G: TransformGroup> Node<I, G>

pub fn leaf(item: I) -> Self

Create a bare leaf — a payload with no children — without an id.

pub fn group( children: impl IntoIterator<Item = impl Into<Transformed<Self, G>>>, ) -> Self

Create a pure frame — no payload — holding the placed children. Plain nodes passed in the iterator place with the identity pose.

pub fn branch( item: I, children: impl IntoIterator<Item = impl Into<Transformed<Self, G>>>, ) -> Self

Create a branch — a payload and placed children — without an id. The payload paints before the children. Plain nodes passed in the iterator place with the identity pose.

pub fn frame() -> Self

Create an empty pure anchor frame: no payload, no children.

Trait Implementations

impl<I, G> Aabb for Node<I, G>

where I: Aabb, G: Clone + Into<DAffine3>,

fn aabb(&self) -> [DVec3; 2]

Union of the payload’s and the placed children’s AABBs — each placement’s wrapper already applies its own pose, so the result is in the receiver’s local frame. A node with no payload and no children warns and reports a degenerate box, mirroring the slice impl in ranim-core.

fn aabb_size(&self) -> DVec3

Get the size of the Aabb.

fn aabb_center(&self) -> DVec3

Get the center of the Aabb.

impl<I, G> Alignable for Node<I, G>

where I: Alignable + Opacity, G: Clone,

fn is_aligned(&self, other: &Self) -> bool

Whether both sides are already structurally compatible for direct interpolation: payload presence must match positionally, sibling counts must be equal, and every payload and child pair must satisfy [Alignable::is_aligned]. This mirrors the Vec<T> blanket’s pre-alignment contract; [Alignable::align_with] establishes this state from mismatched trees.

fn align_with(&mut self, other: &mut Self)

Align two trees for interpolation under one uniform rule: absence is filled with a transparent clone of the present side.

1. Payload presence: when only one side carries an item, the other side receives a transparent (set_opacity(0.0)) clone of it, so lerping fades the payload in or out smoothly instead of jumping.
2. Payload pairs: when both sides carry items, they align with each other (vertex-level padding for point data).
3. Children: unequal child counts are padded on both sides. A non-empty list grows by repeating its own entries (resize_preserving_order_with_repeated_indices, matching the Vec<T>: Alignable blanket); an empty list has nothing of its own to repeat, so it grows with transparent clones of the other side’s children — the same absence rule as payloads. Pairs recurse.

impl<I: Clone, G: Clone> Clone for Node<I, G>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<I: Debug, G: Debug> Debug for Node<I, G>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<I, G> Empty for Node<I, G>

where I: Empty,

fn empty() -> Self

Getting an empty item

impl<I: Eq, G: Eq> Eq for Node<I, G>

impl<I, G> Extract for Node<I, G>

where I: Extract, G: Clone + Into<DAffine3>,

Available on crate feature render only.

fn extract(&self, ctx: &mut ExtractContext<'_>)

Synchronize this value’s render-world outputs.

impl<I, G> FillColor for Node<I, G>

where I: FillColor,

fn fill_color(&self) -> AlphaColor<Srgb>

The fill color of the first leaf in DFS order; an empty tree warns and reports white.

fn set_fill_color(&mut self, color: AlphaColor<Srgb>) -> &mut Self

Setting fill color(rgba) of an item

fn set_fill_opacity(&mut self, opacity: f32) -> &mut Self

Setting fill opacity of an item

impl<I, G: TransformGroup> From<Node<I, G>> for Transformed<Node<I, G>, G>

A bare Node places with the identity pose, so plain and wrapped nodes mix freely in the same vec![...] of children.

fn from(inner: Node<I, G>) -> Self

Converts to this type from the input type.

impl<I, G> Interpolatable for Node<I, G>

where I: Interpolatable, G: Interpolatable,

fn lerp(&self, target: &Self, t: f64) -> Self

Structural lerp: nodes interpolate positionally, payloads and node poses interpolate independently, and ids switch at the mid-point like other front-loaded fields in ranim. Callers must have aligned structures first (see [Alignable]): payload-presence mismatches panic, and unequal sibling counts follow Vec’s truncating-zip precedent.

impl<I, G> Locate<Node<I, G>> for Centroid

where Centroid: Locate<I>, G: Clone + Into<DAffine3>,

The centroid of a tree weights every flattened leaf equally: sum each leaf’s centroid mapped through its accumulated world affine and divide by the leaf count — NOT per-child weighting. An empty tree warns and returns zero instead of producing NaNs.

fn locate(&self, target: &Node<I, G>) -> DVec3

Locate self on the target

impl<I, G> Opacity for Node<I, G>

where I: Opacity,

fn set_opacity(&mut self, opacity: f32) -> &mut Self

Setting opacity of an item

impl<I, G> Partial for Node<I, G>

where I: Partial, G: Clone,

fn get_partial(&self, range: Range<f64>) -> Self

Getting a partial item

fn get_partial_closed(&self, range: Range<f64>) -> Self

Getting a partial item closed

impl<I: PartialEq, G: PartialEq> PartialEq for Node<I, G>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<I, G> StrokeColor for Node<I, G>

where I: StrokeColor,

fn stroke_color(&self) -> AlphaColor<Srgb>

The stroke color of the first leaf in DFS order; an empty tree warns and reports white.

fn set_stroke_color(&mut self, color: AlphaColor<Srgb>) -> &mut Self

Setting stroke color(rgba) of an item

fn set_stroke_opacity(&mut self, opacity: f32) -> &mut Self

Setting stroke opacity of an item

impl<I, G> StrokeWidth for Node<I, G>

where I: StrokeWidth,

fn stroke_width(&self) -> f32

The stroke width of the first leaf in DFS order; an empty tree warns and reports 0.0.

fn apply_stroke_func( &mut self, f: impl for<'a> Fn(&'a mut [Width]), ) -> &mut Self

Forward the stroke-width function to every leaf independently.

fn set_stroke_width(&mut self, width: f32) -> &mut Self

Setting stroke width of an item