diff --git a/README.md b/README.md index d0165f4..19e46fa 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,13 @@ - Clean up my 'parent vertex mapping' thingy, *and* come up with meaningful terms to discuss it. +- Terminology: "run" a rule versus "evaluate" a rule. - Do transforms compose in the *reverse* of automata_scratch? This appears to be the case. ## Important but less critical: +- Why must I repeat myself so much in these definitions? - Consider trampolining `to_mesh`. My call stack seems needlessly deep in spots. Can I make tail-recursive? - Grep for all TODOs in code, really. diff --git a/src/examples.rs b/src/examples.rs index 7ecf35a..39278c4 100644 --- a/src/examples.rs +++ b/src/examples.rs @@ -2,7 +2,7 @@ use nalgebra::*; //pub mod examples; use crate::openmesh::{OpenMesh, Tag, Mat4, Vertex, vertex}; -use crate::rule::{Rule, RuleStep}; +use crate::rule::{Rule, RuleStep, Child}; use crate::prim; fn curve_horn_start() -> RuleStep { @@ -22,11 +22,18 @@ fn curve_horn_start() -> RuleStep { }, final_geom: prim::empty_mesh(), children: vec![ - (Rule::Recurse(curve_horn_thing_rule), id, vec![0,1,2,3]), - (Rule::Recurse(curve_horn_thing_rule), flip180, vec![3,2,1,0]), + Child { + rule: Rule::Recurse(curve_horn_thing_rule), + xf: id, + vmap: vec![0,1,2,3], + }, + Child { + rule: Rule::Recurse(curve_horn_thing_rule), + xf: flip180, + vmap: vec![3,2,1,0], + }, ], } - // TODO: Fix the consequences of the 180 flip } fn curve_horn_thing_rule() -> RuleStep { @@ -77,7 +84,11 @@ fn curve_horn_thing_rule() -> RuleStep { geom: geom, final_geom: final_geom, children: vec![ - (Rule::Recurse(curve_horn_thing_rule), m, vec![0,1,2,3]), + Child { + rule: Rule::Recurse(curve_horn_thing_rule), + xf: m, + vmap: vec![0,1,2,3], + }, ], } } @@ -102,11 +113,15 @@ fn cube_thing_rule() -> RuleStep { geometry::Rotation3::from_axis_angle(z, -qtr).to_homogeneous(), ]; - let gen_rulestep = |rot: &Mat4| -> (Rule, Mat4, Vec) { + let gen_rulestep = |rot: &Mat4| -> Child { let m: Mat4 = rot * Matrix4::new_scaling(0.5) * geometry::Translation3::new(6.0, 0.0, 0.0).to_homogeneous(); - (Rule::Recurse(cube_thing_rule), m, vec![]) + Child { + rule: Rule::Recurse(cube_thing_rule), + xf: m, + vmap: vec![], + } }; RuleStep { @@ -119,8 +134,9 @@ fn cube_thing_rule() -> RuleStep { // Conversion from Python & automata_scratch fn ram_horn_start() -> RuleStep { let opening_xform = |i| { + let r = std::f32::consts::FRAC_PI_2 * i; ((geometry::Rotation3::from_axis_angle( - &nalgebra::Vector3::z_axis(), i).to_homogeneous()) * + &nalgebra::Vector3::z_axis(), r).to_homogeneous()) * geometry::Translation3::new(0.25, 0.25, 1.0).to_homogeneous() * Matrix4::new_scaling(0.5) * geometry::Translation3::new(0.0, 0.0, -1.0).to_homogeneous()) @@ -171,12 +187,28 @@ fn ram_horn_start() -> RuleStep { }, final_geom: prim::empty_mesh(), children: vec![ - (Rule::Recurse(ram_horn), opening_xform(0.0), vec![5,2,6,8]), - (Rule::Recurse(ram_horn), opening_xform(std::f32::consts::FRAC_PI_2), vec![4,1,5,8]), - (Rule::Recurse(ram_horn), opening_xform(std::f32::consts::FRAC_PI_2*2.0), vec![7,0,4,8]), - (Rule::Recurse(ram_horn), opening_xform(std::f32::consts::FRAC_PI_2*3.0), vec![6,3,7,8]), + Child { + rule: Rule::Recurse(ram_horn), + xf: opening_xform(0.0), + vmap: vec![5,2,6,8], + }, + Child { + rule: Rule::Recurse(ram_horn), + xf: opening_xform(1.0), + vmap: vec![4,1,5,8], + }, + Child { + rule: Rule::Recurse(ram_horn), + xf: opening_xform(2.0), + vmap: vec![7,0,4,8], + }, + Child { + rule: Rule::Recurse(ram_horn), + xf: opening_xform(3.0), + vmap: vec![6,3,7,8], + }, // TODO: These vertex mappings appear to be right. - // Understand *why* they are right. + // Explain *why* they are right. ], } } @@ -219,7 +251,11 @@ fn ram_horn() -> RuleStep { geom: geom, final_geom: final_geom, children: vec![ - (Rule::Recurse(ram_horn), incr, vec![0,1,2,3]), + Child { + rule: Rule::Recurse(ram_horn), + xf: incr, + vmap: vec![0,1,2,3], + }, ], } } diff --git a/src/rule.rs b/src/rule.rs index ec0b725..bb76684 100644 --- a/src/rule.rs +++ b/src/rule.rs @@ -1,34 +1,69 @@ use crate::openmesh::{OpenMesh, Mat4}; use crate::prim; -// TODO: Do I benefit with Rc below so Rule can be shared? +/// Definition of a rule. In general, a `Rule`: +/// +/// - produces geometry when it is evaluated +/// - tells what other rules to invoke, and what to do with their +/// geometry pub enum Rule { - // Produce geometry, and possibly recurse further: + /// Produce some geometry, and possibly recurse further. Recurse(fn () -> RuleStep), - // Stop recursing here: + /// Produce nothing and recurse no further. EmptyRule, } // TODO: Rename rules? // TODO: It may be possible to have just a 'static' rule that requires // no function call. +// TODO: Do I benefit with Rc below so Rule can be shared? +/// `RuleStep` supplies the results of evaluating some `Rule` for one +/// iteration: it contains the geometry produced at this step +/// (`geom`), and it tells what to do next depending on whether +/// recursion continues further, or is stopped here (due to hitting +/// some limit of iterations or some lower limit on overall scale). +/// +/// That is: +/// - if recursion stops, `final_geom` is connected with `geom`. +/// - if recursion continues, the rules of `children` are evaluated, +/// and the resultant geometry is transformed and then connected with +/// `geom`. pub struct RuleStep { - // The geometry generated by this rule on its own (not by any of - // the child rules). + /// The geometry generated at just this iteration pub geom: OpenMesh, - // The "final" geometry, used only if recursion must be stopped. - // This should be in the same coordinate space as 'geom', and - // properly close any exit groups that it may have (and have no - // exit groups of its own). + /// The "final" geometry that is merged with `geom` via + /// `connect()` in the event that recursion stops. This must be + /// in the same coordinate space as `geom`. + /// + /// Parent vertex references will be resolved directly to `geom` + /// with no mapping. pub final_geom: OpenMesh, - // Child rules, paired with the transform that will be applied to - // all of their geometry and parent vertex mappings - pub children: Vec<(Rule, Mat4, Vec)>, - // TODO: Clean this up, perhaps change the tuple to something - // saner. - // TODO: Also, document & rename this more clearly. + /// The child invocations (used if recursion continues). The + /// 'parent' mesh, from the perspective of all geometry produced + /// by `children`, is `geom`. + pub children: Vec, +} + +/// `Child` evaluations, pairing another `Rule` with the +/// transformations and parent vertex mappings that should be applied +/// to it. +pub struct Child { + + /// Rule to evaluate to produce geometry + pub rule: Rule, + + /// The transform to apply to all geometry produced by `rule` + /// (including its own `geom` and `final_geom` if needed, as well + /// as all sub-geometry produced recursively). + pub xf: Mat4, + + /// The mapping to apply to turn a Tag::Parent vertex reference + /// into a vertex index of the parent mesh. That is, if `rule` + /// produces an `OpenMesh` with a face of `Tag::Parent(n)`, this + /// will correspond to index `vmap[n]` in the parent mesh. + pub vmap: Vec, } impl Rule { @@ -37,13 +72,16 @@ impl Rule { // could end up having a lot of identical geometry that need not be // duplicated until it is transformed into the global space. // - // This might produce bigger gains if I rewrite rule_to_mesh so that + // This might produce bigger gains if I rewrite to_mesh so that // rather than repeatedly transforming meshes, it stacks // transformations and then applies them all at once. + /// Convert this `Rule` to mesh data, recursively. `iters_left` + /// sets the maximum recursion depth. This returns (geometry, + /// number of rule evaluations). pub fn to_mesh(&self, iters_left: u32) -> (OpenMesh, u32) { - let mut nodes: u32 = 1; + let mut evals: u32 = 1; if iters_left <= 0 { match self { @@ -52,7 +90,7 @@ impl Rule { return (rs.final_geom, 1); } Rule::EmptyRule => { - return (prim::empty_mesh(), nodes); + return (prim::empty_mesh(), evals); } } } @@ -63,23 +101,22 @@ impl Rule { // TODO: This logic is more or less right, but it // could perhaps use some un-tupling or something. - let subgeom: Vec<(OpenMesh, &Vec)> = rs.children.iter().map( - |(subrule, subxform, vmap)| { - // Get sub-geometry (still un-transformed): - let (submesh,n) = subrule.to_mesh(iters_left - 1); - // Tally up node count: - nodes += n; - - let m2 = submesh.transform(*subxform); - - (m2, vmap) - }).collect(); + let subgeom: Vec<(OpenMesh, &Vec)> = rs.children.iter().map(|sub| { + // Get sub-geometry (still un-transformed): + let (submesh, eval) = sub.rule.to_mesh(iters_left - 1); + // Tally up eval count: + evals += n; + + let m2 = submesh.transform(sub.xf); + + (m2, &sub.vmap) + }).collect(); // Connect geometry from this rule (not child rules): - return (rs.geom.connect(&subgeom), nodes); + return (rs.geom.connect(&subgeom), evals); } Rule::EmptyRule => { - return (prim::empty_mesh(), nodes); + return (prim::empty_mesh(), evals); } } }