Replaced 3-tuple with rule::Child; wrote some docs

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.

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]),
+            Child {
-            (Rule::Recurse(curve_horn_thing_rule), flip180, vec![3,2,1,0]),
+                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<usize>) {
+    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]),
+            Child {
-            (Rule::Recurse(ram_horn), opening_xform(std::f32::consts::FRAC_PI_2), vec![4,1,5,8]),
+                rule: Rule::Recurse(ram_horn),
-            (Rule::Recurse(ram_horn), opening_xform(std::f32::consts::FRAC_PI_2*2.0), vec![7,0,4,8]),
+                xf: opening_xform(0.0),
-            (Rule::Recurse(ram_horn), opening_xform(std::f32::consts::FRAC_PI_2*3.0), vec![6,3,7,8]),
+                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],
+            },
         ],
     }
 }

src/rule.rs

@@ -1,34 +1,69 @@
 use crate::openmesh::{OpenMesh, Mat4};
 use crate::prim;
 
-// TODO: Do I benefit with Rc<Rule> 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<Rule> 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 geometry generated at just this iteration
-    // the child rules).
     pub geom: OpenMesh,
 
-    // The "final" geometry, used only if recursion must be stopped.
+    /// The "final" geometry that is merged with `geom` via
-    // This should be in the same coordinate space as 'geom', and
+    /// `connect()` in the event that recursion stops.  This must be
-    // properly close any exit groups that it may have (and have no
+    /// in the same coordinate space as `geom`.
-    // exit groups of its own).
+    ///
+    /// 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
+    /// The child invocations (used if recursion continues).  The
-    // all of their geometry and parent vertex mappings
+    /// 'parent' mesh, from the perspective of all geometry produced
-    pub children: Vec<(Rule, Mat4, Vec<usize>)>,
+    /// by `children`, is `geom`.
-    // TODO: Clean this up, perhaps change the tuple to something
+    pub children: Vec<Child>,
-    // saner.
+}
-    // TODO: Also, document & rename this more clearly.
+
+/// `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<usize>,
 }
 
 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<usize>)> = rs.children.iter().map(
+                let subgeom: Vec<(OpenMesh, &Vec<usize>)> = rs.children.iter().map(|sub| {
-                    |(subrule, subxform, vmap)| {
+                    // Get sub-geometry (still un-transformed):
-                        // Get sub-geometry (still un-transformed):
+                    let (submesh, eval) = sub.rule.to_mesh(iters_left - 1);
-                        let (submesh,n) = subrule.to_mesh(iters_left - 1);
+                    // Tally up eval count:
-                        // Tally up node count:
+                    evals += n;
-                        nodes += n;
                     
-                        let m2 = submesh.transform(*subxform);
+                    let m2 = submesh.transform(sub.xf);
                     
-                        (m2, vmap)
+                    (m2, &sub.vmap)
-                    }).collect();
+                }).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);
             }
         }
     }