1.1 --- a/thesis/cortex.bib	Sat Mar 29 20:17:58 2014 -0400
     1.2 +++ b/thesis/cortex.bib	Sat Mar 29 20:33:35 2014 -0400
     1.3 @@ -14,7 +14,13 @@
     1.4                    bullshit.}}
     1.5  }
     1.6  
     1.7 -
     1.8 +@misc{bworld,
     1.9 +  author = {Ingo Lütkebohle},
    1.10 +  title = {{BWorld Robot Control Software}},
    1.11 +  howpublished = "\url{http://aiweb.techfak.uni-bielefeld.de/content/bworld-robot-control-software/}",
    1.12 +  year = {2008}, 
    1.13 +  note = "[Online; accessed 19-July-2008]"
    1.14 +}
    1.15  @Comment Karl Sims evolved creatures
    1.16  
    1.17  @Comment SOM larson paper

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

     3.1 --- a/thesis/rlm-cortex-meng.tex	Sat Mar 29 20:17:58 2014 -0400
     3.2 +++ b/thesis/rlm-cortex-meng.tex	Sat Mar 29 20:33:35 2014 -0400
     3.3 @@ -126,12 +126,13 @@
     3.4  \include{cortex}
     3.5  \nocite{*}
     3.6  %\include{chap2}
     3.7 -\appendix
     3.8 -\begin{singlespace}
     3.9 +%\appendix
    3.10 +
    3.11  %\bibliographystyle{agsm}
    3.12  %\bibliographystyle{apa}
    3.13  %\bibliographystyle{plainnat}
    3.14 -\include{user-guide}
    3.15 +%\include{user-guide}
    3.16 +\begin{singlespace}
    3.17  \printbibliography
    3.18  \end{singlespace}
    3.19  \end{document}