codimate 0.1.2__tar.gz → 0.1.4__tar.gz

{codimate-0.1.2 → codimate-0.1.4}/Cargo.lock

@@ -217,7 +217,7 @@ dependencies = [
 
 [[package]]
 name = "codimate-py"
-version = "0.1.2"
+version = "0.1.4"
 dependencies = [
  "codimate-animation",
  "codimate-core",
@@ -236,6 +236,8 @@ dependencies = [
  "codimate-core",
  "codimate-math",
  "codimate-render",
+ "jpeg-decoder",
+ "png",
 ]
 
 [[package]]
@@ -586,6 +588,15 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "jpeg-decoder"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00810f1d8b74be64b13dbf3db89ac67740615d6c891f0e7b6179326533011a07"
+dependencies = [
+ "rayon",
+]
+
 [[package]]
 name = "jpeg-encoder"
 version = "0.6.1"

{codimate-0.1.2 → codimate-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codimate
-Version: 0.1.2
+Version: 0.1.4
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Multimedia :: Video
@@ -182,7 +182,9 @@ scene.circle(name, r=, at=)
 scene.text(name, content, size=, at=)
 scene.polygon(name, points)                             # cm.ngon, cm.star
 scene.curve(name, points, w=)                           # smooth, through the points
+scene.arc(name, r=, sweep=(0, 120))                     # an arc, a dial, a pie slice
 scene.svg(name, "logo.svg", size=)                       # vector art, as real geometry
+scene.image(name, "photo.jpg", size=)                    # a picture: PNG or JPEG
 scene.line(name, start=slot_or_point, end=slot_or_point, w=)
 scene.formula(name, r"\frac{a}{b}", size=, at=)         # LaTeX, needs `typst`
 cm.measure(text, size) -> (w, h)                        # to size a box around text

{codimate-0.1.2 → codimate-0.1.4}/README.md

@@ -170,7 +170,9 @@ scene.circle(name, r=, at=)
 scene.text(name, content, size=, at=)
 scene.polygon(name, points)                             # cm.ngon, cm.star
 scene.curve(name, points, w=)                           # smooth, through the points
+scene.arc(name, r=, sweep=(0, 120))                     # an arc, a dial, a pie slice
 scene.svg(name, "logo.svg", size=)                       # vector art, as real geometry
+scene.image(name, "photo.jpg", size=)                    # a picture: PNG or JPEG
 scene.line(name, start=slot_or_point, end=slot_or_point, w=)
 scene.formula(name, r"\frac{a}{b}", size=, at=)         # LaTeX, needs `typst`
 cm.measure(text, size) -> (w, h)                        # to size a box around text

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-core/src/scene/mod.rs

@@ -27,7 +27,7 @@ pub use connection::{connection, Connection};
 pub use path::{path_node, ConcretePath, PathNode};
 pub use primitive::{
     primitive_circle, primitive_path, primitive_rect, primitive_text, ConcreteGeometry,
-    ConcretePrimitive, Geometry, Primitive, Transformable,
+    ConcretePrimitive, Geometry, Pixels, Primitive, Transformable,
 };
 pub use pulse::{pulse_on, Pulse};
 pub use rect::{rect, ConcreteRect, Rect};

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-core/src/scene/primitive.rs

@@ -34,6 +34,36 @@ pub enum Geometry {
         font_size: Animated<f32>,
         align: TextAlign,
     },
+    /// A decoded raster picture, drawn into a box (ADR 0013).
+    ///
+    /// The pixels are shared rather than owned: a 1,200-frame render resolves
+    /// this once per frame, and copying a megabyte each time would be the
+    /// whole cost of the feature.
+    Image {
+        pixels: std::sync::Arc<Pixels>,
+        width: Animated<f32>,
+        height: Animated<f32>,
+    },
+}
+
+/// Decoded pixels: premultiplied RGBA, ready to blit.
+///
+/// Core does no decoding — it would need a codec and an opinion about file
+/// formats, and neither belongs in the layer that owns no I/O. Something
+/// upstream hands these over already decoded.
+#[derive(Clone, PartialEq)]
+pub struct Pixels {
+    pub width: u32,
+    pub height: u32,
+    pub rgba: Vec<u8>,
+}
+
+// Dimensions only. The derived version would print several megabytes of
+// channel bytes the first time anyone put a Scene in a debug log.
+impl std::fmt::Debug for Pixels {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Pixels({}x{})", self.width, self.height)
+    }
 }
 
 /// A `Geometry` resolved at a specific `t` — plain shape data, still local-space.
@@ -54,6 +84,11 @@ pub enum ConcreteGeometry {
         font_size: f32,
         align: TextAlign,
     },
+    Image {
+        pixels: std::sync::Arc<Pixels>,
+        width: f32,
+        height: f32,
+    },
 }
 
 impl Geometry {
@@ -110,6 +145,7 @@ impl Geometry {
                 }
             }
             Geometry::Text { .. } => Vec2::new(0.0, 0.0),
+            Geometry::Image { .. } => Vec2::new(0.0, 0.0),
         }
     }
 
@@ -134,10 +170,34 @@ impl Geometry {
                 font_size: font_size.resolve(t),
                 align: *align,
             },
+            Geometry::Image {
+                pixels,
+                width,
+                height,
+            } => ConcreteGeometry::Image {
+                pixels: pixels.clone(),
+                width: width.resolve(t),
+                height: height.resolve(t),
+            },
         }
     }
 
     pub(crate) fn ease_with(self, curve: super::TimeCurve) -> Self {
+        // An image eases by its box; the pixels are the same pixels whatever
+        // the time is.
+        if let Geometry::Image {
+            pixels,
+            width,
+            height,
+        } = self
+        {
+            let width_curve = curve.clone();
+            return Geometry::Image {
+                pixels,
+                width: Animated::new(move |t| width.resolve(width_curve(t))),
+                height: Animated::new(move |t| height.resolve(curve(t))),
+            };
+        }
         match self {
             Geometry::Circle { radius } => Geometry::Circle {
                 radius: Animated::new(move |t| radius.resolve(curve(t))),
@@ -164,6 +224,9 @@ impl Geometry {
                     align,
                 }
             }
+            // Handled above, before the match, because it needs to move its
+            // Arc rather than borrow it.
+            Geometry::Image { .. } => unreachable!("eased before the match"),
         }
     }
 
@@ -239,6 +302,7 @@ impl Geometry {
             Geometry::Rect { .. } => "Rect",
             Geometry::Path { .. } => "Path",
             Geometry::Text { .. } => "Text",
+            Geometry::Image { .. } => "Image",
         }
     }
 }

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-py/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codimate-py"
-version = "0.1.2"
+version = "0.1.4"
 edition = "2021"
 
 [lib]

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-reconcile/Cargo.toml

@@ -8,3 +8,9 @@ codimate-core = { path = "../codimate-core" }
 codimate-animation = { path = "../codimate-animation" }
 codimate-math = { path = "../codimate-math" }
 codimate-render = { path = "../codimate-render" }
+
+# Decoding an imported picture (ADR 0013). `png` is already in the workspace;
+# `jpeg-decoder` is the one dependency added purely for a feature, because
+# photographs are JPEG and `jpeg-encoder` next door only writes them.
+png = "0.18"
+jpeg-decoder = "0.3"

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-reconcile/src/lib.rs

@@ -17,7 +17,7 @@ use std::sync::{Arc, Mutex, OnceLock};
 use codimate_animation::Playable;
 use codimate_core::{
     scene::AnchorKind, scene::Transformable, tween, Animated, Color, ConcreteScene, Geometry,
-    IntoAnimated, Path, Primitive, Scene, Segment, Style, TextAlign, Vec2,
+    IntoAnimated, Path, Pixels, Primitive, Scene, Segment, Style, TextAlign, Vec2,
 };
 
 /// Why a Scene could not be built.
@@ -85,8 +85,8 @@ pub struct Shape {
 
 /// Every `kind` Python may send. An unknown kind is a Python `ValueError`,
 /// never a silently missing shape.
-pub const KINDS: [&str; 8] = [
-    "rect", "circle", "text", "line", "formula", "polygon", "curve", "svg",
+pub const KINDS: [&str; 10] = [
+    "rect", "circle", "text", "line", "formula", "polygon", "curve", "svg", "image", "arc",
 ];
 
 /// A rectangle with rounded corners, in local space, centred on the anchor.
@@ -235,6 +235,79 @@ fn curve_path(s: &Shape) -> Path {
     Path { segments, closed }
 }
 
+/// How many cubics an arc is built from, whatever it sweeps.
+///
+/// Fixed rather than "one per 90 degrees", because two arcs only tween if they
+/// have the same path structure — the rule `polygon` follows for corners. A
+/// fixed count is what lets a pie fill or an angle mark grow smoothly, which is
+/// the whole reason this kind exists rather than a `curve` through points on a
+/// circle. Eight keeps every span under 45 degrees even at a full turn, where
+/// the cubic approximation is good to a few thousandths of a radius.
+const ARC_SPANS: usize = 8;
+
+/// An arc or a sector in local space.
+///
+/// `w`/`h` are the bounding box, so an ellipse costs nothing extra; `x2`/`y2`
+/// are the start and end angle in degrees; `r` above zero closes it back to the
+/// centre, making a pie slice rather than an open curve.
+///
+/// Angles run clockwise from twelve o'clock, matching `cm.ngon`, whose first
+/// corner also points straight up.
+/// The same arc, from plain numbers — so the tween can interpolate the
+/// *angles* and build a true arc at every instant.
+///
+/// Interpolating the path's control points instead looks right for an open
+/// arc and is wrong for a sector: halfway between a collapsed slice and a
+/// 300-degree one is not a 150-degree slice, it is a self-crossing shape that
+/// fills as a sliver and a half-disc. Caught by rendering one.
+fn arc_at(rx: f32, ry: f32, from_deg: f32, to_deg: f32, sector: bool) -> Path {
+    // Screen y grows downward, so subtracting a quarter turn puts zero at the
+    // top and makes a rising angle read as clockwise.
+    let at = |deg: f32| {
+        let a = deg.to_radians() - std::f32::consts::FRAC_PI_2;
+        (Vec2::new(rx * a.cos(), ry * a.sin()), a)
+    };
+
+    let (start, theta0) = at(from_deg);
+    let (_, theta1) = at(to_deg);
+    let step = (theta1 - theta0) / ARC_SPANS as f32;
+    // The classic cubic fit to a circular span: exact at both ends and at the
+    // midpoint, which is why the error stays small for spans under a quarter
+    // turn.
+    let k = 4.0 / 3.0 * (step / 4.0).tan();
+
+    let mut segments = Vec::with_capacity(ARC_SPANS + 3);
+    if sector {
+        segments.push(Segment::MoveTo(Vec2::new(0.0, 0.0)));
+        segments.push(Segment::Line(Vec2::new(0.0, 0.0), start));
+    } else {
+        segments.push(Segment::MoveTo(start));
+    }
+
+    let mut from = start;
+    let mut a = theta0;
+    for _ in 0..ARC_SPANS {
+        let b = a + step;
+        let to = Vec2::new(rx * b.cos(), ry * b.sin());
+        // The tangent at each end, scaled by the span — the control points sit
+        // along it, which is what keeps the join smooth.
+        let c1 = Vec2::new(from.x - k * rx * a.sin(), from.y + k * ry * a.cos());
+        let c2 = Vec2::new(to.x + k * rx * b.sin(), to.y - k * ry * b.cos());
+        segments.push(Segment::Cubic(from, c1, c2, to));
+        from = to;
+        a = b;
+    }
+
+    if sector {
+        segments.push(Segment::Line(from, Vec2::new(0.0, 0.0)));
+    }
+
+    Path {
+        segments,
+        closed: sector,
+    }
+}
+
 /// A line in local space: from the anchor to the far end.
 fn line_path(s: &Shape) -> Path {
     Path {
@@ -272,6 +345,29 @@ impl Shape {
                 }
             }
 
+            // The angles tween, and the arc is rebuilt at every instant — so
+            // a dial sweeps and a pie fills through shapes that are all
+            // genuinely arcs. This is the point of the kind: a `curve` through
+            // points on a circle changes its point count when the sweep
+            // changes, and then it snaps instead of sweeping.
+            "arc" => {
+                let (rx0, ry0) = (self.w / 2.0, self.h / 2.0);
+                let (rx1, ry1) = (other.w / 2.0, other.h / 2.0);
+                let (a0, b0) = (self.x2, self.y2);
+                let (a1, b1) = (other.x2, other.y2);
+                let sector = other.r > 0.0;
+                Geometry::path(Animated::new(move |t| {
+                    let mix = |x: f32, y: f32| x + (y - x) * t;
+                    arc_at(
+                        mix(rx0, rx1),
+                        mix(ry0, ry1),
+                        mix(a0, a1),
+                        mix(b0, b1),
+                        sector,
+                    )
+                }))
+            }
+
             // Same rule as a polygon: matching sample counts interpolate, and
             // otherwise the later shape stands for the whole segment.
             "curve" => {
@@ -285,7 +381,10 @@ impl Shape {
             // A formula is many glyph outlines and an imported SVG is many
             // paths, so neither can be one Geometry. `primitives()` expands
             // them; these arms are never reached.
-            "formula" | "svg" => Geometry::rect(0.0.into_animated(), 0.0.into_animated()),
+            // `primitives()` handles these three and returns before asking
+            // for a Geometry: a formula and an SVG are many, and an image can
+            // fail to decode, which this signature cannot report.
+            "formula" | "svg" | "image" => Geometry::rect(0.0.into_animated(), 0.0.into_animated()),
 
             // Square corners stay a real Rect — the common case keeps the
             // cheaper primitive and the renderer's own rectangle path.
@@ -754,6 +853,110 @@ pub fn formula_glyphs(latex: &str) -> Result<Arc<Vec<Path>>> {
     Ok(shared)
 }
 
+/// Decode, premultiply and cache a picture — once per path, for the life of
+/// the process.
+///
+/// Cached for the reason the formula glyphs and SVG artwork are: a 1,200-frame
+/// render must not decode the same megabyte 1,200 times. As with those, it
+/// also means editing the file mid-session and re-rendering shows the old
+/// picture.
+fn image_pixels(file: &str) -> Result<Arc<Pixels>> {
+    static CACHE: OnceLock<Mutex<HashMap<String, Arc<Pixels>>>> = OnceLock::new();
+    let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
+
+    if let Some(hit) = cache.lock().unwrap().get(file) {
+        return Ok(hit.clone());
+    }
+
+    let bytes = std::fs::read(file)
+        .map_err(|e| Error(format!("could not read the image {file:?}: {e}")))?;
+
+    // By content, not by extension: a `.png` that is really a JPEG is a
+    // mistake worth surviving, and the magic numbers are unambiguous.
+    let decoded = if bytes.starts_with(&[0x89, b'P', b'N', b'G']) {
+        decode_png(&bytes)
+    } else if bytes.starts_with(&[0xFF, 0xD8]) {
+        decode_jpeg(&bytes)
+    } else {
+        return Err(Error(format!(
+            "{file:?} is not a PNG or a JPEG — those are the two Codimate reads"
+        )));
+    }
+    .map_err(|m| Error(format!("could not read the image {file:?}: {m}")))?;
+
+    let shared = Arc::new(decoded);
+    cache
+        .lock()
+        .unwrap()
+        .insert(file.to_string(), shared.clone());
+    Ok(shared)
+}
+
+/// Straight RGBA to premultiplied, which is what tiny-skia blits.
+fn premultiplied(width: u32, height: u32, rgba: Vec<u8>) -> Pixels {
+    let mut rgba = rgba;
+    for px in rgba.chunks_exact_mut(4) {
+        let a = px[3] as u32;
+        if a == 255 {
+            continue;
+        }
+        for c in 0..3 {
+            px[c] = ((px[c] as u32 * a + 127) / 255) as u8;
+        }
+    }
+    Pixels {
+        width,
+        height,
+        rgba,
+    }
+}
+
+fn decode_png(bytes: &[u8]) -> std::result::Result<Pixels, String> {
+    let mut decoder = png::Decoder::new(std::io::Cursor::new(bytes));
+    // Normalise greyscale, palette and 16-bit down to 8-bit colour, and expand
+    // transparency into a real alpha channel, so the rest of this sees one
+    // layout instead of six.
+    decoder.set_transformations(
+        png::Transformations::normalize_to_color8() | png::Transformations::ALPHA,
+    );
+    let mut reader = decoder.read_info().map_err(|e| e.to_string())?;
+    let mut buffer = vec![0; reader.output_buffer_size().unwrap_or(0)];
+    let info = reader.next_frame(&mut buffer).map_err(|e| e.to_string())?;
+    buffer.truncate(info.buffer_size());
+
+    let rgba = match info.color_type {
+        png::ColorType::Rgba => buffer,
+        png::ColorType::GrayscaleAlpha => buffer
+            .chunks_exact(2)
+            .flat_map(|p| [p[0], p[0], p[0], p[1]])
+            .collect(),
+        other => return Err(format!("unsupported PNG colour type {other:?}")),
+    };
+    Ok(premultiplied(info.width, info.height, rgba))
+}
+
+fn decode_jpeg(bytes: &[u8]) -> std::result::Result<Pixels, String> {
+    let mut decoder = jpeg_decoder::Decoder::new(std::io::Cursor::new(bytes));
+    let pixels = decoder.decode().map_err(|e| e.to_string())?;
+    let info = decoder.info().ok_or("no JPEG header")?;
+
+    // JPEG has no alpha, so every pixel is opaque and premultiplying is a
+    // no-op — the conversion is only about layout.
+    let rgba: Vec<u8> = match info.pixel_format {
+        jpeg_decoder::PixelFormat::RGB24 => pixels
+            .chunks_exact(3)
+            .flat_map(|p| [p[0], p[1], p[2], 255])
+            .collect(),
+        jpeg_decoder::PixelFormat::L8 => pixels.iter().flat_map(|&g| [g, g, g, 255]).collect(),
+        other => return Err(format!("unsupported JPEG pixel format {other:?}")),
+    };
+    Ok(Pixels {
+        width: info.width as u32,
+        height: info.height as u32,
+        rgba,
+    })
+}
+
 /// An imported SVG, ready to draw.
 ///
 /// Paths are centred on the artwork's own bounding box and scaled so its
@@ -800,6 +1003,28 @@ fn fit_scale(art: (f32, f32), fit: (f32, f32)) -> f32 {
     by_w.min(by_h)
 }
 
+/// The size a picture is actually drawn at, fitted inside the box the author
+/// named with its aspect kept — the same rule `scene.svg` follows, so the two
+/// imports size the same way.
+fn fitted_box(pixels: &Pixels, fit: (f32, f32)) -> (f32, f32) {
+    let natural = (pixels.width.max(1) as f32, pixels.height.max(1) as f32);
+    if fit.0 <= 0.0 && fit.1 <= 0.0 {
+        return natural;
+    }
+    let by_w = if fit.0 > 0.0 {
+        fit.0 / natural.0
+    } else {
+        f32::MAX
+    };
+    let by_h = if fit.1 > 0.0 {
+        fit.1 / natural.1
+    } else {
+        f32::MAX
+    };
+    let scale = by_w.min(by_h);
+    (natural.0 * scale, natural.1 * scale)
+}
+
 /// Read, parse and normalise an SVG file — once per path, for the life of the
 /// process.
 ///
@@ -1047,6 +1272,26 @@ fn primitives(before: &Shape, after: &Shape, rules: &[Rule]) -> Result<Vec<Primi
         ));
     }
 
+    // One Geometry, not an expansion — an image is a single thing. It is here
+    // rather than in `geometry()` only because decoding can fail, and that
+    // signature has no way to say so.
+    if before.kind == "image" {
+        let pixels = image_pixels(&before.text)?;
+        let from = fitted_box(&pixels, (before.w, before.h));
+        let to = fitted_box(&pixels, (after.w, after.h));
+        return Ok(vec![Primitive::new(Geometry::Image {
+            pixels,
+            width: tween(from.0, to.0),
+            height: tween(from.1, to.1),
+        })
+        .pos(path)
+        .scale_xy(scale)
+        .rotate(spin)
+        .pivot(pivot)
+        .style(style)
+        .opacity(opacity)]);
+    }
+
     if before.kind == "svg" {
         // Same shape as a formula: one Item, many outlines, revealed left to
         // right. The difference is that the artwork brought its own colours
@@ -1234,6 +1479,9 @@ fn bounds(shape: &Shape) -> (f32, f32, f32, f32) {
         // The fitted box, not the box asked for: a wide drawing in a square
         // `size` does not fill the square, and framing the square would leave
         // the camera looking at empty air above and below.
+        "image" => image_pixels(&shape.text)
+            .map(|p| fitted_box(&p, (shape.w, shape.h)))
+            .unwrap_or((0.0, 0.0)),
         "svg" => svg_art(&shape.text)
             .map(|art| {
                 let s = fit_scale(art.size, (shape.w, shape.h));
@@ -1256,6 +1504,9 @@ fn bounds(shape: &Shape) -> (f32, f32, f32, f32) {
                 ys.iter().cloned().fold(f32::MIN, f32::max),
             );
         }
+        // The whole ellipse, not the swept part: an arc that grows would
+        // otherwise resize the camera as it sweeps.
+        "arc" => (shape.w, shape.h),
         "line" => {
             let (x0, x1) = (shape.x.min(shape.x2), shape.x.max(shape.x2));
             let (y0, y1) = (shape.y.min(shape.y2), shape.y.max(shape.y2));
@@ -1701,6 +1952,183 @@ mod tests {
         assert_ne!(start, mid, "a swap must not snap at t=0");
     }
 
+    /// An SVG on disk, because `svg_art` reads a path rather than a string —
+    /// the payload carries a file name, so the cache can key on it.
+    fn arc_path(s: &Shape) -> Path {
+        arc_at(s.w / 2.0, s.h / 2.0, s.x2, s.y2, s.r > 0.0)
+    }
+
+    fn arc_shape(r: f32, from: f32, to: f32, sector: bool) -> Shape {
+        Shape {
+            item: "arc".into(),
+            kind: "arc".into(),
+            w: r * 2.0,
+            h: r * 2.0,
+            x2: from,
+            y2: to,
+            r: if sector { 1.0 } else { 0.0 },
+            color: "white".into(),
+            opacity: 1.0,
+            ..Default::default()
+        }
+    }
+
+    /// Every point the arc visits is on the circle it claims to be — the
+    /// eight-span cubic fit is an approximation, so this is what says how good.
+    #[test]
+    fn an_arc_stays_on_its_circle() {
+        for (from, to) in [(0.0, 90.0), (0.0, 270.0), (0.0, 360.0), (45.0, -120.0)] {
+            let path = arc_path(&arc_shape(100.0, from, to, false));
+            for seg in &path.segments {
+                let ends = match *seg {
+                    Segment::Cubic(a, _, _, b) => vec![a, b],
+                    Segment::MoveTo(a) => vec![a],
+                    _ => vec![],
+                };
+                for p in ends {
+                    let radius = (p.x * p.x + p.y * p.y).sqrt();
+                    assert!(
+                        (radius - 100.0).abs() < 0.5,
+                        "{from}..{to}: a point sits at {radius}, not 100"
+                    );
+                }
+            }
+        }
+    }
+
+    /// A sector closes back to its centre and an open arc does not — the
+    /// difference between a pie slice and a curved line.
+    #[test]
+    fn a_sector_returns_to_the_centre() {
+        let open = arc_path(&arc_shape(50.0, 0.0, 120.0, false));
+        let pie = arc_path(&arc_shape(50.0, 0.0, 120.0, true));
+
+        assert!(!open.closed && pie.closed);
+        // Distance from the centre, not `x`: an arc starting at zero degrees
+        // begins at the top, where `x` is zero.
+        assert!(
+            matches!(open.segments.first(), Some(Segment::MoveTo(p)) if p.x.hypot(p.y) > 1.0),
+            "an open arc starts on its circle, not at the centre"
+        );
+        assert!(
+            matches!(pie.segments.first(), Some(Segment::MoveTo(p)) if p.x.abs() < 1e-6 && p.y.abs() < 1e-6),
+            "a pie starts at its centre"
+        );
+        assert!(
+            matches!(pie.segments.last(), Some(Segment::Line(_, p)) if p.x.abs() < 1e-6 && p.y.abs() < 1e-6),
+            "and comes back to it"
+        );
+    }
+
+    /// The reason this kind exists rather than a `curve` through points on a
+    /// circle, and the bug the first version had: halfway through a sweep the
+    /// shape must be a real arc at the halfway angle.
+    ///
+    /// Interpolating the path's control points gives a self-crossing sliver
+    /// instead, which looks fine on an open arc and obviously wrong on a pie.
+    #[test]
+    fn a_sweep_passes_through_real_arcs() {
+        let closed = arc_shape(100.0, 0.0, 0.0, true);
+        let open_to_300 = arc_shape(100.0, 0.0, 300.0, true);
+
+        let geometry = closed.geometry(&open_to_300);
+        let codimate_core::ConcreteGeometry::Path { path: halfway } = geometry.resolve(0.5) else {
+            panic!("an arc resolves to a path");
+        };
+        let expected = arc_path(&arc_shape(100.0, 0.0, 150.0, true));
+
+        let ends = |p: &Path| -> Vec<Vec2> {
+            p.segments
+                .iter()
+                .filter_map(|s| match *s {
+                    Segment::Cubic(_, _, _, b) => Some(b),
+                    _ => None,
+                })
+                .collect()
+        };
+        let (got, want) = (ends(&halfway), ends(&expected));
+        assert_eq!(got.len(), want.len());
+        for (a, b) in got.iter().zip(&want) {
+            assert!(
+                (a.x - b.x).abs() < 0.01 && (a.y - b.y).abs() < 0.01,
+                "halfway through a 0..300 sweep should be the 150 arc: {a:?} vs {b:?}"
+            );
+        }
+    }
+
+    fn svg_on_disk(name: &str, body: &str) -> String {
+        let path = std::env::temp_dir().join(format!("codimate-test-{name}.svg"));
+        std::fs::write(&path, body).expect("temp file");
+        path.to_string_lossy().into_owned()
+    }
+
+    fn svg_shape(file: &str, colour: &str, fit: (f32, f32)) -> Shape {
+        Shape {
+            item: "art".into(),
+            kind: "svg".into(),
+            x: 0.0,
+            y: 0.0,
+            w: fit.0,
+            h: fit.1,
+            text: file.into(),
+            color: colour.into(),
+            r: 1.0,
+            opacity: 1.0,
+            ..Default::default()
+        }
+    }
+
+    const TWO_SHAPES: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 50">
+        <rect x="0" y="0" width="40" height="40" fill="#ff0000"/>
+        <rect x="60" y="0" width="40" height="40" fill="#0000ff"/>
+    </svg>"##;
+
+    /// The sentinel that makes an import look like the file it came from
+    /// (ADR 0014). An empty `color` means "as authored"; anything else
+    /// flattens the drawing. If `style()` ever stopped honouring the empty
+    /// string, every import would silently go white.
+    #[test]
+    fn an_empty_colour_keeps_the_artwork_own_fills() {
+        let file = svg_on_disk("authored", TWO_SHAPES);
+
+        let as_drawn = svg_shape(&file, "", (100.0, 100.0));
+        let parts = primitives(&as_drawn, &as_drawn, &[]).expect("should expand");
+        assert_eq!(parts.len(), 2, "one primitive per path in the file");
+
+        let fills: Vec<Color> = parts.iter().map(|p| p.resolve(0.0).style.fill).collect();
+        assert!(
+            fills.iter().any(|c| c.r > 0.9 && c.b < 0.1)
+                && fills.iter().any(|c| c.b > 0.9 && c.r < 0.1),
+            "the red and the blue should both survive, got {fills:?}"
+        );
+
+        // And naming a colour overrides every path at once.
+        let flattened = svg_shape(&file, "white", (100.0, 100.0));
+        let parts = primitives(&flattened, &flattened, &[]).expect("should expand");
+        for part in &parts {
+            let fill = part.resolve(0.0).style.fill;
+            assert!(fill.r > 0.9 && fill.g > 0.9 && fill.b > 0.9, "{fill:?}");
+        }
+    }
+
+    /// `size` is a box the drawing fits inside with its aspect kept, so a wide
+    /// file in a square box does not fill the square — and `focus()` frames
+    /// what is actually drawn rather than the box that was asked for.
+    #[test]
+    fn an_import_fits_its_box_without_distorting() {
+        let file = svg_on_disk("fit", TWO_SHAPES);
+        let wide = svg_shape(&file, "", (200.0, 200.0));
+
+        let (x0, y0, x1, y1) = bounds(&wide);
+        let (w, h) = (x1 - x0, y1 - y0);
+        assert!(
+            (w - 200.0).abs() < 0.5,
+            "the long side fills the box, got {w}"
+        );
+        // The artwork is 100x40 of drawn content, so the short side must not.
+        assert!(h < w * 0.6, "aspect kept: {w} by {h}");
+    }
+
     fn curve_of(points: &[(f32, f32)], closed: bool) -> Shape {
         let flat: Vec<f32> = points.iter().flat_map(|(x, y)| [*x, *y]).collect();
         let xs: Vec<f32> = points.iter().map(|p| p.0).collect();

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-render/src/command.rs

@@ -28,6 +28,18 @@ pub enum RenderCommand {
         height: f32,
         fill: Color,
     },
+    /// A decoded picture and the affine that places it.
+    ///
+    /// Every other command is geometry that can be transformed point by point.
+    /// A picture cannot, so the transform travels with it, as
+    /// `[sx, ky, kx, sy, tx, ty]` mapping the image's own pixel space to the
+    /// frame. `opacity` rides here rather than in a fill, because an image has
+    /// no fill colour to carry it.
+    Image {
+        pixels: std::sync::Arc<codimate_core::Pixels>,
+        transform: [f32; 6],
+        opacity: f32,
+    },
     Path {
         segments: Vec<Segment>,
         closed: bool,
@@ -127,6 +139,42 @@ fn render_primitive_commands(primitive: &ConcretePrimitive) -> Vec<RenderCommand
                 stroke_color: stroke,
             }]
         }
+        ConcreteGeometry::Image {
+            pixels,
+            width,
+            height,
+        } => {
+            // The same mapping `transform_point` performs, written as an
+            // affine because a picture is blitted rather than walked. Doing it
+            // by corner points would place the box but lose the rotation,
+            // which is what an earlier version of this did.
+            let t = &primitive.transform;
+            let (sin, cos) = t.rotation_deg.to_radians().sin_cos();
+            let (a, b) = (t.scale.x * cos, t.scale.x * sin);
+            let (c, d) = (-t.scale.y * sin, t.scale.y * cos);
+            let e = t.pos.x + t.pivot.x - t.pivot.x * a - t.pivot.y * c;
+            let f = t.pos.y + t.pivot.y - t.pivot.x * b - t.pivot.y * d;
+
+            // Composed with the map from the image's pixels to its box, which
+            // is centred on the primitive's origin like every other geometry.
+            let (w, h) = (*width, *height);
+            let (px, py) = (
+                w / pixels.width.max(1) as f32,
+                h / pixels.height.max(1) as f32,
+            );
+            vec![RenderCommand::Image {
+                pixels: pixels.clone(),
+                transform: [
+                    a * px,
+                    b * px,
+                    c * py,
+                    d * py,
+                    e - a * w / 2.0 - c * h / 2.0,
+                    f - b * w / 2.0 - d * h / 2.0,
+                ],
+                opacity: t.opacity,
+            }]
+        }
         ConcreteGeometry::Text {
             text,
             font_size,
@@ -245,3 +293,80 @@ pub trait Renderer {
 
     fn render(&mut self, frame: &LayoutFrame) -> Result<(), Self::Error>;
 }
+
+#[cfg(test)]
+mod image_tests {
+    use super::*;
+    use codimate_core::{ConcretePrimitive, ConcreteTransform, Pixels, Style, Vec2};
+    use std::sync::Arc;
+
+    fn one_red_pixel() -> Arc<Pixels> {
+        Arc::new(Pixels {
+            width: 1,
+            height: 1,
+            rgba: vec![255, 0, 0, 255],
+        })
+    }
+
+    fn placed(rotation_deg: f32, scale: Vec2) -> ConcretePrimitive {
+        ConcretePrimitive {
+            transform: ConcreteTransform {
+                pos: Vec2::new(100.0, 50.0),
+                scale,
+                rotation_deg,
+                pivot: Vec2::new(0.0, 0.0),
+                opacity: 1.0,
+            },
+            style: Style::new(),
+            geometry: ConcreteGeometry::Image {
+                pixels: one_red_pixel(),
+                width: 20.0,
+                height: 10.0,
+            },
+        }
+    }
+
+    fn affine_of(primitive: &ConcretePrimitive) -> [f32; 6] {
+        match render_primitive_commands(primitive).remove(0) {
+            RenderCommand::Image { transform, .. } => transform,
+            other => panic!("expected an Image command, got {other:?}"),
+        }
+    }
+
+    /// The regression this exists for. Every other command is geometry and is
+    /// transformed point by point; the first version of the image command
+    /// placed the picture by transforming its centre and emitting an
+    /// axis-aligned box, which put it in exactly the right place and silently
+    /// threw the rotation away. Nothing caught it but looking at a picture.
+    #[test]
+    fn a_turned_image_carries_its_rotation() {
+        let [_, ky, kx, _, _, _] = affine_of(&placed(25.0, Vec2::new(1.0, 1.0)));
+        assert!(
+            ky.abs() > 0.01 && kx.abs() > 0.01,
+            "a rotated image must have skew terms, got kx={kx} ky={ky}"
+        );
+
+        let [_, ky, kx, _, _, _] = affine_of(&placed(0.0, Vec2::new(1.0, 1.0)));
+        assert!(
+            ky.abs() < 1e-6 && kx.abs() < 1e-6,
+            "an unrotated image must not, got kx={kx} ky={ky}"
+        );
+    }
+
+    /// The affine maps the image's own pixel space, so a one-pixel source
+    /// drawn into a 20x10 box scales by exactly that.
+    #[test]
+    fn the_affine_maps_pixels_to_the_box() {
+        let [sx, _, _, sy, tx, ty] = affine_of(&placed(0.0, Vec2::new(1.0, 1.0)));
+        assert_eq!((sx, sy), (20.0, 10.0), "one source pixel fills the box");
+        // Centred on the primitive's position, like every other geometry.
+        assert_eq!((tx, ty), (100.0 - 10.0, 50.0 - 5.0));
+    }
+
+    /// `.grow()` reaches an image, unlike `.turn()` before this was fixed.
+    #[test]
+    fn scale_reaches_an_image() {
+        let [sx, _, _, sy, _, _] = affine_of(&placed(0.0, Vec2::new(2.0, 0.5)));
+        assert_eq!((sx, sy), (40.0, 5.0));
+    }
+}

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-render/src/raster.rs

@@ -88,6 +88,36 @@ fn rasterize_commands(viewport: Viewport, commands: &[RenderCommand], pixel_scal
                     pixmap.fill_path(&path, &paint, FillRule::Winding, transform, None);
                 }
             }
+            RenderCommand::Image {
+                pixels,
+                transform: affine,
+                opacity,
+            } => {
+                if let Some(view) = tiny_skia::PixmapRef::from_bytes(
+                    &pixels.rgba,
+                    pixels.width.max(1),
+                    pixels.height.max(1),
+                ) {
+                    let placed = transform.pre_concat(tiny_skia::Transform::from_row(
+                        affine[0], affine[1], affine[2], affine[3], affine[4], affine[5],
+                    ));
+                    pixmap.draw_pixmap(
+                        0,
+                        0,
+                        view,
+                        &tiny_skia::PixmapPaint {
+                            opacity: opacity.clamp(0.0, 1.0),
+                            // Bilinear: an image is nearly always drawn at some
+                            // size other than its own, and nearest neighbour on
+                            // a photograph is visibly wrong.
+                            quality: tiny_skia::FilterQuality::Bilinear,
+                            ..Default::default()
+                        },
+                        placed,
+                        None,
+                    );
+                }
+            }
             RenderCommand::Rect {
                 x,
                 y,

{codimate-0.1.2 → codimate-0.1.4}/crates/codimate-render/tests/raster.rs

@@ -4,6 +4,7 @@ use codimate_core::{circle_path, Color, Segment, TextAlign, Vec2};
 use codimate_fonts::FontRegistry;
 use codimate_layout::Viewport;
 use codimate_render::{rasterize, RenderCommand, RenderFrame};
+use std::sync::Arc;
 
 fn red_circle_frame() -> RenderFrame {
     RenderFrame {
@@ -334,3 +335,73 @@ fn rasterize_path_cubic_circle() {
     // Far corner is black (background)
     assert_eq!(img.pixel(0, 0), (0, 0, 0, 255));
 }
+
+/// A picture actually reaching the pixels — the end of the path that ADR 0013
+/// added and that nothing else here covers.
+fn image_frame(transform: [f32; 6], opacity: f32) -> RenderFrame {
+    // One solid red pixel, stretched by the affine into whatever box it names.
+    let pixels = Arc::new(codimate_core::Pixels {
+        width: 1,
+        height: 1,
+        rgba: vec![255, 0, 0, 255],
+    });
+    RenderFrame {
+        name: "image-test".to_string(),
+        elapsed_seconds: 0.0,
+        viewport: Viewport::new(100.0, 100.0),
+        commands: vec![RenderCommand::Image {
+            pixels,
+            transform,
+            opacity,
+        }],
+    }
+}
+
+#[test]
+fn rasterize_image_fills_the_box_it_is_given() {
+    // Twenty by twenty, placed at (40, 40).
+    let img = rasterize(&image_frame([20.0, 0.0, 0.0, 20.0, 40.0, 40.0], 1.0));
+
+    assert_eq!(img.pixel(50, 50), (255, 0, 0, 255), "inside the box");
+    assert_eq!(img.pixel(5, 5), (0, 0, 0, 255), "outside it");
+    assert_eq!(img.pixel(90, 90), (0, 0, 0, 255), "and past the far edge");
+}
+
+/// The regression the command-level test guards from the other side: a turned
+/// image must actually land turned. A square drawn axis-aligned has black
+/// corners inside its bounding box only when it is rotated.
+#[test]
+fn rasterize_image_honours_rotation() {
+    let (sin, cos) = 45f32.to_radians().sin_cos();
+    let (w, h) = (30.0, 30.0);
+    // The same composition `render_primitive_commands` builds: rotate, then
+    // offset so the box is centred on (50, 50).
+    let (a, b, c, d) = (cos * w, sin * w, -sin * h, cos * h);
+    let turned = rasterize(&image_frame(
+        [a, b, c, d, 50.0 - (a + c) / 2.0, 50.0 - (b + d) / 2.0],
+        1.0,
+    ));
+    let square = rasterize(&image_frame([w, 0.0, 0.0, h, 35.0, 35.0], 1.0));
+
+    // Centre is red either way; the corner of the upright square is red and
+    // the corner of the diamond is not, because it rotated away.
+    assert_eq!(turned.pixel(50, 50), (255, 0, 0, 255));
+    assert_eq!(square.pixel(50, 50), (255, 0, 0, 255));
+    assert_eq!(
+        square.pixel(37, 37),
+        (255, 0, 0, 255),
+        "upright fills its corner"
+    );
+    assert_eq!(turned.pixel(37, 37), (0, 0, 0, 255), "turned does not");
+}
+
+#[test]
+fn rasterize_image_honours_opacity() {
+    let half = rasterize(&image_frame([20.0, 0.0, 0.0, 20.0, 40.0, 40.0], 0.5));
+    let (r, g, b, a) = half.pixel(50, 50);
+    assert!(
+        (100..=160).contains(&r) && g == 0 && b == 0 && a == 255,
+        "half-opaque red over black should be mid red, got {:?}",
+        (r, g, b, a)
+    );
+}

{codimate-0.1.2 → codimate-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "codimate"
-version = "0.1.2"
+version = "0.1.4"
 description = "Turn a running algorithm into an explainer video"
 readme = "README.md"
 requires-python = ">=3.9"

{codimate-0.1.2 → codimate-0.1.4}/python/codimate/__init__.py

@@ -20,8 +20,8 @@ encoding — happens in Rust (ADR 0008).
 
 ## What a moment looks like
 
-- `Scene` — one picture: `rect`, `circle`, `polygon`, `curve`, `arrow`,
-  `text`, `line`, `formula`, `svg`
+- `Scene` — one picture: `rect`, `circle`, `arc`, `polygon`, `curve`, `arrow`,
+  `text`, `line`, `formula`, `svg`, `image`
 - `ngon`, `star` — corners for a polygon, so you do not compute them
 - `Group` — several shapes that move together
 - `Handle` — what a shape call returns: `.fill()`, `.round()`, `.turn()`,

{codimate-0.1.2 → codimate-0.1.4}/python/codimate/scene.py

@@ -290,6 +290,56 @@ class Group:
         return self._place(key, "formula", x=x, y=y, text=latex, size=size,
                            layer=10, r=1.0)
 
+    def arc(self, key: Hashable, *, r, sweep, at=None) -> "Handle":
+        """A slice of a circle — an angle mark, a pie, a dial, an orbit.
+
+            scene.arc("angle", r=90, sweep=(0, 50)).fill("none", edge="cyan",
+                                                          edge_w=3)
+            scene.arc("slice", r=120, sweep=(0, 120)).fill("orange").round(1)
+
+        `sweep` is `(start, end)` in degrees, clockwise from twelve o'clock —
+        the same zero `cm.ngon` uses. `r` is the radius, or `(rx, ry)` for an
+        ellipse.
+
+        Open by default, so it draws as a curved line. `.round(1)` closes it
+        back to the centre and makes a pie slice you can fill.
+
+        Two arcs always tween, however far apart their angles are, so an angle
+        mark grows and a pie fills smoothly. That is what this cannot be done
+        with `curve`: a curve through points on a circle changes its point
+        count when the sweep changes, and then it snaps instead of sweeping.
+        """
+        rx, ry = (r, r) if isinstance(r, (int, float)) else r
+        start, end = sweep
+        x, y = self._where(at, 0.0)
+        return self._place(
+            key, "arc", x=x, y=y,
+            # The bounding box, so an ellipse costs nothing extra.
+            w=float(rx) * 2, h=float(ry) * 2,
+            # `x2`/`y2` are the line's endpoints elsewhere and free here.
+            x2=float(start), y2=float(end),
+        )
+
+    def image(self, key: Hashable, file, *, size=None, at=None) -> "Handle":
+        """A picture — a photo, a screenshot, a figure — drawn into the frame.
+
+            scene.image("paper", "figures/attention.png", size=(520, 300))
+            scene.image("shot", "screen.png", size=400).on(opacity=0.4)
+
+        PNG and JPEG, read by content rather than by extension. `size` is a box
+        it fits inside, one number or `(w, h)`, aspect always kept; leave it out
+        and the picture is drawn at its own pixel size.
+
+        It moves, scales, turns and fades like anything else, and `focus()`
+        frames it. For a logo or a diagram prefer `svg`, which arrives as
+        geometry you can recolour and draw on — an image is pixels, so it can
+        only be placed.
+        """
+        box = (size, size) if isinstance(size, (int, float)) else size
+        w, h = (0.0, 0.0) if box is None else (float(box[0]), float(box[1]))
+        x, y = self._where(at, 0.0)
+        return self._place(key, "image", x=x, y=y, text=str(file), w=w, h=h)
+
     def svg(self, key: Hashable, file, *, size=120.0, at=None) -> "Handle":
         """Vector art from a file, drawn as real geometry.