Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

15.1 KB
Raw Blame
//! Canvases (reference images on planes) and decals (images on planar faces).

use serde_json::{Value, json};
use solidcore_record::Vec2;
use solidcraft_doc::canvas::{Canvas, MAX_CANVAS_BYTES, base64_decode, base64_encode, image_info};
use solidcraft_geom::prelude::*;

use super::CommandSpec;
use crate::params::{bad, bool_, num, str_, vec2};
use crate::schema::canvas::{
    CanvasCalibrateParams, CanvasCalibrated, CanvasDecalParams, CanvasDeleteParams, CanvasDeleted, CanvasEditParams, CanvasEdited,
    CanvasInsertParams, CanvasPlaced,
};
use crate::schema::{TypedContract, output_schema_for};
use crate::{EngineError, Result, Session};

const INSERT_CONTRACT: TypedContract<CanvasInsertParams> = TypedContract::new();
const DECAL_CONTRACT: TypedContract<CanvasDecalParams> = TypedContract::new();
const EDIT_CONTRACT: TypedContract<CanvasEditParams> = TypedContract::new();
const CALIBRATE_CONTRACT: TypedContract<CanvasCalibrateParams> = TypedContract::new();
const DELETE_CONTRACT: TypedContract<CanvasDeleteParams> = TypedContract::new();

/// A canvas command's reply, built from its schema's type so the two can't drift apart.
fn canvas_reply(cmd: &str, r: impl serde::Serialize) -> Result<Value> {
    serde_json::to_value(r).map_err(|e| bad(cmd, e.to_string()))
}

pub static COMMANDS: &[CommandSpec] = &[
    CommandSpec::new("canvas.insert", "Canvas", crate::checked!("canvas.insert", add_canvas))
        .at("SKETCH", "INSERT")
        .icon("canvas")
        .contract(&INSERT_CONTRACT)
        .output(output_schema_for::<CanvasPlaced>)
        .params("path | data (base64 PNG or JPEG); plane?: XY|XZ|YZ|{face: [x,y,z]}|… (default XY); center?: [x,y] on the plane, or at?: [x,y,z]; width?: mm (default 100); angle?: deg; opacity?: 0…1 (default 0.5); flip?; name?"),
    CommandSpec::new("canvas.decal", "Decal", crate::checked!("canvas.decal", add_decal))
        .at("SKETCH", "INSERT")
        .icon("decal")
        .contract(&DECAL_CONTRACT)
        .output(output_schema_for::<CanvasPlaced>)
        .params("path | data; face: [x,y,z] on a planar face (the image is centred there), or the picked face as sketch.create's plane takes it ({face, body, index, path?}); width?: mm; angle?: deg; opacity?: (default 1)"),
    CommandSpec::new("canvas.edit", "Edit Canvas", crate::checked!("canvas.edit", edit_canvas))
        .at("SKETCH", "INSERT")
        .icon("canvas")
        .contract(&EDIT_CONTRACT)
        .output(output_schema_for::<CanvasEdited>)
        .params("canvas: id or name; center?, width?, angle?: deg, opacity?, flip?, visible?, name?, locked? (a locked canvas refuses center, width, angle, flip, Calibrate and Delete)"),
    CommandSpec::new("canvas.calibrate", "Calibrate Canvas", crate::checked!("canvas.calibrate", calibrate))
        .icon("measure")
        .contract(&CALIBRATE_CONTRACT)
        .output(output_schema_for::<CanvasCalibrated>)
        .params("canvas: id or name; a, b: two points on the canvas plane [x,y]; distance: their true distance (mm): scales the image about a"),
    CommandSpec::new("canvas.delete", "Delete Canvas", crate::checked!("canvas.delete", delete_canvas))
        .icon("delete")
        .contract(&DELETE_CONTRACT)
        .output(output_schema_for::<CanvasDeleted>)
        .params("canvas: id or name"),
];

fn image_bytes(p: &Value, cmd: &str) -> Result<Vec<u8>> {
    let b = if let Some(d) = str_(p, "data") {
        if d.len() > MAX_CANVAS_BYTES * 4 / 3 + 16 {
            return Err(bad(cmd, "the image is too large"));
        }
        base64_decode(d).ok_or_else(|| bad(cmd, "`data` is not base64"))?
    } else {
        let path = str_(p, "path").filter(|x| !x.trim().is_empty() && x.len() < 4096).ok_or_else(|| bad(cmd, "give `path` or `data`"))?;
        solidcraft_io::vfs::read(path, MAX_CANVAS_BYTES).map_err(|e| EngineError::Other(format!("{path}: {e}")))?
    };
    if b.len() > MAX_CANVAS_BYTES {
        return Err(bad(cmd, "the image is too large"));
    }
    Ok(b)
}

fn make(s: &mut Session, p: &Value, cmd: &str, decal: bool) -> Result<Value> {
    let bytes = image_bytes(p, cmd)?;
    let (format, pixels) = image_info(&bytes).ok_or_else(|| bad(cmd, "only PNG and JPEG images can be inserted"))?;
    let plane = super::sketch::plane_ref(s, p, cmd)?;
    let (vals, _) = s.doc.param_values();
    let pl = s.doc.resolve_plane_in(&vals, &plane, 0, Some(&s.model.state()))?;
    // A decal sits where the face was picked.
    let at = p.get("at").or_else(|| p.get("plane").and_then(|v| v.get("face"))).and_then(crate::params::vec3).map(|q| pl.to_local(q));
    let center = p.get("center").and_then(vec2).or(at).unwrap_or(Vec2::ZERO);
    let width = num(p, "width").unwrap_or(100.0);
    if !(width > 1e-6 && width < 1e7) {
        return Err(bad(cmd, "`width` must be positive"));
    }
    let opacity = num(p, "opacity").unwrap_or(if decal { 1.0 } else { 0.5 }).clamp(0.0, 1.0);
    // It belongs to the active component (its plane is in that frame) and moves with it.
    let component = s.active_component;
    let doc = s.doc_mut();
    let id = doc.allocate_id()?;
    let base = if decal { "Decal" } else { "Canvas" };
    let name = str_(p, "name").map(str::to_string).unwrap_or_else(|| {
        let names: std::collections::BTreeSet<_> = doc.canvases.iter().map(|c| c.name.as_str()).collect();
        let number = (1..=doc.canvases.len().saturating_add(1)).find(|n| !names.contains(format!("{base}{n}").as_str())).unwrap_or(1);
        format!("{base}{number}")
    });
    doc.canvases.push(Canvas {
        id,
        name: name.clone(),
        format: format.into(),
        data: base64_encode(&bytes).into(),
        pixels,
        plane,
        center,
        width,
        angle: num(p, "angle").unwrap_or(0.0).to_radians(),
        opacity,
        flip: bool_(p, "flip").unwrap_or(false),
        visible: true,
        locked: false,
        component,
    });
    canvas_reply(cmd, CanvasPlaced { canvas: id, name, pixels, param_warnings: Vec::new() })
}

fn add_canvas(s: &mut Session, p: &Value) -> Result<Value> {
    make(s, p, "canvas.insert", false)
}

fn add_decal(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "canvas.decal";
    let face = p.get("face").cloned().ok_or_else(|| bad(cmd, "`face` must be a point [x,y,z] on a planar face"))?;
    // A picked face as `sketch.create` takes it ({face, body, index, path?}) is used as it is.
    let plane = if face.get("face").is_some() { face } else { json!({"face": face}) };
    let mut q = p.clone();
    if let Some(o) = q.as_object_mut() {
        o.insert("plane".into(), plane);
    }
    make(s, &q, cmd, true)
}

fn find(s: &Session, p: &Value, cmd: &str) -> Result<usize> {
    let key = match p.get("canvas") {
        Some(Value::Number(n)) => n.to_string(),
        Some(Value::String(x)) => x.clone(),
        _ => return Err(bad(cmd, "`canvas` must be an id or a name")),
    };
    s.doc.canvases.iter().position(|c| c.id.to_string() == key || c.name == key).ok_or_else(|| bad(cmd, format!("no canvas `{key}`")))
}

/// A locked canvas (#12310) keeps its place and is not deleted: the refusal names it.
fn refuse_locked(s: &Session, i: usize, cmd: &str) -> Result<()> {
    match s.doc.canvases.get(i) {
        Some(c) if c.locked => Err(bad(cmd, locked_reason(c))),
        _ => Ok(()),
    }
}

/// Why a locked canvas is left as it is.
pub(crate) fn locked_reason(c: &Canvas) -> String {
    format!("{} is locked; unlock it first", c.name)
}

fn edit_canvas(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "canvas.edit";
    let i = find(s, p, cmd)?;
    let width = num(p, "width");
    if width.is_some_and(|w| !(w > 1e-6 && w < 1e7)) {
        return Err(bad(cmd, "`width` must be positive"));
    }
    // Unlocking in the same call lets the other changes through.
    let moves = ["center", "width", "angle", "flip"].iter().any(|k| p.get(*k).is_some_and(|v| !v.is_null()));
    if moves && bool_(p, "locked") != Some(false) {
        refuse_locked(s, i, cmd)?;
    }
    let c = s.doc_mut().canvases.get_mut(i).ok_or_else(|| bad(cmd, "canvas"))?;
    if let Some(l) = bool_(p, "locked") {
        c.locked = l;
    }
    if let Some(v) = p.get("center").and_then(vec2) {
        c.center = v;
    }
    if let Some(w) = width {
        c.width = w;
    }
    if let Some(a) = num(p, "angle") {
        c.angle = a.to_radians();
    }
    if let Some(o) = num(p, "opacity") {
        c.opacity = o.clamp(0.0, 1.0);
    }
    if let Some(f) = bool_(p, "flip") {
        c.flip = f;
    }
    if let Some(v) = bool_(p, "visible") {
        c.visible = v;
    }
    if let Some(n) = str_(p, "name").filter(|n| !n.trim().is_empty()) {
        c.name = n.to_string();
    }
    canvas_reply(cmd, CanvasEdited { canvas: c.id, param_warnings: Vec::new() })
}

fn calibrate(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "canvas.calibrate";
    let i = find(s, p, cmd)?;
    let (a, b) = (p.get("a").and_then(vec2), p.get("b").and_then(vec2));
    let (Some(a), Some(b)) = (a, b) else { return Err(bad(cmd, "`a` and `b` must be points [x,y]")) };
    let d = num(p, "distance").filter(|d| *d > 1e-9).ok_or_else(|| bad(cmd, "`distance` must be positive"))?;
    let now = a.dist(b);
    if now < 1e-9 {
        return Err(bad(cmd, "the points must differ"));
    }
    let k = d / now;
    refuse_locked(s, i, cmd)?;
    let c = s.doc_mut().canvases.get_mut(i).ok_or_else(|| bad(cmd, "canvas"))?;
    c.width *= k;
    c.center = a + (c.center - a) * k;
    canvas_reply(cmd, CanvasCalibrated { canvas: c.id, width: c.width, param_warnings: Vec::new() })
}

fn delete_canvas(s: &mut Session, p: &Value) -> Result<Value> {
    let cmd = "canvas.delete";
    let i = find(s, p, cmd)?;
    refuse_locked(s, i, cmd)?;
    let c = s.doc_mut().canvases.remove(i);
    canvas_reply(cmd, CanvasDeleted { deleted: c.id, param_warnings: Vec::new() })
}

#[cfg(test)]
mod tests {
    use serde_json::json;
    use solidcraft_doc::canvas::base64_encode;

    use crate::Session;

    fn png(w: u32, h: u32) -> String {
        let mut b = b"\x89PNG\r\n\x1a\n\0\0\0\rIHDR".to_vec();
        b.extend(w.to_be_bytes());
        b.extend(h.to_be_bytes());
        b.extend([8, 6, 0, 0, 0, 0, 0, 0, 0]);
        base64_encode(&b)
    }

    #[test]
    fn deleted_canvas_ids_are_not_reused_after_reopening() {
        let mut s = Session::default();
        let params = json!({"data": png(10, 10)});
        let first = s.execute("canvas.insert", &params).unwrap()["canvas"].as_u64().unwrap();
        s.execute("canvas.delete", &json!({"canvas": first})).unwrap();
        let doc = solidcraft_doc::Document::from_json(&s.doc.to_json()).unwrap();
        *s.doc_mut() = doc;
        let second = s.execute("canvas.insert", &params).unwrap()["canvas"].as_u64().unwrap();
        assert!(second > first, "deleted canvas {first} was reused as {second}");
        assert!(s.execute("canvas.edit", &json!({"canvas": first, "width": 500})).is_err());
    }

    /// A locked canvas (#12310) refuses a move, a resize, a turn, a flip, Calibrate and Delete,
    /// keeps taking opacity, visibility and a new name, is saved locked, and moves again once
    /// unlocked. Delete of a selection with it deletes the rest and says why it stayed.
    #[test]
    fn a_locked_canvas_keeps_its_place_and_is_not_deleted() {
        let mut s = Session::default();
        let id = s.execute("canvas.insert", &json!({"data": png(10, 10), "width": 50})).unwrap()["canvas"].as_u64().unwrap();
        let other = s.execute("canvas.insert", &json!({"data": png(10, 10)})).unwrap()["canvas"].as_u64().unwrap();
        s.execute("canvas.edit", &json!({"canvas": id, "locked": true})).unwrap();
        let locked = s.doc.canvases[0].clone();
        assert!(locked.locked);
        for p in [
            json!({"canvas": id, "center": [5, 5]}),
            json!({"canvas": id, "width": 80}),
            json!({"canvas": id, "angle": 30}),
            json!({"canvas": id, "flip": true}),
            json!({"canvas": id, "locked": true, "width": 80}),
        ] {
            let e = s.execute("canvas.edit", &p).unwrap_err().to_string();
            assert!(e.contains("Canvas1 is locked"), "{p}: {e}");
        }
        assert!(s.execute("canvas.calibrate", &json!({"canvas": id, "a": [0, 0], "b": [10, 0], "distance": 20})).is_err());
        assert!(s.execute("canvas.delete", &json!({"canvas": id})).is_err());
        assert_eq!(s.doc.canvases[0], locked, "nothing changed");
        s.execute("canvas.edit", &json!({"canvas": id, "opacity": 0.9, "visible": false, "name": "Blueprint"})).unwrap();
        assert!(s.doc.canvases[0].locked && !s.doc.canvases[0].visible && s.doc.canvases[0].name == "Blueprint");
        // Saved locked; a design without the field opens unlocked.
        let back = solidcraft_doc::Document::from_json(&s.doc.to_json()).unwrap();
        assert!(back.canvases[0].locked && !back.canvases[1].locked);
        assert!(serde_json::to_value(&s.doc.canvases[1]).unwrap().get("locked").is_none(), "an unlocked canvas saves as before");
        // Delete of both deletes the unlocked one and names the locked one.
        let r = s.execute("selection.delete", &json!({"canvases": [id, other]})).unwrap();
        assert_eq!(r["skipped"], json!(["Blueprint is locked; unlock it first"]));
        assert_eq!(s.doc.canvases.iter().map(|c| c.id).collect::<Vec<_>>(), [id]);
        assert!(s.execute("selection.delete", &json!({"canvases": [id]})).is_err());
        // Unlocking in the same call lets the move through.
        s.execute("canvas.edit", &json!({"canvas": id, "locked": false, "width": 80})).unwrap();
        assert!(!s.doc.canvases[0].locked && (s.doc.canvases[0].width - 80.0).abs() < 1e-12);
        s.execute("canvas.delete", &json!({"canvas": id})).unwrap();
        assert!(s.doc.canvases.is_empty());
    }

    #[test]
    fn canvas_insert_edit_calibrate_save() {
        let mut s = Session::default();
        let r = s.execute("canvas.insert", &json!({"data": png(400, 200), "plane": "XZ", "width": 80})).unwrap();
        let id = r["canvas"].as_u64().unwrap();
        let c = s.doc.canvases[0].clone();
        assert_eq!(c.pixels, [400, 200]);
        assert!((c.height() - 40.0).abs() < 1e-12);
        // Two points 20 apart on the image are really 50 apart.
        s.execute("canvas.calibrate", &json!({"canvas": id, "a": [0, 0], "b": [20, 0], "distance": 50})).unwrap();
        assert!((s.doc.canvases[0].width - 200.0).abs() < 1e-9);
        s.execute("canvas.edit", &json!({"canvas": "Canvas1", "opacity": 0.8, "angle": 90})).unwrap();
        // Undo-able and saved with the design.
        let back = solidcraft_doc::Document::from_json(&s.doc.to_json()).unwrap();
        assert_eq!(back.canvases, s.doc.canvases);
        s.execute("canvas.delete", &json!({"canvas": id})).unwrap();
        assert!(s.doc.canvases.is_empty());
        s.execute("edit.undo", &json!({})).unwrap();
        assert_eq!(s.doc.canvases.len(), 1);
        assert!(s.execute("canvas.insert", &json!({"data": "bm9wZQ=="})).is_err());
        // A decal on the top face of a box.
        s.execute("solid.box", &json!({"length": 30, "width": 30, "height": 10})).unwrap();
        let r = s.execute("canvas.decal", &json!({"data": png(10, 10), "face": [15, 15, 10], "width": 20})).unwrap();
        assert!(r["canvas"].is_u64());
    }
}