1.1 --- a/thesis/Makefile	Sat Mar 29 20:33:35 2014 -0400
     1.2 +++ b/thesis/Makefile	Sat Mar 29 20:35:44 2014 -0400
     1.3 @@ -9,7 +9,7 @@
     1.4  		/home/r/proj/cortex/thesis "r@aurellem.org:~"
     1.5  	ssh r@aurellem.org cd "~/thesis; $(INVOKE_LATEX)"
     1.6  	scp "r@aurellem.org:/home/r/thesis/$(THESIS_NAME).pdf" .
     1.7 -	rm cortex.tex abstract.tex user-guide.tex
     1.8 +	rm cortex.tex abstract.tex
     1.9  
    1.10  
    1.11  

     2.1 --- a/thesis/user-guide.org	Sat Mar 29 20:33:35 2014 -0400
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,365 +0,0 @@
     2.4 -* Appendix: =CORTEX= User Guide
     2.5 -
     2.6 -  Those who write a thesis should endeavor to make their code not only
     2.7 -  accessable, but actually useable, as a way to pay back the community
     2.8 -  that made the thesis possible in the first place. This thesis would
     2.9 -  not be possible without Free Software such as jMonkeyEngine3,
    2.10 -  Blender, clojure, emacs, ffmpeg, and many other tools. That is why I
    2.11 -  have included this user guide, in the hope that someone else might
    2.12 -  find =CORTEX= useful.
    2.13 -
    2.14 -** Obtaining =CORTEX= 
    2.15 -
    2.16 -   You can get cortex from its mercurial repository at
    2.17 -   http://hg.bortreb.com/cortex. You may also download =CORTEX=
    2.18 -   releases at http://aurellem.org/cortex/releases/. As a condition of
    2.19 -   making this thesis, I have also provided Professor Winston the
    2.20 -   =CORTEX= source, and he knows how to run the demos and get started.
    2.21 -   You may also email me at =cortex@aurellem.org= and I may help where
    2.22 -   I can.
    2.23 -
    2.24 -** Running =CORTEX= 
    2.25 -   
    2.26 -   =CORTEX= comes with README and INSTALL files that will guide you
    2.27 -   through installation and running the test suite. In particular you
    2.28 -   should look at test =cortex.test= which contains test suites that
    2.29 -   run through all senses and multiple creatures.
    2.30 -
    2.31 -** Creating creatures
    2.32 -
    2.33 -   Creatures are created using /Blender/, a free 3D modeling program.
    2.34 -   You will need Blender version 2.6 when using the =CORTEX= included
    2.35 -   in this thesis. You create a =CORTEX= creature in a similiar manner
    2.36 -   to modeling anything in Blender, except that you also create
    2.37 -   several trees of empty nodes which define the creature's senses.
    2.38 -
    2.39 -*** Mass 
    2.40 -    
    2.41 -    To give an object mass in =CORTEX=, add a ``mass'' metadata label
    2.42 -    to the object with the mass in jMonkeyEngine units. Note that
    2.43 -    setting the mass to 0 causes the object to be immovable.
    2.44 -
    2.45 -*** Joints
    2.46 -
    2.47 -    Joints are created by creating an empty node named =joints= and
    2.48 -    then creating any number of empty child nodes to represent your
    2.49 -    creature's joints. The joint will automatically connect the
    2.50 -    closest two physical objects. It will help to set the empty node's
    2.51 -    display mode to ``Arrows'' so that you can clearly see the
    2.52 -    direction of the axes.
    2.53 -   
    2.54 -    Joint nodes should have the following metadata under the ``joint''
    2.55 -    label:
    2.56 -
    2.57 -    #+BEGIN_SRC clojure
    2.58 -;; ONE OF the following, under the label "joint":
    2.59 -{:type :point}
    2.60 -
    2.61 -;; OR
    2.62 -
    2.63 -{:type :hinge
    2.64 - :limit [<limit-low> <limit-high>]
    2.65 - :axis (Vector3f. <x> <y> <z>)}
    2.66 -;;(:axis defaults to (Vector3f. 1 0 0) if not provided for hinge joints)
    2.67 -
    2.68 -;; OR
    2.69 -
    2.70 -{:type :cone
    2.71 - :limit-xz <lim-xz>
    2.72 - :limit-xy <lim-xy>
    2.73 - :twist    <lim-twist>}   ;(use XZY rotation mode in blender!)
    2.74 -    #+END_SRC
    2.75 -
    2.76 -*** Eyes
    2.77 -
    2.78 -    Eyes are created by creating an empty node named =eyes= and then
    2.79 -    creating any number of empty child nodes to represent your
    2.80 -    creature's eyes.
    2.81 -
    2.82 -    Eye nodes should have the following metadata under the ``eye''
    2.83 -    label:
    2.84 -
    2.85 -#+BEGIN_SRC clojure
    2.86 -{:red    <red-retina-definition>
    2.87 - :blue   <blue-retina-definition>
    2.88 - :green  <green-retina-definition>
    2.89 - :all    <all-retina-definition>
    2.90 - (<0xrrggbb> <custom-retina-image>)...
    2.91 -}
    2.92 -#+END_SRC
    2.93 -
    2.94 -    Any of the color channels may be omitted. You may also include
    2.95 -    your own color selectors, and in fact :red is equivalent to
    2.96 -    0xFF0000 and so forth. The eye will be placed at the same position
    2.97 -    as the empty node and will bind to the neatest physical object.
    2.98 -    The eye will point outward from the X-axis of the node, and ``up''
    2.99 -    will be in the direction of the X-axis of the node. It will help
   2.100 -    to set the empty node's display mode to ``Arrows'' so that you can
   2.101 -    clearly see the direction of the axes.
   2.102 -
   2.103 -    Each retina file should contain white pixels whever you want to be
   2.104 -    sensitive to your chosen color. If you want the entire field of
   2.105 -    view, specify :all of 0xFFFFFF and a retinal map that is entirely
   2.106 -    white. 
   2.107 -
   2.108 -    Here is a sample retinal map:
   2.109 -
   2.110 -    #+caption: An example retinal profile image. White pixels are 
   2.111 -    #+caption: photo-sensitive elements. The distribution of white 
   2.112 -    #+caption: pixels is denser in the middle and falls off at the 
   2.113 -    #+caption: edges and is inspired by the human retina.
   2.114 -    #+name: retina
   2.115 -    #+ATTR_LaTeX: :width 7cm :placement [H]
   2.116 -    [[./images/retina-small.png]]
   2.117 -
   2.118 -*** Hearing
   2.119 -
   2.120 -    Ears are created by creating an empty node named =ears= and then
   2.121 -    creating any number of empty child nodes to represent your
   2.122 -    creature's ears. 
   2.123 -
   2.124 -    Ear nodes do not require any metadata.
   2.125 -
   2.126 -    The ear will bind to and follow the closest physical node.
   2.127 -
   2.128 -*** Touch
   2.129 -
   2.130 -    Touch is handled similarly to mass. To make a particular object
   2.131 -    touch sensitive, add metadata of the following form under the
   2.132 -    object's ``touch'' metadata field:
   2.133 -    
   2.134 -    #+BEGIN_EXAMPLE
   2.135 -    <touch-UV-map-file-name>    
   2.136 -    #+END_EXAMPLE
   2.137 -
   2.138 -    You may also include an optional ``scale'' metadata number to
   2.139 -    specifiy the length of the touch feelers. The default is $0.1$,
   2.140 -    and this is generally sufficient.
   2.141 -
   2.142 -    The touch UV should contain white pixels for each touch sensor.
   2.143 -
   2.144 -    Here is an example touch-uv map that approximates a human finger,
   2.145 -    and its corresponding model.
   2.146 -
   2.147 -    #+caption: This is the tactile-sensor-profile for the upper segment 
   2.148 -    #+caption: of a fingertip. It defines regions of high touch sensitivity 
   2.149 -    #+caption: (where there are many white pixels) and regions of low 
   2.150 -    #+caption: sensitivity (where white pixels are sparse).
   2.151 -    #+name: guide-fingertip-UV
   2.152 -    #+ATTR_LaTeX: :width 9cm :placement [H]
   2.153 -    [[./images/finger-UV.png]]
   2.154 -
   2.155 -    #+caption: The fingertip UV-image form above applied to a simple
   2.156 -    #+caption: model of a fingertip.
   2.157 -    #+name: guide-fingertip
   2.158 -    #+ATTR_LaTeX: :width 9cm :placement [H]
   2.159 -    [[./images/finger-2.png]]
   2.160 -
   2.161 -*** Propriocepotion
   2.162 -
   2.163 -    Proprioception is tied to each joint node -- nothing special must
   2.164 -    be done in a blender model to enable proprioception other than
   2.165 -    creating joint nodes.
   2.166 -
   2.167 -*** Muscles
   2.168 -
   2.169 -    Muscles are created by creating an empty node named =muscles= and
   2.170 -    then creating any number of empty child nodes to represent your
   2.171 -    creature's muscles.
   2.172 -
   2.173 -    
   2.174 -    Muscle nodes should have the following metadata under the
   2.175 -    ``muscle'' label:
   2.176 -
   2.177 -    #+BEGIN_EXAMPLE
   2.178 -    <muscle-profile-file-name>
   2.179 -    #+END_EXAMPLE
   2.180 -
   2.181 -    Muscles should also have a ``strength'' metadata entry describing
   2.182 -    the muscle's total strength at full activation. 
   2.183 -
   2.184 -    Muscle profiles are simple images that contain the relative amount
   2.185 -    of muscle power in each simulated alpha motor neuron. The width of
   2.186 -    the image is the total size of the motor pool, and the redness of
   2.187 -    each neuron is the relative power of that motor pool.
   2.188 -
   2.189 -    While the profile image can have any dimensions, only the first
   2.190 -    line of pixels is used to define the muscle. Here is a sample
   2.191 -    muscle profile image that defines a human-like muscle.
   2.192 -
   2.193 -    #+caption: A muscle profile image that describes the strengths
   2.194 -    #+caption: of each motor neuron in a muscle. White is weakest 
   2.195 -    #+caption: and dark red is strongest. This particular pattern 
   2.196 -    #+caption: has weaker motor neurons at the beginning, just 
   2.197 -    #+caption: like human muscle.
   2.198 -    #+name: muscle-recruit
   2.199 -    #+ATTR_LaTeX: :width 7cm :placement [H]
   2.200 -    [[./images/basic-muscle.png]]
   2.201 -    
   2.202 -    Muscles twist the nearest physical object about the muscle node's
   2.203 -    Z-axis. I recommend using the ``Single Arrow'' display mode for
   2.204 -    muscles and using the right hand rule to determine which way the
   2.205 -    muscle will twist. To make a segment that can twist in multiple
   2.206 -    directions, create multiple, differently aligned muscles.
   2.207 -
   2.208 -** =CORTEX= API
   2.209 -
   2.210 -   These are the some functions exposed by =CORTEX= for creating
   2.211 -   worlds and simulating creatures. These are in addition to
   2.212 -   jMonkeyEngine3's extensive library, which is documented elsewhere.
   2.213 -
   2.214 -*** Simulation
   2.215 -   - =(world root-node key-map setup-fn update-fn)= :: create
   2.216 -        a simulation.
   2.217 -     - /root-node/     :: a =com.jme3.scene.Node= object which
   2.218 -          contains all of the objects that should be in the
   2.219 -          simulation.
   2.220 -
   2.221 -     - /key-map/       :: a map from strings describing keys to
   2.222 -          functions that should be executed whenever that key is
   2.223 -          pressed. the functions should take a SimpleApplication
   2.224 -          object and a boolean value. The SimpleApplication is the
   2.225 -          current simulation that is running, and the boolean is true
   2.226 -          if the key is being pressed, and false if it is being
   2.227 -          released. As an example,
   2.228 -          #+BEGIN_SRC clojure
   2.229 -       {"key-j" (fn [game value] (if value (println "key j pressed")))}		  
   2.230 -	  #+END_SRC
   2.231 -	  is a valid key-map which will cause the simulation to print
   2.232 -          a message whenever the 'j' key on the keyboard is pressed.
   2.233 -
   2.234 -     - /setup-fn/      :: a function that takes a =SimpleApplication=
   2.235 -          object. It is called once when initializing the simulation.
   2.236 -          Use it to create things like lights, change the gravity,
   2.237 -          initialize debug nodes, etc.
   2.238 -
   2.239 -     - /update-fn/     :: this function takes a =SimpleApplication=
   2.240 -          object and a float and is called every frame of the
   2.241 -          simulation. The float tells how many seconds is has been
   2.242 -          since the last frame was rendered, according to whatever
   2.243 -          clock jme is currently using. The default is to use IsoTimer
   2.244 -          which will result in this value always being the same.
   2.245 -
   2.246 -   - =(position-camera world position rotation)= :: set the position
   2.247 -        of the simulation's main camera.
   2.248 -
   2.249 -   - =(enable-debug world)= :: turn on debug wireframes for each
   2.250 -        simulated object.
   2.251 -
   2.252 -   - =(set-gravity world gravity)= :: set the gravity of a running
   2.253 -        simulation.
   2.254 -
   2.255 -   - =(box length width height & {options})= :: create a box in the
   2.256 -        simulation. Options is a hash map specifying texture, mass,
   2.257 -        etc. Possible options are =:name=, =:color=, =:mass=,
   2.258 -        =:friction=, =:texture=, =:material=, =:position=,
   2.259 -        =:rotation=, =:shape=, and =:physical?=.
   2.260 -
   2.261 -   - =(sphere radius & {options})= :: create a sphere in the simulation.
   2.262 -        Options are the same as in =box=.
   2.263 -
   2.264 -   - =(load-blender-model file-name)= :: create a node structure
   2.265 -        representing that described in a blender file.
   2.266 -
   2.267 -   - =(light-up-everything world)= :: distribute a standard compliment
   2.268 -        of lights throught the simulation. Should be adequate for most
   2.269 -        purposes.
   2.270 -
   2.271 -   - =(node-seq node)= :: return a recursuve list of the node's
   2.272 -        children.
   2.273 -
   2.274 -   - =(nodify name children)= :: construct a node given a node-name and
   2.275 -        desired children.
   2.276 -
   2.277 -   - =(add-element world element)= :: add an object to a running world
   2.278 -        simulation.
   2.279 -
   2.280 -   - =(set-accuracy world accuracy)= :: change the accuracy of the
   2.281 -        world's physics simulator.
   2.282 -
   2.283 -   - =(asset-manager)= :: get an /AssetManager/, a jMonkeyEngine
   2.284 -        construct that is useful for loading textures and is required
   2.285 -        for smooth interaction with jMonkeyEngine library functions.
   2.286 -
   2.287 -   - =(load-bullet)=   :: unpack native libraries and initialize
   2.288 -        blender. This function is required before other world building
   2.289 -        functions are called.
   2.290 -	
   2.291 -
   2.292 -*** Creature Manipulation / Import
   2.293 -
   2.294 -   - =(body! creature)= :: give the creature a physical body.
   2.295 -
   2.296 -   - =(vision! creature)= :: give the creature a sense of vision.
   2.297 -        Returns a list of functions which will each, when called
   2.298 -        during a simulation, return the vision data for the channel of
   2.299 -        one of the eyes. The functions are ordered depending on the
   2.300 -        alphabetical order of the names of the eye nodes in the
   2.301 -        blender file. The data returned by the functions is a vector
   2.302 -        containing the eye's /topology/, a vector of coordinates, and
   2.303 -        the eye's /data/, a vector of RGB values filtered by the eye's
   2.304 -        sensitivity. 
   2.305 -
   2.306 -   - =(hearing! creature)= :: give the creature a sense of hearing.
   2.307 -        Returns a list of functions, one for each ear, that when
   2.308 -        called will return a frame's worth of hearing data for that
   2.309 -        ear. The functions are ordered depending on the alphabetical
   2.310 -        order of the names of the ear nodes in the blender file. The
   2.311 -        data returned by the functions is an array PCM encoded wav
   2.312 -        data. 
   2.313 -
   2.314 -   - =(touch! creature)= :: give the creature a sense of touch. Returns
   2.315 -        a single function that must be called with the /root node/ of
   2.316 -        the world, and which will return a vector of /touch-data/
   2.317 -        one entry for each touch sensitive component, each entry of
   2.318 -        which contains a /topology/ that specifies the distribution of
   2.319 -        touch sensors, and the /data/, which is a vector of
   2.320 -        =[activation, length]= pairs for each touch hair.
   2.321 -
   2.322 -   - =(proprioception! creature)= :: give the creature the sense of
   2.323 -        proprioception. Returns a list of functions, one for each
   2.324 -        joint, that when called during a running simulation will
   2.325 -        report the =[headnig, pitch, roll]= of the joint.
   2.326 -
   2.327 -   - =(movement! creature)= :: give the creature the power of movement.
   2.328 -        Creates a list of functions, one for each muscle, that when
   2.329 -        called with an integer, will set the recruitment of that
   2.330 -        muscle to that integer, and will report the current power
   2.331 -        being exerted by the muscle. Order of muscles is determined by
   2.332 -        the alphabetical sort order of the names of the muscle nodes.
   2.333 -	
   2.334 -*** Visualization/Debug
   2.335 -
   2.336 -   - =(view-vision)= :: create a function that when called with a list
   2.337 -        of visual data returned from the functions made by =vision!=, 
   2.338 -        will display that visual data on the screen.
   2.339 -
   2.340 -   - =(view-hearing)= :: same as =view-vision= but for hearing.
   2.341 -
   2.342 -   - =(view-touch)= :: same as =view-vision= but for touch.
   2.343 -
   2.344 -   - =(view-proprioception)= :: same as =view-vision= but for
   2.345 -        proprioception.
   2.346 -
   2.347 -   - =(view-movement)= :: same as =view-vision= but for
   2.348 -        proprioception.
   2.349 -
   2.350 -   - =(view anything)= :: =view= is a polymorphic function that allows
   2.351 -        you to inspect almost anything you could reasonably expect to
   2.352 -        be able to ``see'' in =CORTEX=.
   2.353 -
   2.354 -   - =(text anything)= :: =text= is a polymorphic function that allows
   2.355 -        you to convert practically anything into a text string.	
   2.356 -
   2.357 -   - =(println-repl anything)= :: print messages to clojure's repl
   2.358 -        instead of the simulation's terminal window.
   2.359 -
   2.360 -   - =(mega-import-jme3)= :: for experimenting at the REPL. This
   2.361 -        function will import all jMonkeyEngine3 classes for immediate
   2.362 -        use.
   2.363 -
   2.364 -   - =(display-dialated-time world timer)= :: Shows the time as it is
   2.365 -        flowing in the simulation on a HUD display.
   2.366 -
   2.367 -
   2.368 -

     3.1 --- a/thesis/weave-thesis.sh	Sat Mar 29 20:33:35 2014 -0400
     3.2 +++ b/thesis/weave-thesis.sh	Sat Mar 29 20:35:44 2014 -0400
     3.3 @@ -9,8 +9,6 @@
     3.4  (progn
     3.5    (find-file \"cortex.org\")
     3.6    (org-latex-export-to-latex nil nil nil t nil) \
     3.7 -  (find-file \"user-guide.org\")
     3.8 -  (org-latex-export-to-latex nil nil nil t nil) \
     3.9    (find-file \"abstract.org\")
    3.10    (org-latex-export-to-latex nil nil nil t nil))" \
    3.11  \