1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/org/cone-joints.txt	Sat Jan 07 00:58:47 2012 -0700
     1.3 @@ -0,0 +1,127 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +(ConeJoint
     1.9 +	RigidBody A
    1.10 +	RigidBody B
    1.11 +	Vector3f PivotA
    1.12 +	Vector3f PivotB
    1.13 +	Matrix3f RotA
    1.14 +	Matrix3f RotB
    1.15 +)
    1.16 +
    1.17 +Parameters:
    1.18 +
    1.19 +The specification of a cone joint depends on local coordinates,
    1.20 +that is coordinates relative to the given rigid bodies.
    1.21 +
    1.22 +***
    1.23 +DIGRESSION ABOUT LOCAL COORDINATES
    1.24 +
    1.25 +Each rigid body has its own coordinate system.
    1.26 +If an object is placed, unrotated, at the origin of the world,
    1.27 +then its coordinate system is the same as the world's coordinate
    1.28 +system. In other words, the origin of the object coincides with the
    1.29 +origin of the world, and the XYZ axes of the object coincide with the
    1.30 +XYZ axes of the world.
    1.31 +
    1.32 +When you translate the object, its "origin" goes with it.
    1.33 +The origin of the object is always the center of the object.
    1.34 +
    1.35 +When you rotate the object, its axes go with it.
    1.36 +For example, if you rotate the object pi/2 radians righthandedly
    1.37 +about the Z axis, its own X axis will move to coincide with the
    1.38 +world's Y axis; its own Y axis will move to coincide with the
    1.39 +world's -X axis; its Z axis will remain aligned with the world's
    1.40 +Z-axis.
    1.41 +
    1.42 +
    1.43 +In such a way, you can see the way in which the translations and rotations of an
    1.44 +object alter its local coordinates.
    1.45 +
    1.46 +
    1.47 +## a haphazard elaboration of the above
    1.48 +
    1.49 +Converting from world coordinates to local coordinates amounts to
    1.50 +finding the transformation that undoes all the rotations and
    1.51 +translations that the Object has suffered, then applying that
    1.52 +undoing-transformation to the world coordinates.
    1.53 +
    1.54 +            +position of obj   +rot of obj
    1.55 +world axes  ---------------> x -----------> obj axes
    1.56 +
    1.57 +
    1.58 +1. Start with the world coordinates of the Object and a test-object.
    1.59 +2. Subtract the world coordinates of the Object from each. Now the
    1.60 +Object is at the origin (though still has its rotation, if any) and
    1.61 +the test-object is somewhere else (irrelevant).
    1.62 +3. Rotate the whole world about the origin so that the Object becomes
    1.63 +unrotated. Now the object is unrotated at the origin, and the
    1.64 +test-object is somewhere else.
    1.65 +4. That somewhere-else is the coordinates of the test-object as seen
    1.66 +from the Object's own coordinate system (the system in which the Object is always
    1.67 +unrotated and centered at the origin)
    1.68 +
    1.69 +cf: get-subjective-rotation
    1.70 +cf: get-subjective-position
    1.71 +
    1.72 +***
    1.73 +
    1.74 +
    1.75 +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
    1.76 +
    1.77 +Now, to understand the ConeJoint constructor: 
    1.78 +Suppose you have the position of the cone joint picked out, as well as its
    1.79 +orientation (orientation aka rotation matters because the limits of
    1.80 +rotation are taken with respect to the xy and xz plane of the _joint's_
    1.81 +coordinate system. This is what the documentation means by "by
    1.82 +default, the x-axis").
    1.83 +
    1.84 +Then: 
    1.85 +Pivot-a is the position of the joint, as expressed in the coordinate
    1.86 +system of object-a.
    1.87 +Pivot-a is the position of the joint again, this time as expressed in
    1.88 +the coordinate system of object-b.
    1.89 +
    1.90 +(Use get-subjective-position to calculate this conveniently)
    1.91 +
    1.92 +
    1.93 +Rot-a is the orientation of the joint, as expressed in the
    1.94 +coordinate system of object-a. By default, it is aligned with a's
    1.95 +coordinate system, making the cone's axis along a's x-axis, and its
    1.96 +limits of rotation in a's xy and xz planes.
    1.97 +
    1.98 +Analogously for b.
    1.99 +
   1.100 +If inconsistent pivot locations are given, it's possible to recover by
   1.101 +moving the objects. I think the engine prefers to keep object b still
   1.102 +and move everything else, but it may not always be so.
   1.103 +
   1.104 +If inconsistent rotations are given ... I don't know what
   1.105 +happens. Beez happens.
   1.106 +
   1.107 +
   1.108 +Modulo a bunch of forced object migration because your pivots give
   1.109 +inconsistent indicators of where the joint should be expected, etc., this is
   1.110 +how the method works.
   1.111 +
   1.112 +
   1.113 +
   1.114 +# Another implementation option would have been to specify the positions and
   1.115 +# rotations of THREE things --- object A, object B, and the joint --- all in terms of world
   1.116 +# coordinates. This wouldn't be any more or less fragile (i.e. subject to explosions
   1.117 +# of inconsistency) but it might be nice to avoid those
   1.118 +# transformations into local coordinates, even if we had to introduce
   1.119 +# more parameters into such a new method
   1.120 +# (specifically, the position and orientation of the joint would be new).
   1.121 +
   1.122 +# I wouldn't mind because after all, don't we already  need to keep in mind the position and orientation of the
   1.123 +# joint in the existing method? Lest it explode in inconsistency? I
   1.124 +# suggest we create a clojure method that creates cone joints in the
   1.125 +# transformation-free way.
   1.126 +# cf. joint-create, my first attempt
   1.127 +
   1.128 +
   1.129 +
   1.130 +