# HG changeset patch
# User Robert McIntyre <rlm@mit.edu>
# Date 1328362000 25200
# Node ID 1943b3f581c24a18b5d467b4c1b070e6abd99192
# Parent  04a39e6bb6955089f7b1e996c929948541113be5
renamed proprioception functions

diff -r 04a39e6bb695 -r 1943b3f581c2 org/proprioception.org
--- a/org/proprioception.org	Sat Feb 04 05:08:35 2012 -0700
+++ b/org/proprioception.org	Sat Feb 04 06:26:40 2012 -0700
@@ -9,20 +9,42 @@
 #+name: proprioception
 #+begin_src clojure
 (ns cortex.proprioception
-  (:use (cortex world util sense body)))
+  "Simulate the sense of proprioception (ability to detect the
+  relative positions of body parts with repsect to other body parts)
+  in jMonkeyEngine3. Reads specially prepared blender files to
+  automatically generate proprioceptive senses."
+  (:use (cortex world util sense body))
+  (:use clojure.contrib.def))
+        
 
 (cortex.import/mega-import-jme3)
 
-(defn right-handed? [vec1 vec2 vec3]
+(defvar 
+  ^{:arglists '([creature])}
+  joints
+  (sense-nodes "joints")
+  "Return the children of the creature's \"joints\" node.")
+
+(defn right-handed?
+  "true iff the three vectors form a right handed coordinate
+  system. The three vectors do not have to be normalized or
+  orthogonal."
+  [vec1 vec2 vec3]
   (< 0 (.dot (.cross vec1 vec2) vec3)))
 
-(defn absolute-angle [vec1 vec2 axis]
+(defn absolute-angle
+  "The angle between 'vec1 and 'vec2. Positive if the angle to get
+  from 'vec1 to 'vec2 is counterclockwise around 'axis, and negative
+  otherwise." 
+  [vec1 vec2 axis]
   (let [angle (.angleBetween vec1 vec2)]
     (if (right-handed? vec1 vec2 axis)
       angle (- (* 2 Math/PI) angle))))
 
-
-(defn joint-proprioception [#^Node parts #^Node joint]
+(defn proprioception-fn
+  "Returns a function which returns proprioceptive sensory data when
+  called inside a running simulation."
+  [#^Node parts #^Node joint]
   (let [[obj-a obj-b] (joint-targets parts joint)
         joint-rot (.getWorldRotation joint)
         x0 (.mult joint-rot Vector3f/UNIT_X)
@@ -55,16 +77,17 @@
                (let [cross (.normalize (.cross X x))]
                  (if (= 0 (.length cross)) y cross))))
             roll (absolute-angle (.mult reverse Y) y x)]
-        
         [heading pitch roll]))))
 
-(defn proprioception
-  "Create a function that provides proprioceptive information about an
-  entire body."
+(defn proprioception!
+  "Endow the creature with the sense of proprioception. Returns a
+   sequence of functions, one for each child of the \"joints\" node in
+   the creature, which each report proprioceptive information about
+   that joint."
   [#^Node creature]
   ;; extract the body's joints
-  (let [joints (creature-joints creature)
-        senses (map (partial joint-proprioception creature) joints)]
+  (let [senses (map (partial proprioception-fn creature)
+                    (joints creature))]
     (fn []
       (map #(%) senses))))
 
diff -r 04a39e6bb695 -r 1943b3f581c2 org/test-creature.org
--- a/org/test-creature.org	Sat Feb 04 05:08:35 2012 -0700
+++ b/org/test-creature.org	Sat Feb 04 06:26:40 2012 -0700
@@ -189,7 +189,7 @@
                              hearing-senses)
         bell (AudioNode. (asset-manager)
                          "Sounds/pure.wav" false)
-        prop (proprioception creature)
+        prop (proprioception! creature)
         prop-debug (proprioception-debug-window)
 
         muscle-fns (enable-muscles creature)