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::core_item::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/extraction 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; 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). The same placement Extract composes into core items. 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<Target = CoreItem>, G: Clone + Into<DAffine3>,

type Target = CoreItem

Extraction target.

fn extract_into(&self, buf: &mut Vec<Self::Target>)

Append extracted values to buf.

fn extract(&self) -> Vec<Self::Target>

Extract into a newly allocated vector.

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