Refactor type system of items

[AzurIce]

Note

Latest thinking: #154 (comment)

Problem

The items we used in programmatic animation engine often involve subtypes and supertypes.

For example, an Sphere is actually expressed with a Surface, while a Surface is actually a MeshItem.

In OOP languages, this is often described with inheriting, but Rust is not OOP.
So, instead, in ranim-items, this is expressed by using From/Into conversions:

graph LR
    Square --> Rectangle
    Square --> RegularPolygon
    Square --> Parallelogram
    Rectangle --> Parallelogram
    Rectangle --> Polygon
    Parallelogram --> Polygon
    RegularPolygon --> Polygon
    
    Circle --> Ellipse
    Circle --> Arc
    Circle --> EllipticArc
    Ellipse --> EllipticArc
    Arc --> EllipticArc
    ArcBetweenPoints --> Arc
    
    Polygon --> VItem
    Parallelogram --> VItem
    EllipticArc --> VItem
    Ellipse --> VItem
    Arc --> VItem
    Circle --> VItem
    Line --> VItem
    Square --> VItem
    Rectangle --> VItem
    
    VItem --> CoreVItem
    
    Sphere --> Surface
    Surface --> MeshItem
    MeshItem --> CoreMeshItem
    
    TextItem --> VecVItem
    TypstText --> VecVItem
    SvgItem --> VecVItem -.- VItem

Loading

All item types are individual, flattened structs with From/Into impls to convert from subtypes to supertypes semantically.

1. Massive boilerplate

VItems like Arc, Circle, Ellipse all share the same fields (basis, fill_rgba, stroke_rgba, stroke_width) and the same trait impls (FillColor, StrokeColor, Opacity, ShiftTransform, etc.). Each type must redeclare these fields and re-derive/re-impl the same traits, plus all the From/Into and Extract logic.

2. Missing interpolation levels

All items can only interpolate with themselves at the low-level point data (VPointVec). There is no parameter-level interpolation (e.g., interpolating radius or angle directly).

3. Tedious type conversions

Subtype → supertype requires manually implementing a large number of From/Into conversions.

4. Atomic vs. Compound items at the same level

Some items convert 1:1 into a CoreItem (e.g., VItem), while others produce multiple CoreItems via Extract (e.g., TextItem, TypstText, SvgItem). These are conceptually different levels of abstraction but are treated at the same level in the current design.

[AzurIce]

Initial ideas

A. Generic wrapper VItem<T>

The main difference between Arc, Circle, Ellipse, etc. is the VPointVec they finally generate — they use different data and methods. The shared fields (basis, fill_rgba, stroke_rgba, stroke_width) have the same behavior across types.

So, it can be something like:

pub struct VItem<T = VPointVec> {
    pub transform: DMat4,
    inner: T,
    /// stroke widths
    pub stroke_widths: PointVec<Width>,
    /// stroke rgbas
    pub stroke_rgbas: PointVec<Rgba>,
    /// fill rgbas
    pub fill_rgbas: PointVec<Rgba>,
}

This also enables both points interpolation (low-level data) and parameter interpolation (high-level data).

B. ECS-like compile time bundle

pub trait Has<T: Component> {
    fn get(&self) -> &T::Data;
    fn get_mut(&mut self) -> &mut T::Data;
}

pub trait Component {
    type Data;
}

pub struct FillRgba;
impl Component for FillRgba {
    type Data = PointVec<Rgba>;
}

pub struct VItem {
    // ...
    pub stroke_widths: FillRgba::Data,
}

// Can be done with macros.
impl Has<FillRgba> for VItem {
    // ...
}

Then can constrain anim requirements or provide auto trait impls through Has<T>. But still has some limit.

For example Opacity should operate on both FillRgba and StrokeRgba, but some type may only have one of them, and it will be hard to provide auto trait impls for them, because T: Has<FillRgba> overlaps with T: Has<FillRgba> + Has<StrokeRgba>.

[AzurIce]

A big question is that should we introduce model coordinate? This might lead to a huge burden on User's side.

[AzurIce]

Further analysis on VItem<T> approach

The transform dilemma

The parameterized construction process is essentially a function $f: A \to B$ (params → point data). Transform is another function $g$. This creates two possible paths:

• A → A' → B' (transform params, then generate): Intuitive API (e.g., Line { start, end } where shift modifies start/end directly), but each type needs custom transform-to-parameter mapping — brings back boilerplate.
• A → B → B' (generate, then apply transform matrix): Unified transform on VItem<T>, but operations like put_start_and_end_on require coordinate space conversions. Inverting $f$ is generally hard.

Different T types relate to transform differently

T type	World coords in params?	Needs transform to generate points?
VPointVec	Yes (points are world coords)	No
Line { start, end }	Yes	No
Circle { radius }	No	Yes (needs basis to project into 3D)

This means transform cannot be simply unified at the VItem<T> level — for Line, transform is redundant (params are already world coords); for Circle, transform is a necessary input for point generation.

Conclusion: A → A' → B' path + style unification

• Style fields (fill, stroke, width) are easy to unify → lift into VItem<T> outer layer with blanket trait impls.
• Transform is hard to unify → don't force it. Each T defines its own transform-related data as needed. The transform field on VItem<T> serves primarily as projection plane tracking (for rendering), not as a general model→world transform.
• Transform methods dispatch to both layers: outer transform field (projection plane tracking) + inner T (parameter modification as needed).

pub struct VItem<T = VPointVec> {
    pub transform: DMat4,  // projection plane tracking
    inner: T,
    pub stroke_widths: PointVec<Width>,
    pub stroke_rgbas: PointVec<Rgba>,
    pub fill_rgbas: PointVec<Rgba>,
}

impl<T: /* TransformTrait */> /* TransformTrait */ for VItem<T> {
    fn /* transform_method */(&mut self) {
        self.transform./* update projection plane */();
        self.inner./* update params as needed */();
    }
}

About Basis2d

The projection plane tracking data is essentially a plane definition. Since reconstructing 3D coordinates doesn't require a specific orthonormal basis (any basis on the same plane works), a normal vector + first point is sufficient — Basis2d may be simplifiable.

Related issues

This design also addresses:

• Better Scale API design #122 (Scale API): Transform trait on T defines what transforms each type supports
• Better transform traits system design #130 (Transform trait system): Two-layer dispatch (outer transform + inner params) simplifies the trait hierarchy
• Billboard Support for vitem #152, Anim composition #153: Unified VItem<T> makes animation composition easier

[AzurIce]

VItem<T> is not very good, it introduces an extra layer and complexity. Still need further consideration.

[AzurIce]

Thinking about composing items directly in fields:

// #[derive(Item)]
pub struct Arc {
    pub center: DVec3,
    pub start_dir: DVec3,
    pub radius: f64,
    pub angle: f64
    // #[item]
    inner: VItem
}

impl Item for Arc {
    fn bake(&mut self) {
        // update self.inner
    }
    fn extract(&self) -> Vec<CoreItem> {
        vec![
            self.inner.clone()
        ]
    }
}

// #[derive(Item)]
pub struct Circle {
    pub center: DVec3,
    pub radius: f64,
    // #[item]
    inner: Arc,
}

impl Item for Circle {
    fn bake(&mut self) {
        // update self.inner
    }
    fn extract(&self) -> Vec<CoreItem> {
        self.inner.extract()
    }
}