# HG changeset patch
# User Robert McIntyre <rlm@mit.edu>
# Date 1329205062 25200
# Node ID 5d7961d7fded6849c04267e4edff01f90d86ed41
# Parent  96b746a0b39890def78b600c2d223215ec0ea27f
wrote intro text for proprioception

diff -r 96b746a0b398 -r 5d7961d7fded org/proprioception.org
--- a/org/proprioception.org	Mon Feb 13 23:45:38 2012 -0700
+++ b/org/proprioception.org	Tue Feb 14 00:37:42 2012 -0700
@@ -6,23 +6,46 @@
 #+SETUPFILE: ../../aurellem/org/setup.org
 #+INCLUDE: ../../aurellem/org/level-0.org
 
-#+name: proprioception
+* Proprioception
+
+Close your eyes, and touch your nose with your right index finger. How
+did you do it? You could not see your hand, and neither your hand nor
+your nose could use the sense of touch to guide the path of your hand.
+There are no sound cues, and Taste and Smell certainly don't provide
+any help. You know where your hand is without your other senses
+because of Proprioception.
+
+Humans can sometimes loose this sense through viral infections or
+damage to the spinal cord or brain, and when they do, they loose the
+ability to control their own bodies without looking directly at the
+parts they want to move. In [[http://en.wikipedia.org/wiki/The_Man_Who_Mistook_His_Wife_for_a_Hat][The Man Who Mistook His Wife for a Hat]],
+a woman named Christina looses this sense and has to learn how to move
+by carefully watching her arms and legs. She describes proprioception
+as the "eyes of the body, the way the body sees itself". 
+
+Proprioception in humans is mediated by [[http://en.wikipedia.org/wiki/Articular_capsule][joint capsules]], [[http://en.wikipedia.org/wiki/Muscle_spindle][muscle
+spindles]], and the [[http://en.wikipedia.org/wiki/Golgi_tendon_organ][Golgi tendon organs]]. These measure the relative
+positions of each pody part by monitoring muscle strain and length.
+
+It's clear that this is a vital sense for fulid, graceful
+movement. It's also particurally easy to implement in jMonkeyEngine.
+
+My simulated proprioception calculates the relative angles of each
+joint from the rest position defined in the blender file. This
+simulates the muscle-spindles and joint capsules.  I will deal with
+Golgi tendon organs, which calculate muscle strain, in the [[./movement.org][next post]].
+
+* Helper Functions
+
+
+#+name: helpers
 #+begin_src clojure
-(ns cortex.proprioception
-  "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)
-  (:import com.jme3.scene.Node)
-  (:import java.awt.image.BufferedImage)
-  (:import (com.jme3.math Vector3f Quaternion)))
+(in-ns 'cortex.proprioception)
 
 (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."
+   system. The three vectors do not have to be normalized or
+   orthogonal."
   [vec1 vec2 vec3]
   (< 0 (.dot (.cross vec1 vec2) vec3)))
 
@@ -34,8 +57,11 @@
   (let [angle (.angleBetween vec1 vec2)]
     (if (right-handed? vec1 vec2 axis)
       angle (- (* 2 Math/PI) angle))))
+#+end_src
 
-(defn proprioception-fn
+#+name: proprioception
+#+begin_src clojure
+(defn proprioception-kernel
   "Returns a function which returns proprioceptive sensory data when
   called inside a running simulation."
   [#^Node parts #^Node joint]
@@ -80,18 +106,21 @@
    that joint."
   [#^Node creature]
   ;; extract the body's joints
-  (let [senses (map (partial proprioception-fn creature)
+  (let [senses (map (partial proprioception-kernel creature)
                     (joints creature))]
     (fn []
       (map #(%) senses))))
+#+end_src
 
+#+name: visualize
+#+begin_src clojure 
+(in-ns 'cortex.proprioception)
 
 (defn draw-sprite [image sprite x y color ]
   (dorun
    (for [[u v] sprite]
      (.setRGB image (+ u x) (+ v y) color))))
 
-
 (defn view-angle
   "create a debug view of an angle"
   [color]
@@ -143,15 +172,24 @@
    display each element of the list to the screen as an image."
   []
   (view-sense proprioception-display-kernel))
-  
-  
+#+end_src
 
+#+name: proprioception-header
+#+begin_src clojure
+(ns cortex.proprioception
+  "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)
+  (:import com.jme3.scene.Node)
+  (:import java.awt.image.BufferedImage)
+  (:import (com.jme3.math Vector3f Quaternion)))
 #+end_src
 
 #+name: test-body
 #+begin_src clojure
-
-
 (defn test-proprioception
   "Testing proprioception:
    You should see two foating bars, and a printout of pitch, yaw, and
@@ -246,5 +284,8 @@
 
 * COMMENT generate source
 #+begin_src clojure :tangle ../src/cortex/proprioception.clj
+<<proprioception-header>>
+<<helpers>>
 <<proprioception>>
+<<visualize>>
 #+end_src