src/edu/berkeley/qfat/bind/HasBindingGroup.java

   1 package edu.berkeley.qfat.bind;
   2 import edu.berkeley.qfat.geom.*;
   3
   4 /**
   5  *  A member of an equivalence class of geometric objects whose
   6  *  positions are related by affine transformation matrices and are
   7  *  constrained by an affine constraint.
   8  *
   9  *  Every HasBindingGroup (henceforth, HBG) begins life as a member of
  10  *  a singleton binding group consisting only of itself.
  11  *
  12  *  Invoking bindTo() upon a pair of HBG's that are not part of the
  13  *  same BindingGroup will merge the two BG's.  Invoking bindTo() upon
  14  *  a pair of HBG's that are already part of the same BG will result
  15  *  in the imposition of an AffineConstraint on the BG.
  16  */
  17 public abstract class HasBindingGroup {
  18
  19     BindingGroup bindingGroup;
  20
  21     /**
  22      *  Merge the BGs of this and other, ensuring that
  23      *  this==bindingMatrix*other, and treating differences of less
  24      *  than epsilon as irrelevant for AffineConstraint purposes.
  25      */
  26     public void bindTo(Matrix bindingMatrix, HasBindingGroup other, float epsilon) {
  27         // know:      self   = bindingGroup[self] * master
  28         // know:      other  = other.bindingGroup[other] * other.bindingGroup.master
  29         // want:      self   = bindingMatrix * other
  30         // therefore: master = bindingGroup[self]^-1 * bindingMatrix * other
  31         // therefore:        = bindingGroup[self]^-1 * bindingMatrix * other.bindingGroup[other] * other.bindingGroup.master
  32         if (bindingGroup == null) bindingGroup = new BindingGroup(this);
  33         if (other.bindingGroup == null) other.bindingGroup = new BindingGroup(other);
  34
  35         Matrix bm = bindingGroup.getMatrix(this);
  36         Matrix obm = other.bindingGroup.getMatrix(other);
  37         bindingMatrix =
  38             bm.inverse()
  39             .times(bindingMatrix)
  40             .times(obm);
  41         other.bindingGroup.merge(bindingGroup, bindingMatrix, epsilon);
  42     }
  43
  44     /** number of distinct HBG's in the binding group */
  45     public int bindingGroupSize() {
  46         if (bindingGroup == null) return 1;
  47         return bindingGroup.size();
  48     }
  49
  50     /** returns the AffineConstraint of this BG, translated into this HBG's space */
  51     public AffineConstraint getBindingConstraint() {
  52         if (bindingGroup==null) return new AffineConstraint.All();
  53         return bindingGroup.getAffineConstraint(this);
  54     }
  55
  56     /** return the matrix M which relates the position p2 of other to the position p1 of this; p1=M*p2 */
  57     public Matrix getBindingMatrix(HasBindingGroup other) {
  58         if (other==this) return Matrix.ONE;
  59         return bindingGroup.getMatrix(this, other);
  60     }
  61
  62     /** remove this HBG from its BG and place it in its own individual BG */
  63     public void unbind() {
  64         if (bindingGroup==null) return;
  65         bindingGroup.unbind(this);
  66         bindingGroup = null;
  67         bindingGroupChanged();
  68     }
  69
  70     /** true iff this HBG is in the same BG as the argument */
  71     public boolean isBoundTo(HasBindingGroup t) {
  72         return t==this || (bindingGroup!=null && bindingGroup.contains(t));
  73     }
  74
  75     /** enumerates all members of this HBG's BG, including this */
  76     public Iterable getBoundPeers() {
  77         if (bindingGroup==null) bindingGroup = new BindingGroup(this);
  78         return bindingGroup;
  79     }
  80
  81     /** invoked after the binding group of this HBG has changed due to bindTo() or unbind() */
  82     public void bindingGroupChanged() {
  83     }
  84 }