use super::Solid;
#[derive(Debug, Clone)]
pub struct MechanismSpec {
pub model: Solid,
pub parts: Vec<PartSpec>,
pub mates: Vec<MateSpec>,
pub drives: Vec<DriveSpec>,
pub continua: Vec<ContinuumSpec>,
pub tendons: Vec<TendonSpec>,
}
impl MechanismSpec {
pub fn is_empty(&self) -> bool {
self.parts.is_empty() && self.mates.is_empty() && self.continua.is_empty()
}
pub fn part(&self, name: &str) -> Option<&PartSpec> {
self.parts.iter().find(|p| p.name == name)
}
pub fn continuum(&self, name: &str) -> Option<&ContinuumSpec> {
self.continua.iter().find(|c| c.name == name)
}
pub fn dangling_tendons(&self) -> Vec<&str> {
let mut out = Vec::new();
for tendon in &self.tendons {
if self.continuum(&tendon.along).is_none() && !out.contains(&tendon.along.as_str()) {
out.push(tendon.along.as_str());
}
}
out
}
pub fn mate(&self, name: &str) -> Option<&MateSpec> {
self.mates.iter().find(|m| m.name == name)
}
pub fn dangling_parts(&self) -> Vec<&str> {
let mut out = Vec::new();
for mate in &self.mates {
for name in mate
.parts
.iter()
.chain(mate.carrier.iter())
{
if self.part(name).is_none() && !out.contains(&name.as_str()) {
out.push(name.as_str());
}
}
}
out
}
pub fn dangling_drives(&self) -> Vec<&str> {
let mut out = Vec::new();
for drive in &self.drives {
if self.mate(&drive.mate).is_none() && !out.contains(&drive.mate.as_str()) {
out.push(drive.mate.as_str());
}
}
out
}
}
#[derive(Debug, Clone)]
pub struct PartSpec {
pub name: String,
pub solid: Solid,
pub fixed: bool,
pub density: Option<f32>,
pub mass: Option<f32>,
pub fit: Option<PartFit>,
pub friction: Option<f32>,
pub restitution: Option<f32>,
pub damping: Option<[f32; 2]>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PartFit {
#[default]
Hull,
Mesh,
Decompose,
Box,
Ball,
Capsule,
Cylinder,
}
impl PartFit {
pub fn from_name(name: &str) -> Option<PartFit> {
Some(match name.trim().to_ascii_lowercase().as_str() {
"hull" | "convex" | "convex_hull" | "convexhull" => PartFit::Hull,
"mesh" | "trimesh" | "exact" => PartFit::Mesh,
"decompose" | "decomposed" | "concave" => PartFit::Decompose,
"box" | "aabb" | "cuboid" => PartFit::Box,
"ball" | "sphere" => PartFit::Ball,
"capsule" => PartFit::Capsule,
"cylinder" => PartFit::Cylinder,
_ => return None,
})
}
pub const NAMES: &'static [&'static str] = &[
"hull",
"mesh",
"decompose",
"box",
"ball",
"capsule",
"cylinder",
];
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum MateSpecKind {
Hinge,
Slider,
Cylindrical,
Ball,
Weld,
Planar,
Screw { pitch: f32 },
Gear { ratio: f32 },
Rack { radius: f32 },
}
impl MateSpecKind {
pub fn is_angular(self) -> bool {
matches!(self, MateSpecKind::Hinge)
}
pub fn motor_is_angular(self) -> bool {
!matches!(self, MateSpecKind::Slider | MateSpecKind::Planar)
}
}
#[derive(Debug, Clone)]
pub struct MateSpec {
pub name: String,
pub kind: MateSpecKind,
pub parts: [String; 2],
pub at: [f32; 3],
pub axis: [f32; 3],
pub range: Option<[f32; 2]>,
pub axis_b: Option<[f32; 3]>,
pub bearing: Option<[f32; 2]>,
pub friction: Option<f32>,
pub spring: Option<[f32; 2]>,
pub elastic: Option<[f32; 3]>,
pub carrier: Option<String>,
pub collide: bool,
}
#[derive(Debug, Clone, PartialEq)]
pub struct ContinuumSpec {
pub name: String,
pub base: String,
pub at: [f32; 3],
pub axis: [f32; 3],
pub length: f32,
pub links: usize,
pub radius: f32,
pub backbone_radius: Option<f32>,
pub bore: f32,
pub youngs: f32,
pub poisson: f32,
pub density: f32,
pub damping_ratio: f32,
pub twist: bool,
pub range: Option<[f32; 2]>,
pub segments: usize,
}
impl ContinuumSpec {
pub fn structural_radius(&self) -> f32 {
self.backbone_radius.unwrap_or(self.radius)
}
pub fn segment_links(&self, segment: usize) -> std::ops::Range<usize> {
let n = self.segments.max(1);
if segment == 0 || segment > n {
return 0..0;
}
let base = self.links / n;
let extra = self.links % n;
let start: usize = (0..segment - 1)
.map(|i| base + usize::from(i < extra))
.sum();
let len = base + usize::from(segment - 1 < extra);
start..start + len
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct TendonSpec {
pub name: String,
pub along: String,
pub offset: f32,
pub phase: f32,
pub segment: usize,
pub pretension: f32,
pub stiffness: Option<f32>,
pub damping: f32,
pub pull: f32,
pub max_force: Option<f32>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct DriveSpec {
pub mate: String,
pub to: Option<f32>,
pub over: Option<f32>,
pub start: f32,
pub torque: Option<f32>,
pub max_speed: Option<f32>,
}
impl DriveSpec {
pub fn is_continuous(&self) -> bool {
self.to.is_none()
}
}
#[cfg(test)]
mod tests {
use crate::openscad::geometry_bounds;
use crate::{parse_scad, parse_scad_mechanism};
#[test]
fn a_model_declares_its_own_parts_and_joints() {
let spec = parse_scad_mechanism(
r#"
part("box", fixed = true) cube([40, 20, 8]);
part("lid", density = 1.2) translate([0, 0, 8]) cube([40, 20, 2]);
hinge("lid_pivot", parts = ["lid", "box"],
at = [0, -10, 8], axis = [1, 0, 0], range = [0, 105]);
drive("lid_pivot", to = 105, over = 1.5, torque = 4.5);
"#,
)
.unwrap();
assert_eq!(spec.parts.len(), 2);
assert!(spec.part("box").unwrap().fixed);
assert!(!spec.part("lid").unwrap().fixed);
assert_eq!(spec.part("lid").unwrap().density, Some(1.2));
let mate = spec.mate("lid_pivot").unwrap();
assert_eq!(mate.parts, ["lid".to_string(), "box".to_string()]);
assert_eq!(mate.at, [0.0, -10.0, 8.0]);
assert_eq!(mate.range, Some([0.0, 105.0]));
let drive = &spec.drives[0];
assert_eq!(drive.mate, "lid_pivot");
assert_eq!(
(drive.to, drive.over, drive.torque),
(Some(105.0), Some(1.5), Some(4.5))
);
assert_eq!(drive.start, 0.0);
}
#[test]
fn wrapping_a_subtree_in_part_changes_no_geometry() {
let plain = "cube([40, 20, 8]); translate([0, 0, 8]) cube([40, 20, 2]);";
let named = r#"
part("box") cube([40, 20, 8]);
part("lid") translate([0, 0, 8]) cube([40, 20, 2]);
"#;
let a = geometry_bounds(&parse_scad(plain).unwrap().to_geometry());
let b = geometry_bounds(&parse_scad_mechanism(named).unwrap().model.to_geometry());
for i in 0..3 {
assert!((a.0[i] - b.0[i]).abs() < 1e-4, "min {i}: {a:?} vs {b:?}");
assert!((a.1[i] - b.1[i]).abs() < 1e-4, "max {i}: {a:?} vs {b:?}");
}
}
#[test]
fn the_mechanism_modules_are_inert_in_an_ordinary_parse() {
let src = r#"
module part(name) { translate([100, 0, 0]) children(); }
part("shifted") cube([10, 10, 10]);
"#;
let bounds = geometry_bounds(&parse_scad(src).unwrap().to_geometry());
assert!(
bounds.0[0] > 90.0,
"the user's own part() was overridden: {bounds:?}"
);
let spec = parse_scad_mechanism(src).unwrap();
let bounds = geometry_bounds(&spec.model.to_geometry());
assert!(
bounds.0[0] < 1.0,
"the builtin did not take over: {bounds:?}"
);
assert_eq!(spec.parts.len(), 1);
assert_eq!(spec.parts[0].name, "shifted");
}
#[test]
fn every_mate_kind_parses() {
let spec = parse_scad_mechanism(
r#"
part("a") cube(10);
part("b") translate([20, 0, 0]) cube(10);
hinge("h", parts = ["a", "b"], at = [0,0,0], axis = [0,0,1]);
slider("s", parts = ["a", "b"], at = [0,0,0], axis = [1,0,0], range = [0, 25]);
cylindrical("c", parts = ["a", "b"], at = [0,0,0], axis = [0,1,0]);
ball("k", parts = ["a", "b"], at = [0,0,0]);
weld("w", parts = ["a", "b"], at = [0,0,0], axis = [0,0,1]);
planar("p", parts = ["a", "b"], at = [0,0,0], axis = [0,0,1]);
screw("t", parts = ["a", "b"], at = [0,0,0], axis = [0,0,1], pitch = 1.25);
gear("g", parts = ["a", "b"], at = [0,0,0], axis = [0,1,0], ratio = -3);
rack("r", parts = ["a", "b"], at = [0,0,0], axis = [0,1,0], radius = 6,
rack_axis = [1,0,0]);
"#,
)
.unwrap();
assert_eq!(spec.mates.len(), 9);
assert!(spec.dangling_parts().is_empty());
assert_eq!(
spec.mate("t").unwrap().kind,
super::MateSpecKind::Screw { pitch: 1.25 }
);
assert_eq!(spec.mate("r").unwrap().axis_b, Some([1.0, 0.0, 0.0]));
assert!(spec.mate("k").is_some());
}
#[test]
fn a_drive_either_goes_somewhere_or_just_goes() {
let spec = parse_scad_mechanism(
r#"
part("a") cube(10);
part("b") cube(10);
hinge("axle", parts = ["a", "b"], at = [0,0,0], axis = [0,0,1]);
drive("axle", speed = 120, torque = 5);
"#,
)
.unwrap();
let drive = &spec.drives[0];
assert!(drive.is_continuous(), "a speed with no target is a motor");
assert_eq!(drive.to, None);
assert_eq!(drive.max_speed, Some(120.0));
let err = parse_scad_mechanism(
r#"
part("a") cube(10);
part("b") cube(10);
hinge("axle", parts = ["a", "b"], at = [0,0,0], axis = [0,0,1]);
drive("axle", over = 1.0);
"#,
)
.unwrap_err();
assert!(err.contains("to ="), "unhelpful error: {err}");
assert!(err.contains("speed ="), "unhelpful error: {err}");
}
#[test]
fn a_typo_in_a_part_name_is_reported_rather_than_ignored() {
let spec = parse_scad_mechanism(
r#"
part("lid") cube(10);
hinge("h", parts = ["lid", "bxo"], at = [0,0,0], axis = [1,0,0]);
drive("nope", to = 10);
"#,
)
.unwrap();
assert_eq!(spec.dangling_parts(), vec!["bxo"]);
assert_eq!(spec.dangling_drives(), vec!["nope"]);
}
#[test]
fn a_mate_missing_its_geometry_says_which_argument() {
let err = parse_scad_mechanism(
r#"part("a") cube(10); hinge("h", parts = ["a", "a"], axis = [1,0,0]);"#,
)
.unwrap_err();
assert!(err.contains("at ="), "unhelpful error: {err}");
let err =
parse_scad_mechanism(r#"part("a") cube(10); hinge("h", at = [0,0,0]);"#).unwrap_err();
assert!(err.contains("parts ="), "unhelpful error: {err}");
}
#[test]
fn declarations_can_come_from_loops_and_modules() {
let spec = parse_scad_mechanism(
r#"
module finger(i) {
part(str("finger", i)) translate([i * 12, 0, 0]) cube([10, 10, 40]);
hinge(str("knuckle", i), parts = [str("finger", i), "palm"],
at = [i * 12, 0, 0], axis = [1, 0, 0], range = [0, 90]);
}
part("palm", fixed = true) cube([40, 10, 10]);
for (i = [0 : 2]) finger(i);
"#,
)
.unwrap();
assert_eq!(
spec.parts.len(),
4,
"{:?}",
spec.parts.iter().map(|p| &p.name).collect::<Vec<_>>()
);
assert_eq!(spec.mates.len(), 3);
assert!(spec.part("finger2").is_some());
assert!(spec.dangling_parts().is_empty());
}
#[test]
fn a_failed_parse_leaves_no_mechanism_behind_for_the_next_one() {
let _ = parse_scad_mechanism(r#"part("a") cube(10); hinge("h", at = [0,0,0]);"#);
let spec = parse_scad_mechanism(r#"part("b") cube(10);"#).unwrap();
assert_eq!(spec.parts.len(), 1);
assert_eq!(spec.parts[0].name, "b");
assert!(spec.mates.is_empty());
}
#[test]
fn a_part_can_say_what_it_collides_with() {
use crate::openscad::mechanism::PartFit;
let spec = parse_scad_mechanism(
r#"
part("plain") cube(10);
part("hooked", collider = "decompose", friction = 0.4, bounce = 0.1) cube(10);
part("rail", fixed = true, collider = "mesh", mass = 12) cube(10);
part("roller", collider = "cylinder", restitution = 0.5) cube(10);
"#,
)
.unwrap();
assert_eq!(spec.parts[0].fit, None);
assert_eq!(spec.parts[0].friction, None);
assert_eq!(spec.parts[1].fit, Some(PartFit::Decompose));
assert_eq!(spec.parts[1].friction, Some(0.4));
assert_eq!(spec.parts[1].restitution, Some(0.1));
assert_eq!(spec.parts[2].fit, Some(PartFit::Mesh));
assert_eq!(spec.parts[2].mass, Some(12.0));
assert_eq!(spec.parts[3].fit, Some(PartFit::Cylinder));
assert_eq!(spec.parts[3].restitution, Some(0.5));
}
#[test]
fn a_mate_can_say_its_parts_also_touch() {
let spec = parse_scad_mechanism(
r#"
part("a", fixed = true) cube(10);
part("b") cube(10);
slider("plain", parts = ["b", "a"], at = [0,0,0], axis = [1,0,0]);
slider("touching", parts = ["b", "a"], at = [0,0,0], axis = [1,0,0], collide = true);
"#,
)
.unwrap();
assert!(!spec.mate("plain").unwrap().collide);
assert!(spec.mate("touching").unwrap().collide);
}
#[test]
fn an_unknown_collider_is_an_error_naming_the_alternatives() {
let err = parse_scad_mechanism(r#"part("a", collider = "squishy") cube(10);"#)
.expect_err("should not accept it");
assert!(err.contains("squishy"), "{err}");
assert!(
err.contains("decompose"),
"the message should list what works: {err}"
);
}
#[test]
fn a_model_declares_a_flexible_rod_and_the_cables_on_it() {
let spec = parse_scad_mechanism(
r#"
part("base", fixed = true) cylinder(h = 10, r = 12);
continuum("backbone", on = "base", at = [0, 0, 10], axis = [0, 0, 1],
length = 300, links = 30, radius = 6, segments = 3,
youngs = 200e9, poisson = 0.3, density = 1200,
backbone_radius = 0.5, damping = 0.05);
tendon("t0", along = "backbone", offset = 4, phase = 0, pretension = 1);
tendon("t1", along = "backbone", offset = 4, phase = 120, pretension = 1, segment = 2);
tendon("t2", along = "backbone", offset = 4, phase = 240, pull = 3, force = 40);
"#,
)
.unwrap();
let rod = spec.continuum("backbone").unwrap();
assert_eq!(rod.base, "base");
assert_eq!(rod.at, [0.0, 0.0, 10.0]);
assert_eq!((rod.links, rod.segments), (30, 3));
assert_eq!(rod.structural_radius(), 0.5, "the core, not the sheath");
assert_eq!(rod.damping_ratio, 0.05);
assert!(!rod.twist, "torsion is opt-in");
assert_eq!(spec.tendons.len(), 3);
assert_eq!(spec.tendons[1].phase, 120.0);
assert_eq!(spec.tendons[1].segment, 2);
assert_eq!(spec.tendons[2].pull, 3.0);
assert_eq!(spec.tendons[2].max_force, Some(40.0));
assert!(spec.dangling_tendons().is_empty());
}
#[test]
fn segments_divide_the_links_and_the_remainder_goes_to_the_root() {
let spec = parse_scad_mechanism(
r#"
part("base", fixed = true) cube(1);
continuum("rod", on = "base", length = 100, links = 10, radius = 2,
segments = 3, youngs = 1e6, density = 1000);
"#,
)
.unwrap();
let rod = spec.continuum("rod").unwrap();
assert_eq!(rod.segment_links(1), 0..4);
assert_eq!(rod.segment_links(2), 4..7);
assert_eq!(rod.segment_links(3), 7..10);
assert_eq!(rod.segment_links(4), 0..0, "there is no fourth segment");
}
#[test]
fn a_cable_along_a_rod_that_does_not_exist_is_reported() {
let spec = parse_scad_mechanism(
r#"
part("base", fixed = true) cube(1);
tendon("t0", along = "spine", offset = 4);
"#,
)
.unwrap();
assert_eq!(spec.dangling_tendons(), vec!["spine"]);
}
#[test]
fn a_rod_needs_the_numbers_beam_theory_needs() {
let err = parse_scad_mechanism(r#"continuum("rod", length = 100, links = 10);"#)
.expect_err("should not accept it");
assert!(err.contains("radius"), "{err}");
let err = parse_scad_mechanism(
r#"continuum("rod", length = 100, links = 2, radius = 1, segments = 5,
youngs = 1e6, density = 1000);"#,
)
.expect_err("more segments than links");
assert!(err.contains("empty"), "{err}");
}
#[test]
fn a_mate_can_be_elastic_as_well_as_soft() {
let spec = parse_scad_mechanism(
r#"
part("a") cube(10);
part("b") cube(10);
hinge("h", parts = ["a", "b"], at = [0,0,0], axis = [1,0,0],
spring = [8, 0.7], elastic = [2.5, 15, 0.1]);
"#,
)
.unwrap();
let mate = spec.mate("h").unwrap();
assert_eq!(mate.spring, Some([8.0, 0.7]), "give in the constraint");
assert_eq!(
mate.elastic,
Some([2.5, 15.0, 0.1]),
"and somewhere it would rather be"
);
}
#[test]
fn declarations_can_read_the_animation_variable() {
use crate::openscad::parse_scad_mechanism_at;
let src = r#"
part("a") cube(10);
part("b") cube(10);
hinge("h", parts = ["a", "b"], at = [0,0,0], axis = [1,0,0], range = [0, 90]);
drive("h", to = 90 * $t);
"#;
assert_eq!(
parse_scad_mechanism_at(src, 0.0).unwrap().drives[0].to,
Some(0.0)
);
assert_eq!(
parse_scad_mechanism_at(src, 0.5).unwrap().drives[0].to,
Some(45.0)
);
}
#[test]
fn a_gear_can_name_the_part_it_is_carried_on() {
let spec = parse_scad_mechanism(
r#"
part("case", fixed = true) cube([10, 10, 10]);
part("arm") cube([20, 4, 4]);
part("sun") cylinder(4, 6);
part("planet") cylinder(4, 3);
hinge("arm_pivot", parts = ["arm", "case"], at = [0, 0, 0], axis = [0, 0, 1]);
hinge("sun_pivot", parts = ["sun", "case"], at = [0, 0, 0], axis = [0, 0, 1]);
hinge("planet_pivot", parts = ["planet", "arm"], at = [9, 0, 0], axis = [0, 0, 1]);
gear("mesh", parts = ["planet", "sun"], at = [9, 0, 0], axis = [0, 0, 1],
ratio = -2, carrier = "arm");
"#,
)
.unwrap();
let mesh = spec.mate("mesh").unwrap();
assert_eq!(mesh.carrier.as_deref(), Some("arm"));
assert!(spec.dangling_parts().is_empty(), "{:?}", spec.dangling_parts());
assert!(spec.mate("planet_pivot").unwrap().carrier.is_none());
}
#[test]
fn a_carrier_naming_nothing_is_reported_like_any_other_typo() {
let spec = parse_scad_mechanism(
r#"
part("case", fixed = true) cube([10, 10, 10]);
part("sun") cylinder(4, 6);
part("planet") cylinder(4, 3);
gear("mesh", parts = ["planet", "sun"], at = [9, 0, 0], axis = [0, 0, 1],
ratio = -2, carrier = "arn");
"#,
)
.unwrap();
assert_eq!(spec.dangling_parts(), vec!["arn"]);
}
}