cortex: thesis/old-cortex.org annotate

annotate thesis/old-cortex.org @ 516:ced955c3c84f

resurrect old cortex to fix flow issues.

author	Robert McIntyre <rlm@mit.edu>
date	Sun, 30 Mar 2014 22:48:19 -0400
parents
children

rev	line source
rlm@516	1 #+title: =CORTEX=
rlm@516	2 #+author: Robert McIntyre
rlm@516	3 #+email: rlm@mit.edu
rlm@516	4 #+description: Using embodied AI to facilitate Artificial Imagination.
rlm@516	5 #+keywords: AI, clojure, embodiment
rlm@516	6 #+LaTeX_CLASS_OPTIONS: [nofloat]
rlm@516	7
rlm@516	8 * COMMENT templates
rlm@516	9 #+caption:
rlm@516	10 #+caption:
rlm@516	11 #+caption:
rlm@516	12 #+caption:
rlm@516	13 #+name: name
rlm@516	14 #+begin_listing clojure
rlm@516	15 #+BEGIN_SRC clojure
rlm@516	16 #+END_SRC
rlm@516	17 #+end_listing
rlm@516	18
rlm@516	19 #+caption:
rlm@516	20 #+caption:
rlm@516	21 #+caption:
rlm@516	22 #+name: name
rlm@516	23 #+ATTR_LaTeX: :width 10cm
rlm@516	24 [[./images/aurellem-gray.png]]
rlm@516	25
rlm@516	26 #+caption:
rlm@516	27 #+caption:
rlm@516	28 #+caption:
rlm@516	29 #+caption:
rlm@516	30 #+name: name
rlm@516	31 #+begin_listing clojure
rlm@516	32 #+BEGIN_SRC clojure
rlm@516	33 #+END_SRC
rlm@516	34 #+end_listing
rlm@516	35
rlm@516	36 #+caption:
rlm@516	37 #+caption:
rlm@516	38 #+caption:
rlm@516	39 #+name: name
rlm@516	40 #+ATTR_LaTeX: :width 10cm
rlm@516	41 [[./images/aurellem-gray.png]]
rlm@516	42
rlm@516	43
rlm@516	44 * Empathy and Embodiment as problem solving strategies
rlm@516	45
rlm@516	46 By the end of this thesis, you will have seen a novel approach to
rlm@516	47 interpreting video using embodiment and empathy. You will have also
rlm@516	48 seen one way to efficiently implement empathy for embodied
rlm@516	49 creatures. Finally, you will become familiar with =CORTEX=, a system
rlm@516	50 for designing and simulating creatures with rich senses, which you
rlm@516	51 may choose to use in your own research.
rlm@516	52
rlm@516	53 This is the core vision of my thesis: That one of the important ways
rlm@516	54 in which we understand others is by imagining ourselves in their
rlm@516	55 position and emphatically feeling experiences relative to our own
rlm@516	56 bodies. By understanding events in terms of our own previous
rlm@516	57 corporeal experience, we greatly constrain the possibilities of what
rlm@516	58 would otherwise be an unwieldy exponential search. This extra
rlm@516	59 constraint can be the difference between easily understanding what
rlm@516	60 is happening in a video and being completely lost in a sea of
rlm@516	61 incomprehensible color and movement.
rlm@516	62
rlm@516	63 ** Recognizing actions in video is extremely difficult
rlm@516	64
rlm@516	65 Consider for example the problem of determining what is happening
rlm@516	66 in a video of which this is one frame:
rlm@516	67
rlm@516	68 #+caption: A cat drinking some water. Identifying this action is
rlm@516	69 #+caption: beyond the state of the art for computers.
rlm@516	70 #+ATTR_LaTeX: :width 7cm
rlm@516	71 [[./images/cat-drinking.jpg]]
rlm@516	72
rlm@516	73 It is currently impossible for any computer program to reliably
rlm@516	74 label such a video as ``drinking''. And rightly so -- it is a very
rlm@516	75 hard problem! What features can you describe in terms of low level
rlm@516	76 functions of pixels that can even begin to describe at a high level
rlm@516	77 what is happening here?
rlm@516	78
rlm@516	79 Or suppose that you are building a program that recognizes chairs.
rlm@516	80 How could you ``see'' the chair in figure \ref{hidden-chair}?
rlm@516	81
rlm@516	82 #+caption: The chair in this image is quite obvious to humans, but I
rlm@516	83 #+caption: doubt that any modern computer vision program can find it.
rlm@516	84 #+name: hidden-chair
rlm@516	85 #+ATTR_LaTeX: :width 10cm
rlm@516	86 [[./images/fat-person-sitting-at-desk.jpg]]
rlm@516	87
rlm@516	88 Finally, how is it that you can easily tell the difference between
rlm@516	89 how the girls /muscles/ are working in figure \ref{girl}?
rlm@516	90
rlm@516	91 #+caption: The mysterious ``common sense'' appears here as you are able
rlm@516	92 #+caption: to discern the difference in how the girl's arm muscles
rlm@516	93 #+caption: are activated between the two images.
rlm@516	94 #+name: girl
rlm@516	95 #+ATTR_LaTeX: :width 7cm
rlm@516	96 [[./images/wall-push.png]]
rlm@516	97
rlm@516	98 Each of these examples tells us something about what might be going
rlm@516	99 on in our minds as we easily solve these recognition problems.
rlm@516	100
rlm@516	101 The hidden chairs show us that we are strongly triggered by cues
rlm@516	102 relating to the position of human bodies, and that we can determine
rlm@516	103 the overall physical configuration of a human body even if much of
rlm@516	104 that body is occluded.
rlm@516	105
rlm@516	106 The picture of the girl pushing against the wall tells us that we
rlm@516	107 have common sense knowledge about the kinetics of our own bodies.
rlm@516	108 We know well how our muscles would have to work to maintain us in
rlm@516	109 most positions, and we can easily project this self-knowledge to
rlm@516	110 imagined positions triggered by images of the human body.
rlm@516	111
rlm@516	112 ** =EMPATH= neatly solves recognition problems
rlm@516	113
rlm@516	114 I propose a system that can express the types of recognition
rlm@516	115 problems above in a form amenable to computation. It is split into
rlm@516	116 four parts:
rlm@516	117
rlm@516	118 - Free/Guided Play :: The creature moves around and experiences the
rlm@516	119 world through its unique perspective. Many otherwise
rlm@516	120 complicated actions are easily described in the language of a
rlm@516	121 full suite of body-centered, rich senses. For example,
rlm@516	122 drinking is the feeling of water sliding down your throat, and
rlm@516	123 cooling your insides. It's often accompanied by bringing your
rlm@516	124 hand close to your face, or bringing your face close to water.
rlm@516	125 Sitting down is the feeling of bending your knees, activating
rlm@516	126 your quadriceps, then feeling a surface with your bottom and
rlm@516	127 relaxing your legs. These body-centered action descriptions
rlm@516	128 can be either learned or hard coded.
rlm@516	129 - Posture Imitation :: When trying to interpret a video or image,
rlm@516	130 the creature takes a model of itself and aligns it with
rlm@516	131 whatever it sees. This alignment can even cross species, as
rlm@516	132 when humans try to align themselves with things like ponies,
rlm@516	133 dogs, or other humans with a different body type.
rlm@516	134 - Empathy :: The alignment triggers associations with
rlm@516	135 sensory data from prior experiences. For example, the
rlm@516	136 alignment itself easily maps to proprioceptive data. Any
rlm@516	137 sounds or obvious skin contact in the video can to a lesser
rlm@516	138 extent trigger previous experience. Segments of previous
rlm@516	139 experiences are stitched together to form a coherent and
rlm@516	140 complete sensory portrait of the scene.
rlm@516	141 - Recognition :: With the scene described in terms of first
rlm@516	142 person sensory events, the creature can now run its
rlm@516	143 action-identification programs on this synthesized sensory
rlm@516	144 data, just as it would if it were actually experiencing the
rlm@516	145 scene first-hand. If previous experience has been accurately
rlm@516	146 retrieved, and if it is analogous enough to the scene, then
rlm@516	147 the creature will correctly identify the action in the scene.
rlm@516	148
rlm@516	149 For example, I think humans are able to label the cat video as
rlm@516	150 ``drinking'' because they imagine /themselves/ as the cat, and
rlm@516	151 imagine putting their face up against a stream of water and
rlm@516	152 sticking out their tongue. In that imagined world, they can feel
rlm@516	153 the cool water hitting their tongue, and feel the water entering
rlm@516	154 their body, and are able to recognize that /feeling/ as drinking.
rlm@516	155 So, the label of the action is not really in the pixels of the
rlm@516	156 image, but is found clearly in a simulation inspired by those
rlm@516	157 pixels. An imaginative system, having been trained on drinking and
rlm@516	158 non-drinking examples and learning that the most important
rlm@516	159 component of drinking is the feeling of water sliding down one's
rlm@516	160 throat, would analyze a video of a cat drinking in the following
rlm@516	161 manner:
rlm@516	162
rlm@516	163 1. Create a physical model of the video by putting a ``fuzzy''
rlm@516	164 model of its own body in place of the cat. Possibly also create
rlm@516	165 a simulation of the stream of water.
rlm@516	166
rlm@516	167 2. Play out this simulated scene and generate imagined sensory
rlm@516	168 experience. This will include relevant muscle contractions, a
rlm@516	169 close up view of the stream from the cat's perspective, and most
rlm@516	170 importantly, the imagined feeling of water entering the
rlm@516	171 mouth. The imagined sensory experience can come from a
rlm@516	172 simulation of the event, but can also be pattern-matched from
rlm@516	173 previous, similar embodied experience.
rlm@516	174
rlm@516	175 3. The action is now easily identified as drinking by the sense of
rlm@516	176 taste alone. The other senses (such as the tongue moving in and
rlm@516	177 out) help to give plausibility to the simulated action. Note that
rlm@516	178 the sense of vision, while critical in creating the simulation,
rlm@516	179 is not critical for identifying the action from the simulation.
rlm@516	180
rlm@516	181 For the chair examples, the process is even easier:
rlm@516	182
rlm@516	183 1. Align a model of your body to the person in the image.
rlm@516	184
rlm@516	185 2. Generate proprioceptive sensory data from this alignment.
rlm@516	186
rlm@516	187 3. Use the imagined proprioceptive data as a key to lookup related
rlm@516	188 sensory experience associated with that particular proproceptive
rlm@516	189 feeling.
rlm@516	190
rlm@516	191 4. Retrieve the feeling of your bottom resting on a surface, your
rlm@516	192 knees bent, and your leg muscles relaxed.
rlm@516	193
rlm@516	194 5. This sensory information is consistent with the =sitting?=
rlm@516	195 sensory predicate, so you (and the entity in the image) must be
rlm@516	196 sitting.
rlm@516	197
rlm@516	198 6. There must be a chair-like object since you are sitting.
rlm@516	199
rlm@516	200 Empathy offers yet another alternative to the age-old AI
rlm@516	201 representation question: ``What is a chair?'' --- A chair is the
rlm@516	202 feeling of sitting.
rlm@516	203
rlm@516	204 My program, =EMPATH= uses this empathic problem solving technique
rlm@516	205 to interpret the actions of a simple, worm-like creature.
rlm@516	206
rlm@516	207 #+caption: The worm performs many actions during free play such as
rlm@516	208 #+caption: curling, wiggling, and resting.
rlm@516	209 #+name: worm-intro
rlm@516	210 #+ATTR_LaTeX: :width 15cm
rlm@516	211 [[./images/worm-intro-white.png]]
rlm@516	212
rlm@516	213 #+caption: =EMPATH= recognized and classified each of these
rlm@516	214 #+caption: poses by inferring the complete sensory experience
rlm@516	215 #+caption: from proprioceptive data.
rlm@516	216 #+name: worm-recognition-intro
rlm@516	217 #+ATTR_LaTeX: :width 15cm
rlm@516	218 [[./images/worm-poses.png]]
rlm@516	219
rlm@516	220 One powerful advantage of empathic problem solving is that it
rlm@516	221 factors the action recognition problem into two easier problems. To
rlm@516	222 use empathy, you need an /aligner/, which takes the video and a
rlm@516	223 model of your body, and aligns the model with the video. Then, you
rlm@516	224 need a /recognizer/, which uses the aligned model to interpret the
rlm@516	225 action. The power in this method lies in the fact that you describe
rlm@516	226 all actions form a body-centered viewpoint. You are less tied to
rlm@516	227 the particulars of any visual representation of the actions. If you
rlm@516	228 teach the system what ``running'' is, and you have a good enough
rlm@516	229 aligner, the system will from then on be able to recognize running
rlm@516	230 from any point of view, even strange points of view like above or
rlm@516	231 underneath the runner. This is in contrast to action recognition
rlm@516	232 schemes that try to identify actions using a non-embodied approach.
rlm@516	233 If these systems learn about running as viewed from the side, they
rlm@516	234 will not automatically be able to recognize running from any other
rlm@516	235 viewpoint.
rlm@516	236
rlm@516	237 Another powerful advantage is that using the language of multiple
rlm@516	238 body-centered rich senses to describe body-centerd actions offers a
rlm@516	239 massive boost in descriptive capability. Consider how difficult it
rlm@516	240 would be to compose a set of HOG filters to describe the action of
rlm@516	241 a simple worm-creature ``curling'' so that its head touches its
rlm@516	242 tail, and then behold the simplicity of describing thus action in a
rlm@516	243 language designed for the task (listing \ref{grand-circle-intro}):
rlm@516	244
rlm@516	245 #+caption: Body-centerd actions are best expressed in a body-centered
rlm@516	246 #+caption: language. This code detects when the worm has curled into a
rlm@516	247 #+caption: full circle. Imagine how you would replicate this functionality
rlm@516	248 #+caption: using low-level pixel features such as HOG filters!
rlm@516	249 #+name: grand-circle-intro
rlm@516	250 #+begin_listing clojure
rlm@516	251 #+begin_src clojure
rlm@516	252 (defn grand-circle?
rlm@516	253 "Does the worm form a majestic circle (one end touching the other)?"
rlm@516	254 [experiences]
rlm@516	255 (and (curled? experiences)
rlm@516	256 (let [worm-touch (:touch (peek experiences))
rlm@516	257 tail-touch (worm-touch 0)
rlm@516	258 head-touch (worm-touch 4)]
rlm@516	259 (and (< 0.2 (contact worm-segment-bottom-tip tail-touch))
rlm@516	260 (< 0.2 (contact worm-segment-top-tip head-touch))))))
rlm@516	261 #+end_src
rlm@516	262 #+end_listing
rlm@516	263
rlm@516	264 ** =CORTEX= is a toolkit for building sensate creatures
rlm@516	265
rlm@516	266 I built =CORTEX= to be a general AI research platform for doing
rlm@516	267 experiments involving multiple rich senses and a wide variety and
rlm@516	268 number of creatures. I intend it to be useful as a library for many
rlm@516	269 more projects than just this thesis. =CORTEX= was necessary to meet
rlm@516	270 a need among AI researchers at CSAIL and beyond, which is that
rlm@516	271 people often will invent neat ideas that are best expressed in the
rlm@516	272 language of creatures and senses, but in order to explore those
rlm@516	273 ideas they must first build a platform in which they can create
rlm@516	274 simulated creatures with rich senses! There are many ideas that
rlm@516	275 would be simple to execute (such as =EMPATH=), but attached to them
rlm@516	276 is the multi-month effort to make a good creature simulator. Often,
rlm@516	277 that initial investment of time proves to be too much, and the
rlm@516	278 project must make do with a lesser environment.
rlm@516	279
rlm@516	280 =CORTEX= is well suited as an environment for embodied AI research
rlm@516	281 for three reasons:
rlm@516	282
rlm@516	283 - You can create new creatures using Blender, a popular 3D modeling
rlm@516	284 program. Each sense can be specified using special blender nodes
rlm@516	285 with biologically inspired paramaters. You need not write any
rlm@516	286 code to create a creature, and can use a wide library of
rlm@516	287 pre-existing blender models as a base for your own creatures.
rlm@516	288
rlm@516	289 - =CORTEX= implements a wide variety of senses, including touch,
rlm@516	290 proprioception, vision, hearing, and muscle tension. Complicated
rlm@516	291 senses like touch, and vision involve multiple sensory elements
rlm@516	292 embedded in a 2D surface. You have complete control over the
rlm@516	293 distribution of these sensor elements through the use of simple
rlm@516	294 png image files. In particular, =CORTEX= implements more
rlm@516	295 comprehensive hearing than any other creature simulation system
rlm@516	296 available.
rlm@516	297
rlm@516	298 - =CORTEX= supports any number of creatures and any number of
rlm@516	299 senses. Time in =CORTEX= dialates so that the simulated creatures
rlm@516	300 always precieve a perfectly smooth flow of time, regardless of
rlm@516	301 the actual computational load.
rlm@516	302
rlm@516	303 =CORTEX= is built on top of =jMonkeyEngine3=, which is a video game
rlm@516	304 engine designed to create cross-platform 3D desktop games. =CORTEX=
rlm@516	305 is mainly written in clojure, a dialect of =LISP= that runs on the
rlm@516	306 java virtual machine (JVM). The API for creating and simulating
rlm@516	307 creatures and senses is entirely expressed in clojure, though many
rlm@516	308 senses are implemented at the layer of jMonkeyEngine or below. For
rlm@516	309 example, for the sense of hearing I use a layer of clojure code on
rlm@516	310 top of a layer of java JNI bindings that drive a layer of =C++=
rlm@516	311 code which implements a modified version of =OpenAL= to support
rlm@516	312 multiple listeners. =CORTEX= is the only simulation environment
rlm@516	313 that I know of that can support multiple entities that can each
rlm@516	314 hear the world from their own perspective. Other senses also
rlm@516	315 require a small layer of Java code. =CORTEX= also uses =bullet=, a
rlm@516	316 physics simulator written in =C=.
rlm@516	317
rlm@516	318 #+caption: Here is the worm from figure \ref{worm-intro} modeled
rlm@516	319 #+caption: in Blender, a free 3D-modeling program. Senses and
rlm@516	320 #+caption: joints are described using special nodes in Blender.
rlm@516	321 #+name: worm-recognition-intro
rlm@516	322 #+ATTR_LaTeX: :width 12cm
rlm@516	323 [[./images/blender-worm.png]]
rlm@516	324
rlm@516	325 Here are some thing I anticipate that =CORTEX= might be used for:
rlm@516	326
rlm@516	327 - exploring new ideas about sensory integration
rlm@516	328 - distributed communication among swarm creatures
rlm@516	329 - self-learning using free exploration,
rlm@516	330 - evolutionary algorithms involving creature construction
rlm@516	331 - exploration of exoitic senses and effectors that are not possible
rlm@516	332 in the real world (such as telekenisis or a semantic sense)
rlm@516	333 - imagination using subworlds
rlm@516	334
rlm@516	335 During one test with =CORTEX=, I created 3,000 creatures each with
rlm@516	336 their own independent senses and ran them all at only 1/80 real
rlm@516	337 time. In another test, I created a detailed model of my own hand,
rlm@516	338 equipped with a realistic distribution of touch (more sensitive at
rlm@516	339 the fingertips), as well as eyes and ears, and it ran at around 1/4
rlm@516	340 real time.
rlm@516	341
rlm@516	342 #+BEGIN_LaTeX
rlm@516	343 \begin{sidewaysfigure}
rlm@516	344 \includegraphics[width=9.5in]{images/full-hand.png}
rlm@516	345 \caption{
rlm@516	346 I modeled my own right hand in Blender and rigged it with all the
rlm@516	347 senses that {\tt CORTEX} supports. My simulated hand has a
rlm@516	348 biologically inspired distribution of touch sensors. The senses are
rlm@516	349 displayed on the right, and the simulation is displayed on the
rlm@516	350 left. Notice that my hand is curling its fingers, that it can see
rlm@516	351 its own finger from the eye in its palm, and that it can feel its
rlm@516	352 own thumb touching its palm.}
rlm@516	353 \end{sidewaysfigure}
rlm@516	354 #+END_LaTeX
rlm@516	355
rlm@516	356 ** Contributions
rlm@516	357
rlm@516	358 - I built =CORTEX=, a comprehensive platform for embodied AI
rlm@516	359 experiments. =CORTEX= supports many features lacking in other
rlm@516	360 systems, such proper simulation of hearing. It is easy to create
rlm@516	361 new =CORTEX= creatures using Blender, a free 3D modeling program.
rlm@516	362
rlm@516	363 - I built =EMPATH=, which uses =CORTEX= to identify the actions of
rlm@516	364 a worm-like creature using a computational model of empathy.
rlm@516	365
rlm@516	366 * Building =CORTEX=
rlm@516	367
rlm@516	368 I intend for =CORTEX= to be used as a general-purpose library for
rlm@516	369 building creatures and outfitting them with senses, so that it will
rlm@516	370 be useful for other researchers who want to test out ideas of their
rlm@516	371 own. To this end, wherver I have had to make archetictural choices
rlm@516	372 about =CORTEX=, I have chosen to give as much freedom to the user as
rlm@516	373 possible, so that =CORTEX= may be used for things I have not
rlm@516	374 forseen.
rlm@516	375
rlm@516	376 ** Simulation or Reality?
rlm@516	377
rlm@516	378 The most important archetictural decision of all is the choice to
rlm@516	379 use a computer-simulated environemnt in the first place! The world
rlm@516	380 is a vast and rich place, and for now simulations are a very poor
rlm@516	381 reflection of its complexity. It may be that there is a significant
rlm@516	382 qualatative difference between dealing with senses in the real
rlm@516	383 world and dealing with pale facilimilies of them in a simulation.
rlm@516	384 What are the advantages and disadvantages of a simulation vs.
rlm@516	385 reality?
rlm@516	386
rlm@516	387 *** Simulation
rlm@516	388
rlm@516	389 The advantages of virtual reality are that when everything is a
rlm@516	390 simulation, experiments in that simulation are absolutely
rlm@516	391 reproducible. It's also easier to change the character and world
rlm@516	392 to explore new situations and different sensory combinations.
rlm@516	393
rlm@516	394 If the world is to be simulated on a computer, then not only do
rlm@516	395 you have to worry about whether the character's senses are rich
rlm@516	396 enough to learn from the world, but whether the world itself is
rlm@516	397 rendered with enough detail and realism to give enough working
rlm@516	398 material to the character's senses. To name just a few
rlm@516	399 difficulties facing modern physics simulators: destructibility of
rlm@516	400 the environment, simulation of water/other fluids, large areas,
rlm@516	401 nonrigid bodies, lots of objects, smoke. I don't know of any
rlm@516	402 computer simulation that would allow a character to take a rock
rlm@516	403 and grind it into fine dust, then use that dust to make a clay
rlm@516	404 sculpture, at least not without spending years calculating the
rlm@516	405 interactions of every single small grain of dust. Maybe a
rlm@516	406 simulated world with today's limitations doesn't provide enough
rlm@516	407 richness for real intelligence to evolve.
rlm@516	408
rlm@516	409 *** Reality
rlm@516	410
rlm@516	411 The other approach for playing with senses is to hook your
rlm@516	412 software up to real cameras, microphones, robots, etc., and let it
rlm@516	413 loose in the real world. This has the advantage of eliminating
rlm@516	414 concerns about simulating the world at the expense of increasing
rlm@516	415 the complexity of implementing the senses. Instead of just
rlm@516	416 grabbing the current rendered frame for processing, you have to
rlm@516	417 use an actual camera with real lenses and interact with photons to
rlm@516	418 get an image. It is much harder to change the character, which is
rlm@516	419 now partly a physical robot of some sort, since doing so involves
rlm@516	420 changing things around in the real world instead of modifying
rlm@516	421 lines of code. While the real world is very rich and definitely
rlm@516	422 provides enough stimulation for intelligence to develop as
rlm@516	423 evidenced by our own existence, it is also uncontrollable in the
rlm@516	424 sense that a particular situation cannot be recreated perfectly or
rlm@516	425 saved for later use. It is harder to conduct science because it is
rlm@516	426 harder to repeat an experiment. The worst thing about using the
rlm@516	427 real world instead of a simulation is the matter of time. Instead
rlm@516	428 of simulated time you get the constant and unstoppable flow of
rlm@516	429 real time. This severely limits the sorts of software you can use
rlm@516	430 to program the AI because all sense inputs must be handled in real
rlm@516	431 time. Complicated ideas may have to be implemented in hardware or
rlm@516	432 may simply be impossible given the current speed of our
rlm@516	433 processors. Contrast this with a simulation, in which the flow of
rlm@516	434 time in the simulated world can be slowed down to accommodate the
rlm@516	435 limitations of the character's programming. In terms of cost,
rlm@516	436 doing everything in software is far cheaper than building custom
rlm@516	437 real-time hardware. All you need is a laptop and some patience.
rlm@516	438
rlm@516	439 ** Because of Time, simulation is perferable to reality
rlm@516	440
rlm@516	441 I envision =CORTEX= being used to support rapid prototyping and
rlm@516	442 iteration of ideas. Even if I could put together a well constructed
rlm@516	443 kit for creating robots, it would still not be enough because of
rlm@516	444 the scourge of real-time processing. Anyone who wants to test their
rlm@516	445 ideas in the real world must always worry about getting their
rlm@516	446 algorithms to run fast enough to process information in real time.
rlm@516	447 The need for real time processing only increases if multiple senses
rlm@516	448 are involved. In the extreme case, even simple algorithms will have
rlm@516	449 to be accelerated by ASIC chips or FPGAs, turning what would
rlm@516	450 otherwise be a few lines of code and a 10x speed penality into a
rlm@516	451 multi-month ordeal. For this reason, =CORTEX= supports
rlm@516	452 /time-dialiation/, which scales back the framerate of the
rlm@516	453 simulation in proportion to the amount of processing each frame.
rlm@516	454 From the perspective of the creatures inside the simulation, time
rlm@516	455 always appears to flow at a constant rate, regardless of how
rlm@516	456 complicated the envorimnent becomes or how many creatures are in
rlm@516	457 the simulation. The cost is that =CORTEX= can sometimes run slower
rlm@516	458 than real time. This can also be an advantage, however ---
rlm@516	459 simulations of very simple creatures in =CORTEX= generally run at
rlm@516	460 40x on my machine!
rlm@516	461
rlm@516	462 ** What is a sense?
rlm@516	463
rlm@516	464 If =CORTEX= is to support a wide variety of senses, it would help
rlm@516	465 to have a better understanding of what a ``sense'' actually is!
rlm@516	466 While vision, touch, and hearing all seem like they are quite
rlm@516	467 different things, I was supprised to learn during the course of
rlm@516	468 this thesis that they (and all physical senses) can be expressed as
rlm@516	469 exactly the same mathematical object due to a dimensional argument!
rlm@516	470
rlm@516	471 Human beings are three-dimensional objects, and the nerves that
rlm@516	472 transmit data from our various sense organs to our brain are
rlm@516	473 essentially one-dimensional. This leaves up to two dimensions in
rlm@516	474 which our sensory information may flow. For example, imagine your
rlm@516	475 skin: it is a two-dimensional surface around a three-dimensional
rlm@516	476 object (your body). It has discrete touch sensors embedded at
rlm@516	477 various points, and the density of these sensors corresponds to the
rlm@516	478 sensitivity of that region of skin. Each touch sensor connects to a
rlm@516	479 nerve, all of which eventually are bundled together as they travel
rlm@516	480 up the spinal cord to the brain. Intersect the spinal nerves with a
rlm@516	481 guillotining plane and you will see all of the sensory data of the
rlm@516	482 skin revealed in a roughly circular two-dimensional image which is
rlm@516	483 the cross section of the spinal cord. Points on this image that are
rlm@516	484 close together in this circle represent touch sensors that are
rlm@516	485 /probably/ close together on the skin, although there is of course
rlm@516	486 some cutting and rearrangement that has to be done to transfer the
rlm@516	487 complicated surface of the skin onto a two dimensional image.
rlm@516	488
rlm@516	489 Most human senses consist of many discrete sensors of various
rlm@516	490 properties distributed along a surface at various densities. For
rlm@516	491 skin, it is Pacinian corpuscles, Meissner's corpuscles, Merkel's
rlm@516	492 disks, and Ruffini's endings, which detect pressure and vibration
rlm@516	493 of various intensities. For ears, it is the stereocilia distributed
rlm@516	494 along the basilar membrane inside the cochlea; each one is
rlm@516	495 sensitive to a slightly different frequency of sound. For eyes, it
rlm@516	496 is rods and cones distributed along the surface of the retina. In
rlm@516	497 each case, we can describe the sense with a surface and a
rlm@516	498 distribution of sensors along that surface.
rlm@516	499
rlm@516	500 The neat idea is that every human sense can be effectively
rlm@516	501 described in terms of a surface containing embedded sensors. If the
rlm@516	502 sense had any more dimensions, then there wouldn't be enough room
rlm@516	503 in the spinal chord to transmit the information!
rlm@516	504
rlm@516	505 Therefore, =CORTEX= must support the ability to create objects and
rlm@516	506 then be able to ``paint'' points along their surfaces to describe
rlm@516	507 each sense.
rlm@516	508
rlm@516	509 Fortunately this idea is already a well known computer graphics
rlm@516	510 technique called called /UV-mapping/. The three-dimensional surface
rlm@516	511 of a model is cut and smooshed until it fits on a two-dimensional
rlm@516	512 image. You paint whatever you want on that image, and when the
rlm@516	513 three-dimensional shape is rendered in a game the smooshing and
rlm@516	514 cutting is reversed and the image appears on the three-dimensional
rlm@516	515 object.
rlm@516	516
rlm@516	517 To make a sense, interpret the UV-image as describing the
rlm@516	518 distribution of that senses sensors. To get different types of
rlm@516	519 sensors, you can either use a different color for each type of
rlm@516	520 sensor, or use multiple UV-maps, each labeled with that sensor
rlm@516	521 type. I generally use a white pixel to mean the presence of a
rlm@516	522 sensor and a black pixel to mean the absence of a sensor, and use
rlm@516	523 one UV-map for each sensor-type within a given sense.
rlm@516	524
rlm@516	525 #+CAPTION: The UV-map for an elongated icososphere. The white
rlm@516	526 #+caption: dots each represent a touch sensor. They are dense
rlm@516	527 #+caption: in the regions that describe the tip of the finger,
rlm@516	528 #+caption: and less dense along the dorsal side of the finger
rlm@516	529 #+caption: opposite the tip.
rlm@516	530 #+name: finger-UV
rlm@516	531 #+ATTR_latex: :width 10cm
rlm@516	532 [[./images/finger-UV.png]]
rlm@516	533
rlm@516	534 #+caption: Ventral side of the UV-mapped finger. Notice the
rlm@516	535 #+caption: density of touch sensors at the tip.
rlm@516	536 #+name: finger-side-view
rlm@516	537 #+ATTR_LaTeX: :width 10cm
rlm@516	538 [[./images/finger-1.png]]
rlm@516	539
rlm@516	540 ** Video game engines provide ready-made physics and shading
rlm@516	541
rlm@516	542 I did not need to write my own physics simulation code or shader to
rlm@516	543 build =CORTEX=. Doing so would lead to a system that is impossible
rlm@516	544 for anyone but myself to use anyway. Instead, I use a video game
rlm@516	545 engine as a base and modify it to accomodate the additional needs
rlm@516	546 of =CORTEX=. Video game engines are an ideal starting point to
rlm@516	547 build =CORTEX=, because they are not far from being creature
rlm@516	548 building systems themselves.
rlm@516	549
rlm@516	550 First off, general purpose video game engines come with a physics
rlm@516	551 engine and lighting / sound system. The physics system provides
rlm@516	552 tools that can be co-opted to serve as touch, proprioception, and
rlm@516	553 muscles. Since some games support split screen views, a good video
rlm@516	554 game engine will allow you to efficiently create multiple cameras
rlm@516	555 in the simulated world that can be used as eyes. Video game systems
rlm@516	556 offer integrated asset management for things like textures and
rlm@516	557 creatures models, providing an avenue for defining creatures. They
rlm@516	558 also understand UV-mapping, since this technique is used to apply a
rlm@516	559 texture to a model. Finally, because video game engines support a
rlm@516	560 large number of users, as long as =CORTEX= doesn't stray too far
rlm@516	561 from the base system, other researchers can turn to this community
rlm@516	562 for help when doing their research.
rlm@516	563
rlm@516	564 ** =CORTEX= is based on jMonkeyEngine3
rlm@516	565
rlm@516	566 While preparing to build =CORTEX= I studied several video game
rlm@516	567 engines to see which would best serve as a base. The top contenders
rlm@516	568 were:
rlm@516	569
rlm@516	570 - [[http://www.idsoftware.com][Quake II]]/[[http://www.bytonic.de/html/jake2.html][Jake2]] :: The Quake II engine was designed by ID
rlm@516	571 software in 1997. All the source code was released by ID
rlm@516	572 software into the Public Domain several years ago, and as a
rlm@516	573 result it has been ported to many different languages. This
rlm@516	574 engine was famous for its advanced use of realistic shading
rlm@516	575 and had decent and fast physics simulation. The main advantage
rlm@516	576 of the Quake II engine is its simplicity, but I ultimately
rlm@516	577 rejected it because the engine is too tied to the concept of a
rlm@516	578 first-person shooter game. One of the problems I had was that
rlm@516	579 there does not seem to be any easy way to attach multiple
rlm@516	580 cameras to a single character. There are also several physics
rlm@516	581 clipping issues that are corrected in a way that only applies
rlm@516	582 to the main character and do not apply to arbitrary objects.
rlm@516	583
rlm@516	584 - [[http://source.valvesoftware.com/][Source Engine]] :: The Source Engine evolved from the Quake II
rlm@516	585 and Quake I engines and is used by Valve in the Half-Life
rlm@516	586 series of games. The physics simulation in the Source Engine
rlm@516	587 is quite accurate and probably the best out of all the engines
rlm@516	588 I investigated. There is also an extensive community actively
rlm@516	589 working with the engine. However, applications that use the
rlm@516	590 Source Engine must be written in C++, the code is not open, it
rlm@516	591 only runs on Windows, and the tools that come with the SDK to
rlm@516	592 handle models and textures are complicated and awkward to use.
rlm@516	593
rlm@516	594 - [[http://jmonkeyengine.com/][jMonkeyEngine3]] :: jMonkeyEngine3 is a new library for creating
rlm@516	595 games in Java. It uses OpenGL to render to the screen and uses
rlm@516	596 screengraphs to avoid drawing things that do not appear on the
rlm@516	597 screen. It has an active community and several games in the
rlm@516	598 pipeline. The engine was not built to serve any particular
rlm@516	599 game but is instead meant to be used for any 3D game.
rlm@516	600
rlm@516	601 I chose jMonkeyEngine3 because it because it had the most features
rlm@516	602 out of all the free projects I looked at, and because I could then
rlm@516	603 write my code in clojure, an implementation of =LISP= that runs on
rlm@516	604 the JVM.
rlm@516	605
rlm@516	606 ** =CORTEX= uses Blender to create creature models
rlm@516	607
rlm@516	608 For the simple worm-like creatures I will use later on in this
rlm@516	609 thesis, I could define a simple API in =CORTEX= that would allow
rlm@516	610 one to create boxes, spheres, etc., and leave that API as the sole
rlm@516	611 way to create creatures. However, for =CORTEX= to truly be useful
rlm@516	612 for other projects, it needs a way to construct complicated
rlm@516	613 creatures. If possible, it would be nice to leverage work that has
rlm@516	614 already been done by the community of 3D modelers, or at least
rlm@516	615 enable people who are talented at moedling but not programming to
rlm@516	616 design =CORTEX= creatures.
rlm@516	617
rlm@516	618 Therefore, I use Blender, a free 3D modeling program, as the main
rlm@516	619 way to create creatures in =CORTEX=. However, the creatures modeled
rlm@516	620 in Blender must also be simple to simulate in jMonkeyEngine3's game
rlm@516	621 engine, and must also be easy to rig with =CORTEX='s senses. I
rlm@516	622 accomplish this with extensive use of Blender's ``empty nodes.''
rlm@516	623
rlm@516	624 Empty nodes have no mass, physical presence, or appearance, but
rlm@516	625 they can hold metadata and have names. I use a tree structure of
rlm@516	626 empty nodes to specify senses in the following manner:
rlm@516	627
rlm@516	628 - Create a single top-level empty node whose name is the name of
rlm@516	629 the sense.
rlm@516	630 - Add empty nodes which each contain meta-data relevant to the
rlm@516	631 sense, including a UV-map describing the number/distribution of
rlm@516	632 sensors if applicable.
rlm@516	633 - Make each empty-node the child of the top-level node.
rlm@516	634
rlm@516	635 #+caption: An example of annoting a creature model with empty
rlm@516	636 #+caption: nodes to describe the layout of senses. There are
rlm@516	637 #+caption: multiple empty nodes which each describe the position
rlm@516	638 #+caption: of muscles, ears, eyes, or joints.
rlm@516	639 #+name: sense-nodes
rlm@516	640 #+ATTR_LaTeX: :width 10cm
rlm@516	641 [[./images/empty-sense-nodes.png]]
rlm@516	642
rlm@516	643 ** Bodies are composed of segments connected by joints
rlm@516	644
rlm@516	645 Blender is a general purpose animation tool, which has been used in
rlm@516	646 the past to create high quality movies such as Sintel
rlm@516	647 \cite{blender}. Though Blender can model and render even complicated
rlm@516	648 things like water, it is crucual to keep models that are meant to
rlm@516	649 be simulated as creatures simple. =Bullet=, which =CORTEX= uses
rlm@516	650 though jMonkeyEngine3, is a rigid-body physics system. This offers
rlm@516	651 a compromise between the expressiveness of a game level and the
rlm@516	652 speed at which it can be simulated, and it means that creatures
rlm@516	653 should be naturally expressed as rigid components held together by
rlm@516	654 joint constraints.
rlm@516	655
rlm@516	656 But humans are more like a squishy bag with wrapped around some
rlm@516	657 hard bones which define the overall shape. When we move, our skin
rlm@516	658 bends and stretches to accomodate the new positions of our bones.
rlm@516	659
rlm@516	660 One way to make bodies composed of rigid pieces connected by joints
rlm@516	661 /seem/ more human-like is to use an /armature/, (or /rigging/)
rlm@516	662 system, which defines a overall ``body mesh'' and defines how the
rlm@516	663 mesh deforms as a function of the position of each ``bone'' which
rlm@516	664 is a standard rigid body. This technique is used extensively to
rlm@516	665 model humans and create realistic animations. It is not a good
rlm@516	666 technique for physical simulation, however because it creates a lie
rlm@516	667 -- the skin is not a physical part of the simulation and does not
rlm@516	668 interact with any objects in the world or itself. Objects will pass
rlm@516	669 right though the skin until they come in contact with the
rlm@516	670 underlying bone, which is a physical object. Whithout simulating
rlm@516	671 the skin, the sense of touch has little meaning, and the creature's
rlm@516	672 own vision will lie to it about the true extent of its body.
rlm@516	673 Simulating the skin as a physical object requires some way to
rlm@516	674 continuously update the physical model of the skin along with the
rlm@516	675 movement of the bones, which is unacceptably slow compared to rigid
rlm@516	676 body simulation.
rlm@516	677
rlm@516	678 Therefore, instead of using the human-like ``deformable bag of
rlm@516	679 bones'' approach, I decided to base my body plans on multiple solid
rlm@516	680 objects that are connected by joints, inspired by the robot =EVE=
rlm@516	681 from the movie WALL-E.
rlm@516	682
rlm@516	683 #+caption: =EVE= from the movie WALL-E. This body plan turns
rlm@516	684 #+caption: out to be much better suited to my purposes than a more
rlm@516	685 #+caption: human-like one.
rlm@516	686 #+ATTR_LaTeX: :width 10cm
rlm@516	687 [[./images/Eve.jpg]]
rlm@516	688
rlm@516	689 =EVE='s body is composed of several rigid components that are held
rlm@516	690 together by invisible joint constraints. This is what I mean by
rlm@516	691 ``eve-like''. The main reason that I use eve-style bodies is for
rlm@516	692 efficiency, and so that there will be correspondence between the
rlm@516	693 AI's semses and the physical presence of its body. Each individual
rlm@516	694 section is simulated by a separate rigid body that corresponds
rlm@516	695 exactly with its visual representation and does not change.
rlm@516	696 Sections are connected by invisible joints that are well supported
rlm@516	697 in jMonkeyEngine3. Bullet, the physics backend for jMonkeyEngine3,
rlm@516	698 can efficiently simulate hundreds of rigid bodies connected by
rlm@516	699 joints. Just because sections are rigid does not mean they have to
rlm@516	700 stay as one piece forever; they can be dynamically replaced with
rlm@516	701 multiple sections to simulate splitting in two. This could be used
rlm@516	702 to simulate retractable claws or =EVE='s hands, which are able to
rlm@516	703 coalesce into one object in the movie.
rlm@516	704
rlm@516	705 *** Solidifying/Connecting a body
rlm@516	706
rlm@516	707 =CORTEX= creates a creature in two steps: first, it traverses the
rlm@516	708 nodes in the blender file and creates physical representations for
rlm@516	709 any of them that have mass defined in their blender meta-data.
rlm@516	710
rlm@516	711 #+caption: Program for iterating through the nodes in a blender file
rlm@516	712 #+caption: and generating physical jMonkeyEngine3 objects with mass
rlm@516	713 #+caption: and a matching physics shape.
rlm@516	714 #+name: name
rlm@516	715 #+begin_listing clojure
rlm@516	716 #+begin_src clojure
rlm@516	717 (defn physical!
rlm@516	718 "Iterate through the nodes in creature and make them real physical
rlm@516	719 objects in the simulation."
rlm@516	720 [#^Node creature]
rlm@516	721 (dorun
rlm@516	722 (map
rlm@516	723 (fn [geom]
rlm@516	724 (let [physics-control
rlm@516	725 (RigidBodyControl.
rlm@516	726 (HullCollisionShape.
rlm@516	727 (.getMesh geom))
rlm@516	728 (if-let [mass (meta-data geom "mass")]
rlm@516	729 (float mass) (float 1)))]
rlm@516	730 (.addControl geom physics-control)))
rlm@516	731 (filter #(isa? (class %) Geometry )
rlm@516	732 (node-seq creature)))))
rlm@516	733 #+end_src
rlm@516	734 #+end_listing
rlm@516	735
rlm@516	736 The next step to making a proper body is to connect those pieces
rlm@516	737 together with joints. jMonkeyEngine has a large array of joints
rlm@516	738 available via =bullet=, such as Point2Point, Cone, Hinge, and a
rlm@516	739 generic Six Degree of Freedom joint, with or without spring
rlm@516	740 restitution.
rlm@516	741
rlm@516	742 Joints are treated a lot like proper senses, in that there is a
rlm@516	743 top-level empty node named ``joints'' whose children each
rlm@516	744 represent a joint.
rlm@516	745
rlm@516	746 #+caption: View of the hand model in Blender showing the main ``joints''
rlm@516	747 #+caption: node (highlighted in yellow) and its children which each
rlm@516	748 #+caption: represent a joint in the hand. Each joint node has metadata
rlm@516	749 #+caption: specifying what sort of joint it is.
rlm@516	750 #+name: blender-hand
rlm@516	751 #+ATTR_LaTeX: :width 10cm
rlm@516	752 [[./images/hand-screenshot1.png]]
rlm@516	753
rlm@516	754
rlm@516	755 =CORTEX='s procedure for binding the creature together with joints
rlm@516	756 is as follows:
rlm@516	757
rlm@516	758 - Find the children of the ``joints'' node.
rlm@516	759 - Determine the two spatials the joint is meant to connect.
rlm@516	760 - Create the joint based on the meta-data of the empty node.
rlm@516	761
rlm@516	762 The higher order function =sense-nodes= from =cortex.sense=
rlm@516	763 simplifies finding the joints based on their parent ``joints''
rlm@516	764 node.
rlm@516	765
rlm@516	766 #+caption: Retrieving the children empty nodes from a single
rlm@516	767 #+caption: named empty node is a common pattern in =CORTEX=
rlm@516	768 #+caption: further instances of this technique for the senses
rlm@516	769 #+caption: will be omitted
rlm@516	770 #+name: get-empty-nodes
rlm@516	771 #+begin_listing clojure
rlm@516	772 #+begin_src clojure
rlm@516	773 (defn sense-nodes
rlm@516	774 "For some senses there is a special empty blender node whose
rlm@516	775 children are considered markers for an instance of that sense. This
rlm@516	776 function generates functions to find those children, given the name
rlm@516	777 of the special parent node."
rlm@516	778 [parent-name]
rlm@516	779 (fn [#^Node creature]
rlm@516	780 (if-let [sense-node (.getChild creature parent-name)]
rlm@516	781 (seq (.getChildren sense-node)) [])))
rlm@516	782
rlm@516	783 (def
rlm@516	784 ^{:doc "Return the children of the creature's \"joints\" node."
rlm@516	785 :arglists '([creature])}
rlm@516	786 joints
rlm@516	787 (sense-nodes "joints"))
rlm@516	788 #+end_src
rlm@516	789 #+end_listing
rlm@516	790
rlm@516	791 To find a joint's targets, =CORTEX= creates a small cube, centered
rlm@516	792 around the empty-node, and grows the cube exponentially until it
rlm@516	793 intersects two physical objects. The objects are ordered according
rlm@516	794 to the joint's rotation, with the first one being the object that
rlm@516	795 has more negative coordinates in the joint's reference frame.
rlm@516	796 Since the objects must be physical, the empty-node itself escapes
rlm@516	797 detection. Because the objects must be physical, =joint-targets=
rlm@516	798 must be called /after/ =physical!= is called.
rlm@516	799
rlm@516	800 #+caption: Program to find the targets of a joint node by
rlm@516	801 #+caption: exponentiallly growth of a search cube.
rlm@516	802 #+name: joint-targets
rlm@516	803 #+begin_listing clojure
rlm@516	804 #+begin_src clojure
rlm@516	805 (defn joint-targets
rlm@516	806 "Return the two closest two objects to the joint object, ordered
rlm@516	807 from bottom to top according to the joint's rotation."
rlm@516	808 [#^Node parts #^Node joint]
rlm@516	809 (loop [radius (float 0.01)]
rlm@516	810 (let [results (CollisionResults.)]
rlm@516	811 (.collideWith
rlm@516	812 parts
rlm@516	813 (BoundingBox. (.getWorldTranslation joint)
rlm@516	814 radius radius radius) results)
rlm@516	815 (let [targets
rlm@516	816 (distinct
rlm@516	817 (map #(.getGeometry %) results))]
rlm@516	818 (if (>= (count targets) 2)
rlm@516	819 (sort-by
rlm@516	820 #(let [joint-ref-frame-position
rlm@516	821 (jme-to-blender
rlm@516	822 (.mult
rlm@516	823 (.inverse (.getWorldRotation joint))
rlm@516	824 (.subtract (.getWorldTranslation %)
rlm@516	825 (.getWorldTranslation joint))))]
rlm@516	826 (.dot (Vector3f. 1 1 1) joint-ref-frame-position))
rlm@516	827 (take 2 targets))
rlm@516	828 (recur (float (* radius 2))))))))
rlm@516	829 #+end_src
rlm@516	830 #+end_listing
rlm@516	831
rlm@516	832 Once =CORTEX= finds all joints and targets, it creates them using
rlm@516	833 a dispatch on the metadata of each joint node.
rlm@516	834
rlm@516	835 #+caption: Program to dispatch on blender metadata and create joints
rlm@516	836 #+caption: sutiable for physical simulation.
rlm@516	837 #+name: joint-dispatch
rlm@516	838 #+begin_listing clojure
rlm@516	839 #+begin_src clojure
rlm@516	840 (defmulti joint-dispatch
rlm@516	841 "Translate blender pseudo-joints into real JME joints."
rlm@516	842 (fn [constraints & _]
rlm@516	843 (:type constraints)))
rlm@516	844
rlm@516	845 (defmethod joint-dispatch :point
rlm@516	846 [constraints control-a control-b pivot-a pivot-b rotation]
rlm@516	847 (doto (SixDofJoint. control-a control-b pivot-a pivot-b false)
rlm@516	848 (.setLinearLowerLimit Vector3f/ZERO)
rlm@516	849 (.setLinearUpperLimit Vector3f/ZERO)))
rlm@516	850
rlm@516	851 (defmethod joint-dispatch :hinge
rlm@516	852 [constraints control-a control-b pivot-a pivot-b rotation]
rlm@516	853 (let [axis (if-let [axis (:axis constraints)] axis Vector3f/UNIT_X)
rlm@516	854 [limit-1 limit-2] (:limit constraints)
rlm@516	855 hinge-axis (.mult rotation (blender-to-jme axis))]
rlm@516	856 (doto (HingeJoint. control-a control-b pivot-a pivot-b
rlm@516	857 hinge-axis hinge-axis)
rlm@516	858 (.setLimit limit-1 limit-2))))
rlm@516	859
rlm@516	860 (defmethod joint-dispatch :cone
rlm@516	861 [constraints control-a control-b pivot-a pivot-b rotation]
rlm@516	862 (let [limit-xz (:limit-xz constraints)
rlm@516	863 limit-xy (:limit-xy constraints)
rlm@516	864 twist (:twist constraints)]
rlm@516	865 (doto (ConeJoint. control-a control-b pivot-a pivot-b
rlm@516	866 rotation rotation)
rlm@516	867 (.setLimit (float limit-xz) (float limit-xy)
rlm@516	868 (float twist)))))
rlm@516	869 #+end_src
rlm@516	870 #+end_listing
rlm@516	871
rlm@516	872 All that is left for joints it to combine the above pieces into a
rlm@516	873 something that can operate on the collection of nodes that a
rlm@516	874 blender file represents.
rlm@516	875
rlm@516	876 #+caption: Program to completely create a joint given information
rlm@516	877 #+caption: from a blender file.
rlm@516	878 #+name: connect
rlm@516	879 #+begin_listing clojure
rlm@516	880 #+begin_src clojure
rlm@516	881 (defn connect
rlm@516	882 "Create a joint between 'obj-a and 'obj-b at the location of
rlm@516	883 'joint. The type of joint is determined by the metadata on 'joint.
rlm@516	884
rlm@516	885 Here are some examples:
rlm@516	886 {:type :point}
rlm@516	887 {:type :hinge :limit [0 (/ Math/PI 2)] :axis (Vector3f. 0 1 0)}
rlm@516	888 (:axis defaults to (Vector3f. 1 0 0) if not provided for hinge joints)
rlm@516	889
rlm@516	890 {:type :cone :limit-xz 0]
rlm@516	891 :limit-xy 0]
rlm@516	892 :twist 0]} (use XZY rotation mode in blender!)"
rlm@516	893 [#^Node obj-a #^Node obj-b #^Node joint]
rlm@516	894 (let [control-a (.getControl obj-a RigidBodyControl)
rlm@516	895 control-b (.getControl obj-b RigidBodyControl)
rlm@516	896 joint-center (.getWorldTranslation joint)
rlm@516	897 joint-rotation (.toRotationMatrix (.getWorldRotation joint))
rlm@516	898 pivot-a (world-to-local obj-a joint-center)
rlm@516	899 pivot-b (world-to-local obj-b joint-center)]
rlm@516	900 (if-let
rlm@516	901 [constraints (map-vals eval (read-string (meta-data joint "joint")))]
rlm@516	902 ;; A side-effect of creating a joint registers
rlm@516	903 ;; it with both physics objects which in turn
rlm@516	904 ;; will register the joint with the physics system
rlm@516	905 ;; when the simulation is started.
rlm@516	906 (joint-dispatch constraints
rlm@516	907 control-a control-b
rlm@516	908 pivot-a pivot-b
rlm@516	909 joint-rotation))))
rlm@516	910 #+end_src
rlm@516	911 #+end_listing
rlm@516	912
rlm@516	913 In general, whenever =CORTEX= exposes a sense (or in this case
rlm@516	914 physicality), it provides a function of the type =sense!=, which
rlm@516	915 takes in a collection of nodes and augments it to support that
rlm@516	916 sense. The function returns any controlls necessary to use that
rlm@516	917 sense. In this case =body!= cerates a physical body and returns no
rlm@516	918 control functions.
rlm@516	919
rlm@516	920 #+caption: Program to give joints to a creature.
rlm@516	921 #+name: name
rlm@516	922 #+begin_listing clojure
rlm@516	923 #+begin_src clojure
rlm@516	924 (defn joints!
rlm@516	925 "Connect the solid parts of the creature with physical joints. The
rlm@516	926 joints are taken from the \"joints\" node in the creature."
rlm@516	927 [#^Node creature]
rlm@516	928 (dorun
rlm@516	929 (map
rlm@516	930 (fn [joint]
rlm@516	931 (let [[obj-a obj-b] (joint-targets creature joint)]
rlm@516	932 (connect obj-a obj-b joint)))
rlm@516	933 (joints creature))))
rlm@516	934 (defn body!
rlm@516	935 "Endow the creature with a physical body connected with joints. The
rlm@516	936 particulars of the joints and the masses of each body part are
rlm@516	937 determined in blender."
rlm@516	938 [#^Node creature]
rlm@516	939 (physical! creature)
rlm@516	940 (joints! creature))
rlm@516	941 #+end_src
rlm@516	942 #+end_listing
rlm@516	943
rlm@516	944 All of the code you have just seen amounts to only 130 lines, yet
rlm@516	945 because it builds on top of Blender and jMonkeyEngine3, those few
rlm@516	946 lines pack quite a punch!
rlm@516	947
rlm@516	948 The hand from figure \ref{blender-hand}, which was modeled after
rlm@516	949 my own right hand, can now be given joints and simulated as a
rlm@516	950 creature.
rlm@516	951
rlm@516	952 #+caption: With the ability to create physical creatures from blender,
rlm@516	953 #+caption: =CORTEX= gets one step closer to becomming a full creature
rlm@516	954 #+caption: simulation environment.
rlm@516	955 #+name: name
rlm@516	956 #+ATTR_LaTeX: :width 15cm
rlm@516	957 [[./images/physical-hand.png]]
rlm@516	958
rlm@516	959 ** Eyes reuse standard video game components
rlm@516	960
rlm@516	961 Vision is one of the most important senses for humans, so I need to
rlm@516	962 build a simulated sense of vision for my AI. I will do this with
rlm@516	963 simulated eyes. Each eye can be independently moved and should see
rlm@516	964 its own version of the world depending on where it is.
rlm@516	965
rlm@516	966 Making these simulated eyes a reality is simple because
rlm@516	967 jMonkeyEngine already contains extensive support for multiple views
rlm@516	968 of the same 3D simulated world. The reason jMonkeyEngine has this
rlm@516	969 support is because the support is necessary to create games with
rlm@516	970 split-screen views. Multiple views are also used to create
rlm@516	971 efficient pseudo-reflections by rendering the scene from a certain
rlm@516	972 perspective and then projecting it back onto a surface in the 3D
rlm@516	973 world.
rlm@516	974
rlm@516	975 #+caption: jMonkeyEngine supports multiple views to enable
rlm@516	976 #+caption: split-screen games, like GoldenEye, which was one of
rlm@516	977 #+caption: the first games to use split-screen views.
rlm@516	978 #+name: name
rlm@516	979 #+ATTR_LaTeX: :width 10cm
rlm@516	980 [[./images/goldeneye-4-player.png]]
rlm@516	981
rlm@516	982 *** A Brief Description of jMonkeyEngine's Rendering Pipeline
rlm@516	983
rlm@516	984 jMonkeyEngine allows you to create a =ViewPort=, which represents a
rlm@516	985 view of the simulated world. You can create as many of these as you
rlm@516	986 want. Every frame, the =RenderManager= iterates through each
rlm@516	987 =ViewPort=, rendering the scene in the GPU. For each =ViewPort= there
rlm@516	988 is a =FrameBuffer= which represents the rendered image in the GPU.
rlm@516	989
rlm@516	990 #+caption: =ViewPorts= are cameras in the world. During each frame,
rlm@516	991 #+caption: the =RenderManager= records a snapshot of what each view
rlm@516	992 #+caption: is currently seeing; these snapshots are =FrameBuffer= objects.
rlm@516	993 #+name: rendermanagers
rlm@516	994 #+ATTR_LaTeX: :width 10cm
rlm@516	995 [[./images/diagram_rendermanager2.png]]
rlm@516	996
rlm@516	997 Each =ViewPort= can have any number of attached =SceneProcessor=
rlm@516	998 objects, which are called every time a new frame is rendered. A
rlm@516	999 =SceneProcessor= receives its =ViewPort's= =FrameBuffer= and can do
rlm@516	1000 whatever it wants to the data. Often this consists of invoking GPU
rlm@516	1001 specific operations on the rendered image. The =SceneProcessor= can
rlm@516	1002 also copy the GPU image data to RAM and process it with the CPU.
rlm@516	1003
rlm@516	1004 *** Appropriating Views for Vision
rlm@516	1005
rlm@516	1006 Each eye in the simulated creature needs its own =ViewPort= so
rlm@516	1007 that it can see the world from its own perspective. To this
rlm@516	1008 =ViewPort=, I add a =SceneProcessor= that feeds the visual data to
rlm@516	1009 any arbitrary continuation function for further processing. That
rlm@516	1010 continuation function may perform both CPU and GPU operations on
rlm@516	1011 the data. To make this easy for the continuation function, the
rlm@516	1012 =SceneProcessor= maintains appropriately sized buffers in RAM to
rlm@516	1013 hold the data. It does not do any copying from the GPU to the CPU
rlm@516	1014 itself because it is a slow operation.
rlm@516	1015
rlm@516	1016 #+caption: Function to make the rendered secne in jMonkeyEngine
rlm@516	1017 #+caption: available for further processing.
rlm@516	1018 #+name: pipeline-1
rlm@516	1019 #+begin_listing clojure
rlm@516	1020 #+begin_src clojure
rlm@516	1021 (defn vision-pipeline
rlm@516	1022 "Create a SceneProcessor object which wraps a vision processing
rlm@516	1023 continuation function. The continuation is a function that takes
rlm@516	1024 [#^Renderer r #^FrameBuffer fb #^ByteBuffer b #^BufferedImage bi],
rlm@516	1025 each of which has already been appropriately sized."
rlm@516	1026 [continuation]
rlm@516	1027 (let [byte-buffer (atom nil)
rlm@516	1028 renderer (atom nil)
rlm@516	1029 image (atom nil)]
rlm@516	1030 (proxy [SceneProcessor] []
rlm@516	1031 (initialize
rlm@516	1032 [renderManager viewPort]
rlm@516	1033 (let [cam (.getCamera viewPort)
rlm@516	1034 width (.getWidth cam)
rlm@516	1035 height (.getHeight cam)]
rlm@516	1036 (reset! renderer (.getRenderer renderManager))
rlm@516	1037 (reset! byte-buffer
rlm@516	1038 (BufferUtils/createByteBuffer
rlm@516	1039 (* width height 4)))
rlm@516	1040 (reset! image (BufferedImage.
rlm@516	1041 width height
rlm@516	1042 BufferedImage/TYPE_4BYTE_ABGR))))
rlm@516	1043 (isInitialized [] (not (nil? @byte-buffer)))
rlm@516	1044 (reshape [_ _ _])
rlm@516	1045 (preFrame [_])
rlm@516	1046 (postQueue [_])
rlm@516	1047 (postFrame
rlm@516	1048 [#^FrameBuffer fb]
rlm@516	1049 (.clear @byte-buffer)
rlm@516	1050 (continuation @renderer fb @byte-buffer @image))
rlm@516	1051 (cleanup []))))
rlm@516	1052 #+end_src
rlm@516	1053 #+end_listing
rlm@516	1054
rlm@516	1055 The continuation function given to =vision-pipeline= above will be
rlm@516	1056 given a =Renderer= and three containers for image data. The
rlm@516	1057 =FrameBuffer= references the GPU image data, but the pixel data
rlm@516	1058 can not be used directly on the CPU. The =ByteBuffer= and
rlm@516	1059 =BufferedImage= are initially "empty" but are sized to hold the
rlm@516	1060 data in the =FrameBuffer=. I call transferring the GPU image data
rlm@516	1061 to the CPU structures "mixing" the image data.
rlm@516	1062
rlm@516	1063 *** Optical sensor arrays are described with images and referenced with metadata
rlm@516	1064
rlm@516	1065 The vision pipeline described above handles the flow of rendered
rlm@516	1066 images. Now, =CORTEX= needs simulated eyes to serve as the source
rlm@516	1067 of these images.
rlm@516	1068
rlm@516	1069 An eye is described in blender in the same way as a joint. They
rlm@516	1070 are zero dimensional empty objects with no geometry whose local
rlm@516	1071 coordinate system determines the orientation of the resulting eye.
rlm@516	1072 All eyes are children of a parent node named "eyes" just as all
rlm@516	1073 joints have a parent named "joints". An eye binds to the nearest
rlm@516	1074 physical object with =bind-sense=.
rlm@516	1075
rlm@516	1076 #+caption: Here, the camera is created based on metadata on the
rlm@516	1077 #+caption: eye-node and attached to the nearest physical object
rlm@516	1078 #+caption: with =bind-sense=
rlm@516	1079 #+name: add-eye
rlm@516	1080 #+begin_listing clojure
rlm@516	1081 (defn add-eye!
rlm@516	1082 "Create a Camera centered on the current position of 'eye which
rlm@516	1083 follows the closest physical node in 'creature. The camera will
rlm@516	1084 point in the X direction and use the Z vector as up as determined
rlm@516	1085 by the rotation of these vectors in blender coordinate space. Use
rlm@516	1086 XZY rotation for the node in blender."
rlm@516	1087 [#^Node creature #^Spatial eye]
rlm@516	1088 (let [target (closest-node creature eye)
rlm@516	1089 [cam-width cam-height]
rlm@516	1090 ;;[640 480] ;; graphics card on laptop doesn't support
rlm@516	1091 ;; arbitray dimensions.
rlm@516	1092 (eye-dimensions eye)
rlm@516	1093 cam (Camera. cam-width cam-height)
rlm@516	1094 rot (.getWorldRotation eye)]
rlm@516	1095 (.setLocation cam (.getWorldTranslation eye))
rlm@516	1096 (.lookAtDirection
rlm@516	1097 cam ; this part is not a mistake and
rlm@516	1098 (.mult rot Vector3f/UNIT_X) ; is consistent with using Z in
rlm@516	1099 (.mult rot Vector3f/UNIT_Y)) ; blender as the UP vector.
rlm@516	1100 (.setFrustumPerspective
rlm@516	1101 cam (float 45)
rlm@516	1102 (float (/ (.getWidth cam) (.getHeight cam)))
rlm@516	1103 (float 1)
rlm@516	1104 (float 1000))
rlm@516	1105 (bind-sense target cam) cam))
rlm@516	1106 #+end_listing
rlm@516	1107
rlm@516	1108 *** Simulated Retina
rlm@516	1109
rlm@516	1110 An eye is a surface (the retina) which contains many discrete
rlm@516	1111 sensors to detect light. These sensors can have different
rlm@516	1112 light-sensing properties. In humans, each discrete sensor is
rlm@516	1113 sensitive to red, blue, green, or gray. These different types of
rlm@516	1114 sensors can have different spatial distributions along the retina.
rlm@516	1115 In humans, there is a fovea in the center of the retina which has
rlm@516	1116 a very high density of color sensors, and a blind spot which has
rlm@516	1117 no sensors at all. Sensor density decreases in proportion to
rlm@516	1118 distance from the fovea.
rlm@516	1119
rlm@516	1120 I want to be able to model any retinal configuration, so my
rlm@516	1121 eye-nodes in blender contain metadata pointing to images that
rlm@516	1122 describe the precise position of the individual sensors using
rlm@516	1123 white pixels. The meta-data also describes the precise sensitivity
rlm@516	1124 to light that the sensors described in the image have. An eye can
rlm@516	1125 contain any number of these images. For example, the metadata for
rlm@516	1126 an eye might look like this:
rlm@516	1127
rlm@516	1128 #+begin_src clojure
rlm@516	1129 {0xFF0000 "Models/test-creature/retina-small.png"}
rlm@516	1130 #+end_src
rlm@516	1131
rlm@516	1132 #+caption: An example retinal profile image. White pixels are
rlm@516	1133 #+caption: photo-sensitive elements. The distribution of white
rlm@516	1134 #+caption: pixels is denser in the middle and falls off at the
rlm@516	1135 #+caption: edges and is inspired by the human retina.
rlm@516	1136 #+name: retina
rlm@516	1137 #+ATTR_LaTeX: :width 7cm
rlm@516	1138 [[./images/retina-small.png]]
rlm@516	1139
rlm@516	1140 Together, the number 0xFF0000 and the image image above describe
rlm@516	1141 the placement of red-sensitive sensory elements.
rlm@516	1142
rlm@516	1143 Meta-data to very crudely approximate a human eye might be
rlm@516	1144 something like this:
rlm@516	1145
rlm@516	1146 #+begin_src clojure
rlm@516	1147 (let [retinal-profile "Models/test-creature/retina-small.png"]
rlm@516	1148 {0xFF0000 retinal-profile
rlm@516	1149 0x00FF00 retinal-profile
rlm@516	1150 0x0000FF retinal-profile
rlm@516	1151 0xFFFFFF retinal-profile})
rlm@516	1152 #+end_src
rlm@516	1153
rlm@516	1154 The numbers that serve as keys in the map determine a sensor's
rlm@516	1155 relative sensitivity to the channels red, green, and blue. These
rlm@516	1156 sensitivity values are packed into an integer in the order
rlm@516	1157 =\|_\|R\|G\|B\|= in 8-bit fields. The RGB values of a pixel in the
rlm@516	1158 image are added together with these sensitivities as linear
rlm@516	1159 weights. Therefore, 0xFF0000 means sensitive to red only while
rlm@516	1160 0xFFFFFF means sensitive to all colors equally (gray).
rlm@516	1161
rlm@516	1162 #+caption: This is the core of vision in =CORTEX=. A given eye node
rlm@516	1163 #+caption: is converted into a function that returns visual
rlm@516	1164 #+caption: information from the simulation.
rlm@516	1165 #+name: vision-kernel
rlm@516	1166 #+begin_listing clojure
rlm@516	1167 #+BEGIN_SRC clojure
rlm@516	1168 (defn vision-kernel
rlm@516	1169 "Returns a list of functions, each of which will return a color
rlm@516	1170 channel's worth of visual information when called inside a running
rlm@516	1171 simulation."
rlm@516	1172 [#^Node creature #^Spatial eye & {skip :skip :or {skip 0}}]
rlm@516	1173 (let [retinal-map (retina-sensor-profile eye)
rlm@516	1174 camera (add-eye! creature eye)
rlm@516	1175 vision-image
rlm@516	1176 (atom
rlm@516	1177 (BufferedImage. (.getWidth camera)
rlm@516	1178 (.getHeight camera)
rlm@516	1179 BufferedImage/TYPE_BYTE_BINARY))
rlm@516	1180 register-eye!
rlm@516	1181 (runonce
rlm@516	1182 (fn [world]
rlm@516	1183 (add-camera!
rlm@516	1184 world camera
rlm@516	1185 (let [counter (atom 0)]
rlm@516	1186 (fn [r fb bb bi]
rlm@516	1187 (if (zero? (rem (swap! counter inc) (inc skip)))
rlm@516	1188 (reset! vision-image
rlm@516	1189 (BufferedImage! r fb bb bi))))))))]
rlm@516	1190 (vec
rlm@516	1191 (map
rlm@516	1192 (fn [[key image]]
rlm@516	1193 (let [whites (white-coordinates image)
rlm@516	1194 topology (vec (collapse whites))
rlm@516	1195 sensitivity (sensitivity-presets key key)]
rlm@516	1196 (attached-viewport.
rlm@516	1197 (fn [world]
rlm@516	1198 (register-eye! world)
rlm@516	1199 (vector
rlm@516	1200 topology
rlm@516	1201 (vec
rlm@516	1202 (for [[x y] whites]
rlm@516	1203 (pixel-sense
rlm@516	1204 sensitivity
rlm@516	1205 (.getRGB @vision-image x y))))))
rlm@516	1206 register-eye!)))
rlm@516	1207 retinal-map))))
rlm@516	1208 #+END_SRC
rlm@516	1209 #+end_listing
rlm@516	1210
rlm@516	1211 Note that since each of the functions generated by =vision-kernel=
rlm@516	1212 shares the same =register-eye!= function, the eye will be
rlm@516	1213 registered only once the first time any of the functions from the
rlm@516	1214 list returned by =vision-kernel= is called. Each of the functions
rlm@516	1215 returned by =vision-kernel= also allows access to the =Viewport=
rlm@516	1216 through which it receives images.
rlm@516	1217
rlm@516	1218 All the hard work has been done; all that remains is to apply
rlm@516	1219 =vision-kernel= to each eye in the creature and gather the results
rlm@516	1220 into one list of functions.
rlm@516	1221
rlm@516	1222
rlm@516	1223 #+caption: With =vision!=, =CORTEX= is already a fine simulation
rlm@516	1224 #+caption: environment for experimenting with different types of
rlm@516	1225 #+caption: eyes.
rlm@516	1226 #+name: vision!
rlm@516	1227 #+begin_listing clojure
rlm@516	1228 #+BEGIN_SRC clojure
rlm@516	1229 (defn vision!
rlm@516	1230 "Returns a list of functions, each of which returns visual sensory
rlm@516	1231 data when called inside a running simulation."
rlm@516	1232 [#^Node creature & {skip :skip :or {skip 0}}]
rlm@516	1233 (reduce
rlm@516	1234 concat
rlm@516	1235 (for [eye (eyes creature)]
rlm@516	1236 (vision-kernel creature eye))))
rlm@516	1237 #+END_SRC
rlm@516	1238 #+end_listing
rlm@516	1239
rlm@516	1240 #+caption: Simulated vision with a test creature and the
rlm@516	1241 #+caption: human-like eye approximation. Notice how each channel
rlm@516	1242 #+caption: of the eye responds differently to the differently
rlm@516	1243 #+caption: colored balls.
rlm@516	1244 #+name: worm-vision-test.
rlm@516	1245 #+ATTR_LaTeX: :width 13cm
rlm@516	1246 [[./images/worm-vision.png]]
rlm@516	1247
rlm@516	1248 The vision code is not much more complicated than the body code,
rlm@516	1249 and enables multiple further paths for simulated vision. For
rlm@516	1250 example, it is quite easy to create bifocal vision -- you just
rlm@516	1251 make two eyes next to each other in blender! It is also possible
rlm@516	1252 to encode vision transforms in the retinal files. For example, the
rlm@516	1253 human like retina file in figure \ref{retina} approximates a
rlm@516	1254 log-polar transform.
rlm@516	1255
rlm@516	1256 This vision code has already been absorbed by the jMonkeyEngine
rlm@516	1257 community and is now (in modified form) part of a system for
rlm@516	1258 capturing in-game video to a file.
rlm@516	1259
rlm@516	1260 ** Hearing is hard; =CORTEX= does it right
rlm@516	1261
rlm@516	1262 At the end of this section I will have simulated ears that work the
rlm@516	1263 same way as the simulated eyes in the last section. I will be able to
rlm@516	1264 place any number of ear-nodes in a blender file, and they will bind to
rlm@516	1265 the closest physical object and follow it as it moves around. Each ear
rlm@516	1266 will provide access to the sound data it picks up between every frame.
rlm@516	1267
rlm@516	1268 Hearing is one of the more difficult senses to simulate, because there
rlm@516	1269 is less support for obtaining the actual sound data that is processed
rlm@516	1270 by jMonkeyEngine3. There is no "split-screen" support for rendering
rlm@516	1271 sound from different points of view, and there is no way to directly
rlm@516	1272 access the rendered sound data.
rlm@516	1273
rlm@516	1274 =CORTEX='s hearing is unique because it does not have any
rlm@516	1275 limitations compared to other simulation environments. As far as I
rlm@516	1276 know, there is no other system that supports multiple listerers,
rlm@516	1277 and the sound demo at the end of this section is the first time
rlm@516	1278 it's been done in a video game environment.
rlm@516	1279
rlm@516	1280 *** Brief Description of jMonkeyEngine's Sound System
rlm@516	1281
rlm@516	1282 jMonkeyEngine's sound system works as follows:
rlm@516	1283
rlm@516	1284 - jMonkeyEngine uses the =AppSettings= for the particular
rlm@516	1285 application to determine what sort of =AudioRenderer= should be
rlm@516	1286 used.
rlm@516	1287 - Although some support is provided for multiple AudioRendering
rlm@516	1288 backends, jMonkeyEngine at the time of this writing will either
rlm@516	1289 pick no =AudioRenderer= at all, or the =LwjglAudioRenderer=.
rlm@516	1290 - jMonkeyEngine tries to figure out what sort of system you're
rlm@516	1291 running and extracts the appropriate native libraries.
rlm@516	1292 - The =LwjglAudioRenderer= uses the [[http://lwjgl.org/][=LWJGL=]] (LightWeight Java Game
rlm@516	1293 Library) bindings to interface with a C library called [[http://kcat.strangesoft.net/openal.html][=OpenAL=]]
rlm@516	1294 - =OpenAL= renders the 3D sound and feeds the rendered sound
rlm@516	1295 directly to any of various sound output devices with which it
rlm@516	1296 knows how to communicate.
rlm@516	1297
rlm@516	1298 A consequence of this is that there's no way to access the actual
rlm@516	1299 sound data produced by =OpenAL=. Even worse, =OpenAL= only supports
rlm@516	1300 one /listener/ (it renders sound data from only one perspective),
rlm@516	1301 which normally isn't a problem for games, but becomes a problem
rlm@516	1302 when trying to make multiple AI creatures that can each hear the
rlm@516	1303 world from a different perspective.
rlm@516	1304
rlm@516	1305 To make many AI creatures in jMonkeyEngine that can each hear the
rlm@516	1306 world from their own perspective, or to make a single creature with
rlm@516	1307 many ears, it is necessary to go all the way back to =OpenAL= and
rlm@516	1308 implement support for simulated hearing there.
rlm@516	1309
rlm@516	1310 *** Extending =OpenAl=
rlm@516	1311
rlm@516	1312 Extending =OpenAL= to support multiple listeners requires 500
rlm@516	1313 lines of =C= code and is too hairy to mention here. Instead, I
rlm@516	1314 will show a small amount of extension code and go over the high
rlm@516	1315 level stragety. Full source is of course available with the
rlm@516	1316 =CORTEX= distribution if you're interested.
rlm@516	1317
rlm@516	1318 =OpenAL= goes to great lengths to support many different systems,
rlm@516	1319 all with different sound capabilities and interfaces. It
rlm@516	1320 accomplishes this difficult task by providing code for many
rlm@516	1321 different sound backends in pseudo-objects called /Devices/.
rlm@516	1322 There's a device for the Linux Open Sound System and the Advanced
rlm@516	1323 Linux Sound Architecture, there's one for Direct Sound on Windows,
rlm@516	1324 and there's even one for Solaris. =OpenAL= solves the problem of
rlm@516	1325 platform independence by providing all these Devices.
rlm@516	1326
rlm@516	1327 Wrapper libraries such as LWJGL are free to examine the system on
rlm@516	1328 which they are running and then select an appropriate device for
rlm@516	1329 that system.
rlm@516	1330
rlm@516	1331 There are also a few "special" devices that don't interface with
rlm@516	1332 any particular system. These include the Null Device, which
rlm@516	1333 doesn't do anything, and the Wave Device, which writes whatever
rlm@516	1334 sound it receives to a file, if everything has been set up
rlm@516	1335 correctly when configuring =OpenAL=.
rlm@516	1336
rlm@516	1337 Actual mixing (doppler shift and distance.environment-based
rlm@516	1338 attenuation) of the sound data happens in the Devices, and they
rlm@516	1339 are the only point in the sound rendering process where this data
rlm@516	1340 is available.
rlm@516	1341
rlm@516	1342 Therefore, in order to support multiple listeners, and get the
rlm@516	1343 sound data in a form that the AIs can use, it is necessary to
rlm@516	1344 create a new Device which supports this feature.
rlm@516	1345
rlm@516	1346 Adding a device to OpenAL is rather tricky -- there are five
rlm@516	1347 separate files in the =OpenAL= source tree that must be modified
rlm@516	1348 to do so. I named my device the "Multiple Audio Send" Device, or
rlm@516	1349 =Send= Device for short, since it sends audio data back to the
rlm@516	1350 calling application like an Aux-Send cable on a mixing board.
rlm@516	1351
rlm@516	1352 The main idea behind the Send device is to take advantage of the
rlm@516	1353 fact that LWJGL only manages one /context/ when using OpenAL. A
rlm@516	1354 /context/ is like a container that holds samples and keeps track
rlm@516	1355 of where the listener is. In order to support multiple listeners,
rlm@516	1356 the Send device identifies the LWJGL context as the master
rlm@516	1357 context, and creates any number of slave contexts to represent
rlm@516	1358 additional listeners. Every time the device renders sound, it
rlm@516	1359 synchronizes every source from the master LWJGL context to the
rlm@516	1360 slave contexts. Then, it renders each context separately, using a
rlm@516	1361 different listener for each one. The rendered sound is made
rlm@516	1362 available via JNI to jMonkeyEngine.
rlm@516	1363
rlm@516	1364 Switching between contexts is not the normal operation of a
rlm@516	1365 Device, and one of the problems with doing so is that a Device
rlm@516	1366 normally keeps around a few pieces of state such as the
rlm@516	1367 =ClickRemoval= array above which will become corrupted if the
rlm@516	1368 contexts are not rendered in parallel. The solution is to create a
rlm@516	1369 copy of this normally global device state for each context, and
rlm@516	1370 copy it back and forth into and out of the actual device state
rlm@516	1371 whenever a context is rendered.
rlm@516	1372
rlm@516	1373 The core of the =Send= device is the =syncSources= function, which
rlm@516	1374 does the job of copying all relevant data from one context to
rlm@516	1375 another.
rlm@516	1376
rlm@516	1377 #+caption: Program for extending =OpenAL= to support multiple
rlm@516	1378 #+caption: listeners via context copying/switching.
rlm@516	1379 #+name: sync-openal-sources
rlm@516	1380 #+begin_listing c
rlm@516	1381 #+BEGIN_SRC c
rlm@516	1382 void syncSources(ALsource masterSource, ALsource slaveSource,
rlm@516	1383 ALCcontext masterCtx, ALCcontext slaveCtx){
rlm@516	1384 ALuint master = masterSource->source;
rlm@516	1385 ALuint slave = slaveSource->source;
rlm@516	1386 ALCcontext *current = alcGetCurrentContext();
rlm@516	1387
rlm@516	1388 syncSourcef(master,slave,masterCtx,slaveCtx,AL_PITCH);
rlm@516	1389 syncSourcef(master,slave,masterCtx,slaveCtx,AL_GAIN);
rlm@516	1390 syncSourcef(master,slave,masterCtx,slaveCtx,AL_MAX_DISTANCE);
rlm@516	1391 syncSourcef(master,slave,masterCtx,slaveCtx,AL_ROLLOFF_FACTOR);
rlm@516	1392 syncSourcef(master,slave,masterCtx,slaveCtx,AL_REFERENCE_DISTANCE);
rlm@516	1393 syncSourcef(master,slave,masterCtx,slaveCtx,AL_MIN_GAIN);
rlm@516	1394 syncSourcef(master,slave,masterCtx,slaveCtx,AL_MAX_GAIN);
rlm@516	1395 syncSourcef(master,slave,masterCtx,slaveCtx,AL_CONE_OUTER_GAIN);
rlm@516	1396 syncSourcef(master,slave,masterCtx,slaveCtx,AL_CONE_INNER_ANGLE);
rlm@516	1397 syncSourcef(master,slave,masterCtx,slaveCtx,AL_CONE_OUTER_ANGLE);
rlm@516	1398 syncSourcef(master,slave,masterCtx,slaveCtx,AL_SEC_OFFSET);
rlm@516	1399 syncSourcef(master,slave,masterCtx,slaveCtx,AL_SAMPLE_OFFSET);
rlm@516	1400 syncSourcef(master,slave,masterCtx,slaveCtx,AL_BYTE_OFFSET);
rlm@516	1401
rlm@516	1402 syncSource3f(master,slave,masterCtx,slaveCtx,AL_POSITION);
rlm@516	1403 syncSource3f(master,slave,masterCtx,slaveCtx,AL_VELOCITY);
rlm@516	1404 syncSource3f(master,slave,masterCtx,slaveCtx,AL_DIRECTION);
rlm@516	1405
rlm@516	1406 syncSourcei(master,slave,masterCtx,slaveCtx,AL_SOURCE_RELATIVE);
rlm@516	1407 syncSourcei(master,slave,masterCtx,slaveCtx,AL_LOOPING);
rlm@516	1408
rlm@516	1409 alcMakeContextCurrent(masterCtx);
rlm@516	1410 ALint source_type;
rlm@516	1411 alGetSourcei(master, AL_SOURCE_TYPE, &source_type);
rlm@516	1412
rlm@516	1413 // Only static sources are currently synchronized!
rlm@516	1414 if (AL_STATIC == source_type){
rlm@516	1415 ALint master_buffer;
rlm@516	1416 ALint slave_buffer;
rlm@516	1417 alGetSourcei(master, AL_BUFFER, &master_buffer);
rlm@516	1418 alcMakeContextCurrent(slaveCtx);
rlm@516	1419 alGetSourcei(slave, AL_BUFFER, &slave_buffer);
rlm@516	1420 if (master_buffer != slave_buffer){
rlm@516	1421 alSourcei(slave, AL_BUFFER, master_buffer);
rlm@516	1422 }
rlm@516	1423 }
rlm@516	1424
rlm@516	1425 // Synchronize the state of the two sources.
rlm@516	1426 alcMakeContextCurrent(masterCtx);
rlm@516	1427 ALint masterState;
rlm@516	1428 ALint slaveState;
rlm@516	1429
rlm@516	1430 alGetSourcei(master, AL_SOURCE_STATE, &masterState);
rlm@516	1431 alcMakeContextCurrent(slaveCtx);
rlm@516	1432 alGetSourcei(slave, AL_SOURCE_STATE, &slaveState);
rlm@516	1433
rlm@516	1434 if (masterState != slaveState){
rlm@516	1435 switch (masterState){
rlm@516	1436 case AL_INITIAL : alSourceRewind(slave); break;
rlm@516	1437 case AL_PLAYING : alSourcePlay(slave); break;
rlm@516	1438 case AL_PAUSED : alSourcePause(slave); break;
rlm@516	1439 case AL_STOPPED : alSourceStop(slave); break;
rlm@516	1440 }
rlm@516	1441 }
rlm@516	1442 // Restore whatever context was previously active.
rlm@516	1443 alcMakeContextCurrent(current);
rlm@516	1444 }
rlm@516	1445 #+END_SRC
rlm@516	1446 #+end_listing
rlm@516	1447
rlm@516	1448 With this special context-switching device, and some ugly JNI
rlm@516	1449 bindings that are not worth mentioning, =CORTEX= gains the ability
rlm@516	1450 to access multiple sound streams from =OpenAL=.
rlm@516	1451
rlm@516	1452 #+caption: Program to create an ear from a blender empty node. The ear
rlm@516	1453 #+caption: follows around the nearest physical object and passes
rlm@516	1454 #+caption: all sensory data to a continuation function.
rlm@516	1455 #+name: add-ear
rlm@516	1456 #+begin_listing clojure
rlm@516	1457 #+BEGIN_SRC clojure
rlm@516	1458 (defn add-ear!
rlm@516	1459 "Create a Listener centered on the current position of 'ear
rlm@516	1460 which follows the closest physical node in 'creature and
rlm@516	1461 sends sound data to 'continuation."
rlm@516	1462 [#^Application world #^Node creature #^Spatial ear continuation]
rlm@516	1463 (let [target (closest-node creature ear)
rlm@516	1464 lis (Listener.)
rlm@516	1465 audio-renderer (.getAudioRenderer world)
rlm@516	1466 sp (hearing-pipeline continuation)]
rlm@516	1467 (.setLocation lis (.getWorldTranslation ear))
rlm@516	1468 (.setRotation lis (.getWorldRotation ear))
rlm@516	1469 (bind-sense target lis)
rlm@516	1470 (update-listener-velocity! target lis)
rlm@516	1471 (.addListener audio-renderer lis)
rlm@516	1472 (.registerSoundProcessor audio-renderer lis sp)))
rlm@516	1473 #+END_SRC
rlm@516	1474 #+end_listing
rlm@516	1475
rlm@516	1476 The =Send= device, unlike most of the other devices in =OpenAL=,
rlm@516	1477 does not render sound unless asked. This enables the system to
rlm@516	1478 slow down or speed up depending on the needs of the AIs who are
rlm@516	1479 using it to listen. If the device tried to render samples in
rlm@516	1480 real-time, a complicated AI whose mind takes 100 seconds of
rlm@516	1481 computer time to simulate 1 second of AI-time would miss almost
rlm@516	1482 all of the sound in its environment!
rlm@516	1483
rlm@516	1484 #+caption: Program to enable arbitrary hearing in =CORTEX=
rlm@516	1485 #+name: hearing
rlm@516	1486 #+begin_listing clojure
rlm@516	1487 #+BEGIN_SRC clojure
rlm@516	1488 (defn hearing-kernel
rlm@516	1489 "Returns a function which returns auditory sensory data when called
rlm@516	1490 inside a running simulation."
rlm@516	1491 [#^Node creature #^Spatial ear]
rlm@516	1492 (let [hearing-data (atom [])
rlm@516	1493 register-listener!
rlm@516	1494 (runonce
rlm@516	1495 (fn [#^Application world]
rlm@516	1496 (add-ear!
rlm@516	1497 world creature ear
rlm@516	1498 (comp #(reset! hearing-data %)
rlm@516	1499 byteBuffer->pulse-vector))))]
rlm@516	1500 (fn [#^Application world]
rlm@516	1501 (register-listener! world)
rlm@516	1502 (let [data @hearing-data
rlm@516	1503 topology
rlm@516	1504 (vec (map #(vector % 0) (range 0 (count data))))]
rlm@516	1505 [topology data]))))
rlm@516	1506
rlm@516	1507 (defn hearing!
rlm@516	1508 "Endow the creature in a particular world with the sense of
rlm@516	1509 hearing. Will return a sequence of functions, one for each ear,
rlm@516	1510 which when called will return the auditory data from that ear."
rlm@516	1511 [#^Node creature]
rlm@516	1512 (for [ear (ears creature)]
rlm@516	1513 (hearing-kernel creature ear)))
rlm@516	1514 #+END_SRC
rlm@516	1515 #+end_listing
rlm@516	1516
rlm@516	1517 Armed with these functions, =CORTEX= is able to test possibly the
rlm@516	1518 first ever instance of multiple listeners in a video game engine
rlm@516	1519 based simulation!
rlm@516	1520
rlm@516	1521 #+caption: Here a simple creature responds to sound by changing
rlm@516	1522 #+caption: its color from gray to green when the total volume
rlm@516	1523 #+caption: goes over a threshold.
rlm@516	1524 #+name: sound-test
rlm@516	1525 #+begin_listing java
rlm@516	1526 #+BEGIN_SRC java
rlm@516	1527 /**
rlm@516	1528 * Respond to sound! This is the brain of an AI entity that
rlm@516	1529 * hears its surroundings and reacts to them.
rlm@516	1530 */
rlm@516	1531 public void process(ByteBuffer audioSamples,
rlm@516	1532 int numSamples, AudioFormat format) {
rlm@516	1533 audioSamples.clear();
rlm@516	1534 byte[] data = new byte[numSamples];
rlm@516	1535 float[] out = new float[numSamples];
rlm@516	1536 audioSamples.get(data);
rlm@516	1537 FloatSampleTools.
rlm@516	1538 byte2floatInterleaved
rlm@516	1539 (data, 0, out, 0, numSamples/format.getFrameSize(), format);
rlm@516	1540
rlm@516	1541 float max = Float.NEGATIVE_INFINITY;
rlm@516	1542 for (float f : out){if (f > max) max = f;}
rlm@516	1543 audioSamples.clear();
rlm@516	1544
rlm@516	1545 if (max > 0.1){
rlm@516	1546 entity.getMaterial().setColor("Color", ColorRGBA.Green);
rlm@516	1547 }
rlm@516	1548 else {
rlm@516	1549 entity.getMaterial().setColor("Color", ColorRGBA.Gray);
rlm@516	1550 }
rlm@516	1551 #+END_SRC
rlm@516	1552 #+end_listing
rlm@516	1553
rlm@516	1554 #+caption: First ever simulation of multiple listerners in =CORTEX=.
rlm@516	1555 #+caption: Each cube is a creature which processes sound data with
rlm@516	1556 #+caption: the =process= function from listing \ref{sound-test}.
rlm@516	1557 #+caption: the ball is constantally emiting a pure tone of
rlm@516	1558 #+caption: constant volume. As it approaches the cubes, they each
rlm@516	1559 #+caption: change color in response to the sound.
rlm@516	1560 #+name: sound-cubes.
rlm@516	1561 #+ATTR_LaTeX: :width 10cm
rlm@516	1562 [[./images/java-hearing-test.png]]
rlm@516	1563
rlm@516	1564 This system of hearing has also been co-opted by the
rlm@516	1565 jMonkeyEngine3 community and is used to record audio for demo
rlm@516	1566 videos.
rlm@516	1567
rlm@516	1568 ** Touch uses hundreds of hair-like elements
rlm@516	1569
rlm@516	1570 Touch is critical to navigation and spatial reasoning and as such I
rlm@516	1571 need a simulated version of it to give to my AI creatures.
rlm@516	1572
rlm@516	1573 Human skin has a wide array of touch sensors, each of which
rlm@516	1574 specialize in detecting different vibrational modes and pressures.
rlm@516	1575 These sensors can integrate a vast expanse of skin (i.e. your
rlm@516	1576 entire palm), or a tiny patch of skin at the tip of your finger.
rlm@516	1577 The hairs of the skin help detect objects before they even come
rlm@516	1578 into contact with the skin proper.
rlm@516	1579
rlm@516	1580 However, touch in my simulated world can not exactly correspond to
rlm@516	1581 human touch because my creatures are made out of completely rigid
rlm@516	1582 segments that don't deform like human skin.
rlm@516	1583
rlm@516	1584 Instead of measuring deformation or vibration, I surround each
rlm@516	1585 rigid part with a plenitude of hair-like objects (/feelers/) which
rlm@516	1586 do not interact with the physical world. Physical objects can pass
rlm@516	1587 through them with no effect. The feelers are able to tell when
rlm@516	1588 other objects pass through them, and they constantly report how
rlm@516	1589 much of their extent is covered. So even though the creature's body
rlm@516	1590 parts do not deform, the feelers create a margin around those body
rlm@516	1591 parts which achieves a sense of touch which is a hybrid between a
rlm@516	1592 human's sense of deformation and sense from hairs.
rlm@516	1593
rlm@516	1594 Implementing touch in jMonkeyEngine follows a different technical
rlm@516	1595 route than vision and hearing. Those two senses piggybacked off
rlm@516	1596 jMonkeyEngine's 3D audio and video rendering subsystems. To
rlm@516	1597 simulate touch, I use jMonkeyEngine's physics system to execute
rlm@516	1598 many small collision detections, one for each feeler. The placement
rlm@516	1599 of the feelers is determined by a UV-mapped image which shows where
rlm@516	1600 each feeler should be on the 3D surface of the body.
rlm@516	1601
rlm@516	1602 *** Defining Touch Meta-Data in Blender
rlm@516	1603
rlm@516	1604 Each geometry can have a single UV map which describes the
rlm@516	1605 position of the feelers which will constitute its sense of touch.
rlm@516	1606 This image path is stored under the ``touch'' key. The image itself
rlm@516	1607 is black and white, with black meaning a feeler length of 0 (no
rlm@516	1608 feeler is present) and white meaning a feeler length of =scale=,
rlm@516	1609 which is a float stored under the key "scale".
rlm@516	1610
rlm@516	1611 #+caption: Touch does not use empty nodes, to store metadata,
rlm@516	1612 #+caption: because the metadata of each solid part of a
rlm@516	1613 #+caption: creature's body is sufficient.
rlm@516	1614 #+name: touch-meta-data
rlm@516	1615 #+begin_listing clojure
rlm@516	1616 #+BEGIN_SRC clojure
rlm@516	1617 (defn tactile-sensor-profile
rlm@516	1618 "Return the touch-sensor distribution image in BufferedImage format,
rlm@516	1619 or nil if it does not exist."
rlm@516	1620 [#^Geometry obj]
rlm@516	1621 (if-let [image-path (meta-data obj "touch")]
rlm@516	1622 (load-image image-path)))
rlm@516	1623
rlm@516	1624 (defn tactile-scale
rlm@516	1625 "Return the length of each feeler. Default scale is 0.01
rlm@516	1626 jMonkeyEngine units."
rlm@516	1627 [#^Geometry obj]
rlm@516	1628 (if-let [scale (meta-data obj "scale")]
rlm@516	1629 scale 0.1))
rlm@516	1630 #+END_SRC
rlm@516	1631 #+end_listing
rlm@516	1632
rlm@516	1633 Here is an example of a UV-map which specifies the position of
rlm@516	1634 touch sensors along the surface of the upper segment of a fingertip.
rlm@516	1635
rlm@516	1636 #+caption: This is the tactile-sensor-profile for the upper segment
rlm@516	1637 #+caption: of a fingertip. It defines regions of high touch sensitivity
rlm@516	1638 #+caption: (where there are many white pixels) and regions of low
rlm@516	1639 #+caption: sensitivity (where white pixels are sparse).
rlm@516	1640 #+name: fingertip-UV
rlm@516	1641 #+ATTR_LaTeX: :width 13cm
rlm@516	1642 [[./images/finger-UV.png]]
rlm@516	1643
rlm@516	1644 *** Implementation Summary
rlm@516	1645
rlm@516	1646 To simulate touch there are three conceptual steps. For each solid
rlm@516	1647 object in the creature, you first have to get UV image and scale
rlm@516	1648 parameter which define the position and length of the feelers.
rlm@516	1649 Then, you use the triangles which comprise the mesh and the UV
rlm@516	1650 data stored in the mesh to determine the world-space position and
rlm@516	1651 orientation of each feeler. Then once every frame, update these
rlm@516	1652 positions and orientations to match the current position and
rlm@516	1653 orientation of the object, and use physics collision detection to
rlm@516	1654 gather tactile data.
rlm@516	1655
rlm@516	1656 Extracting the meta-data has already been described. The third
rlm@516	1657 step, physics collision detection, is handled in =touch-kernel=.
rlm@516	1658 Translating the positions and orientations of the feelers from the
rlm@516	1659 UV-map to world-space is itself a three-step process.
rlm@516	1660
rlm@516	1661 - Find the triangles which make up the mesh in pixel-space and in
rlm@516	1662 world-space. \\(=triangles=, =pixel-triangles=).
rlm@516	1663
rlm@516	1664 - Find the coordinates of each feeler in world-space. These are
rlm@516	1665 the origins of the feelers. (=feeler-origins=).
rlm@516	1666
rlm@516	1667 - Calculate the normals of the triangles in world space, and add
rlm@516	1668 them to each of the origins of the feelers. These are the
rlm@516	1669 normalized coordinates of the tips of the feelers.
rlm@516	1670 (=feeler-tips=).
rlm@516	1671
rlm@516	1672 *** Triangle Math
rlm@516	1673
rlm@516	1674 The rigid objects which make up a creature have an underlying
rlm@516	1675 =Geometry=, which is a =Mesh= plus a =Material= and other
rlm@516	1676 important data involved with displaying the object.
rlm@516	1677
rlm@516	1678 A =Mesh= is composed of =Triangles=, and each =Triangle= has three
rlm@516	1679 vertices which have coordinates in world space and UV space.
rlm@516	1680
rlm@516	1681 Here, =triangles= gets all the world-space triangles which
rlm@516	1682 comprise a mesh, while =pixel-triangles= gets those same triangles
rlm@516	1683 expressed in pixel coordinates (which are UV coordinates scaled to
rlm@516	1684 fit the height and width of the UV image).
rlm@516	1685
rlm@516	1686 #+caption: Programs to extract triangles from a geometry and get
rlm@516	1687 #+caption: their verticies in both world and UV-coordinates.
rlm@516	1688 #+name: get-triangles
rlm@516	1689 #+begin_listing clojure
rlm@516	1690 #+BEGIN_SRC clojure
rlm@516	1691 (defn triangle
rlm@516	1692 "Get the triangle specified by triangle-index from the mesh."
rlm@516	1693 [#^Geometry geo triangle-index]
rlm@516	1694 (triangle-seq
rlm@516	1695 (let [scratch (Triangle.)]
rlm@516	1696 (.getTriangle (.getMesh geo) triangle-index scratch) scratch)))
rlm@516	1697
rlm@516	1698 (defn triangles
rlm@516	1699 "Return a sequence of all the Triangles which comprise a given
rlm@516	1700 Geometry."
rlm@516	1701 [#^Geometry geo]
rlm@516	1702 (map (partial triangle geo) (range (.getTriangleCount (.getMesh geo)))))
rlm@516	1703
rlm@516	1704 (defn triangle-vertex-indices
rlm@516	1705 "Get the triangle vertex indices of a given triangle from a given
rlm@516	1706 mesh."
rlm@516	1707 [#^Mesh mesh triangle-index]
rlm@516	1708 (let [indices (int-array 3)]
rlm@516	1709 (.getTriangle mesh triangle-index indices)
rlm@516	1710 (vec indices)))
rlm@516	1711
rlm@516	1712 (defn vertex-UV-coord
rlm@516	1713 "Get the UV-coordinates of the vertex named by vertex-index"
rlm@516	1714 [#^Mesh mesh vertex-index]
rlm@516	1715 (let [UV-buffer
rlm@516	1716 (.getData
rlm@516	1717 (.getBuffer
rlm@516	1718 mesh
rlm@516	1719 VertexBuffer$Type/TexCoord))]
rlm@516	1720 [(.get UV-buffer (* vertex-index 2))
rlm@516	1721 (.get UV-buffer (+ 1 (* vertex-index 2)))]))
rlm@516	1722
rlm@516	1723 (defn pixel-triangle [#^Geometry geo image index]
rlm@516	1724 (let [mesh (.getMesh geo)
rlm@516	1725 width (.getWidth image)
rlm@516	1726 height (.getHeight image)]
rlm@516	1727 (vec (map (fn [[u v]] (vector (* width u) (* height v)))
rlm@516	1728 (map (partial vertex-UV-coord mesh)
rlm@516	1729 (triangle-vertex-indices mesh index))))))
rlm@516	1730
rlm@516	1731 (defn pixel-triangles
rlm@516	1732 "The pixel-space triangles of the Geometry, in the same order as
rlm@516	1733 (triangles geo)"
rlm@516	1734 [#^Geometry geo image]
rlm@516	1735 (let [height (.getHeight image)
rlm@516	1736 width (.getWidth image)]
rlm@516	1737 (map (partial pixel-triangle geo image)
rlm@516	1738 (range (.getTriangleCount (.getMesh geo))))))
rlm@516	1739 #+END_SRC
rlm@516	1740 #+end_listing
rlm@516	1741
rlm@516	1742 *** The Affine Transform from one Triangle to Another
rlm@516	1743
rlm@516	1744 =pixel-triangles= gives us the mesh triangles expressed in pixel
rlm@516	1745 coordinates and =triangles= gives us the mesh triangles expressed
rlm@516	1746 in world coordinates. The tactile-sensor-profile gives the
rlm@516	1747 position of each feeler in pixel-space. In order to convert
rlm@516	1748 pixel-space coordinates into world-space coordinates we need
rlm@516	1749 something that takes coordinates on the surface of one triangle
rlm@516	1750 and gives the corresponding coordinates on the surface of another
rlm@516	1751 triangle.
rlm@516	1752
rlm@516	1753 Triangles are [[http://mathworld.wolfram.com/AffineTransformation.html ][affine]], which means any triangle can be transformed
rlm@516	1754 into any other by a combination of translation, scaling, and
rlm@516	1755 rotation. The affine transformation from one triangle to another
rlm@516	1756 is readily computable if the triangle is expressed in terms of a
rlm@516	1757 $4x4$ matrix.
rlm@516	1758
rlm@516	1759 #+BEGIN_LaTeX
rlm@516	1760 $$
rlm@516	1761 \begin{bmatrix}
rlm@516	1762 x_1 & x_2 & x_3 & n_x \\
rlm@516	1763 y_1 & y_2 & y_3 & n_y \\
rlm@516	1764 z_1 & z_2 & z_3 & n_z \\
rlm@516	1765 1 & 1 & 1 & 1
rlm@516	1766 \end{bmatrix}
rlm@516	1767 $$
rlm@516	1768 #+END_LaTeX
rlm@516	1769
rlm@516	1770 Here, the first three columns of the matrix are the vertices of
rlm@516	1771 the triangle. The last column is the right-handed unit normal of
rlm@516	1772 the triangle.
rlm@516	1773
rlm@516	1774 With two triangles $T_{1}$ and $T_{2}$ each expressed as a
rlm@516	1775 matrix like above, the affine transform from $T_{1}$ to $T_{2}$
rlm@516	1776 is $T_{2}T_{1}^{-1}$.
rlm@516	1777
rlm@516	1778 The clojure code below recapitulates the formulas above, using
rlm@516	1779 jMonkeyEngine's =Matrix4f= objects, which can describe any affine
rlm@516	1780 transformation.
rlm@516	1781
rlm@516	1782 #+caption: Program to interpert triangles as affine transforms.
rlm@516	1783 #+name: triangle-affine
rlm@516	1784 #+begin_listing clojure
rlm@516	1785 #+BEGIN_SRC clojure
rlm@516	1786 (defn triangle->matrix4f
rlm@516	1787 "Converts the triangle into a 4x4 matrix: The first three columns
rlm@516	1788 contain the vertices of the triangle; the last contains the unit
rlm@516	1789 normal of the triangle. The bottom row is filled with 1s."
rlm@516	1790 [#^Triangle t]
rlm@516	1791 (let [mat (Matrix4f.)
rlm@516	1792 [vert-1 vert-2 vert-3]
rlm@516	1793 (mapv #(.get t %) (range 3))
rlm@516	1794 unit-normal (do (.calculateNormal t)(.getNormal t))
rlm@516	1795 vertices [vert-1 vert-2 vert-3 unit-normal]]
rlm@516	1796 (dorun
rlm@516	1797 (for [row (range 4) col (range 3)]
rlm@516	1798 (do
rlm@516	1799 (.set mat col row (.get (vertices row) col))
rlm@516	1800 (.set mat 3 row 1)))) mat))
rlm@516	1801
rlm@516	1802 (defn triangles->affine-transform
rlm@516	1803 "Returns the affine transformation that converts each vertex in the
rlm@516	1804 first triangle into the corresponding vertex in the second
rlm@516	1805 triangle."
rlm@516	1806 [#^Triangle tri-1 #^Triangle tri-2]
rlm@516	1807 (.mult
rlm@516	1808 (triangle->matrix4f tri-2)
rlm@516	1809 (.invert (triangle->matrix4f tri-1))))
rlm@516	1810 #+END_SRC
rlm@516	1811 #+end_listing
rlm@516	1812
rlm@516	1813 *** Triangle Boundaries
rlm@516	1814
rlm@516	1815 For efficiency's sake I will divide the tactile-profile image into
rlm@516	1816 small squares which inscribe each pixel-triangle, then extract the
rlm@516	1817 points which lie inside the triangle and map them to 3D-space using
rlm@516	1818 =triangle-transform= above. To do this I need a function,
rlm@516	1819 =convex-bounds= which finds the smallest box which inscribes a 2D
rlm@516	1820 triangle.
rlm@516	1821
rlm@516	1822 =inside-triangle?= determines whether a point is inside a triangle
rlm@516	1823 in 2D pixel-space.
rlm@516	1824
rlm@516	1825 #+caption: Program to efficiently determine point includion
rlm@516	1826 #+caption: in a triangle.
rlm@516	1827 #+name: in-triangle
rlm@516	1828 #+begin_listing clojure
rlm@516	1829 #+BEGIN_SRC clojure
rlm@516	1830 (defn convex-bounds
rlm@516	1831 "Returns the smallest square containing the given vertices, as a
rlm@516	1832 vector of integers [left top width height]."
rlm@516	1833 [verts]
rlm@516	1834 (let [xs (map first verts)
rlm@516	1835 ys (map second verts)
rlm@516	1836 x0 (Math/floor (apply min xs))
rlm@516	1837 y0 (Math/floor (apply min ys))
rlm@516	1838 x1 (Math/ceil (apply max xs))
rlm@516	1839 y1 (Math/ceil (apply max ys))]
rlm@516	1840 [x0 y0 (- x1 x0) (- y1 y0)]))
rlm@516	1841
rlm@516	1842 (defn same-side?
rlm@516	1843 "Given the points p1 and p2 and the reference point ref, is point p
rlm@516	1844 on the same side of the line that goes through p1 and p2 as ref is?"
rlm@516	1845 [p1 p2 ref p]
rlm@516	1846 (<=
rlm@516	1847 0
rlm@516	1848 (.dot
rlm@516	1849 (.cross (.subtract p2 p1) (.subtract p p1))
rlm@516	1850 (.cross (.subtract p2 p1) (.subtract ref p1)))))
rlm@516	1851
rlm@516	1852 (defn inside-triangle?
rlm@516	1853 "Is the point inside the triangle?"
rlm@516	1854 {:author "Dylan Holmes"}
rlm@516	1855 [#^Triangle tri #^Vector3f p]
rlm@516	1856 (let [[vert-1 vert-2 vert-3] [(.get1 tri) (.get2 tri) (.get3 tri)]]
rlm@516	1857 (and
rlm@516	1858 (same-side? vert-1 vert-2 vert-3 p)
rlm@516	1859 (same-side? vert-2 vert-3 vert-1 p)
rlm@516	1860 (same-side? vert-3 vert-1 vert-2 p))))
rlm@516	1861 #+END_SRC
rlm@516	1862 #+end_listing
rlm@516	1863
rlm@516	1864 *** Feeler Coordinates
rlm@516	1865
rlm@516	1866 The triangle-related functions above make short work of
rlm@516	1867 calculating the positions and orientations of each feeler in
rlm@516	1868 world-space.
rlm@516	1869
rlm@516	1870 #+caption: Program to get the coordinates of ``feelers '' in
rlm@516	1871 #+caption: both world and UV-coordinates.
rlm@516	1872 #+name: feeler-coordinates
rlm@516	1873 #+begin_listing clojure
rlm@516	1874 #+BEGIN_SRC clojure
rlm@516	1875 (defn feeler-pixel-coords
rlm@516	1876 "Returns the coordinates of the feelers in pixel space in lists, one
rlm@516	1877 list for each triangle, ordered in the same way as (triangles) and
rlm@516	1878 (pixel-triangles)."
rlm@516	1879 [#^Geometry geo image]
rlm@516	1880 (map
rlm@516	1881 (fn [pixel-triangle]
rlm@516	1882 (filter
rlm@516	1883 (fn [coord]
rlm@516	1884 (inside-triangle? (->triangle pixel-triangle)
rlm@516	1885 (->vector3f coord)))
rlm@516	1886 (white-coordinates image (convex-bounds pixel-triangle))))
rlm@516	1887 (pixel-triangles geo image)))
rlm@516	1888
rlm@516	1889 (defn feeler-world-coords
rlm@516	1890 "Returns the coordinates of the feelers in world space in lists, one
rlm@516	1891 list for each triangle, ordered in the same way as (triangles) and
rlm@516	1892 (pixel-triangles)."
rlm@516	1893 [#^Geometry geo image]
rlm@516	1894 (let [transforms
rlm@516	1895 (map #(triangles->affine-transform
rlm@516	1896 (->triangle %1) (->triangle %2))
rlm@516	1897 (pixel-triangles geo image)
rlm@516	1898 (triangles geo))]
rlm@516	1899 (map (fn [transform coords]
rlm@516	1900 (map #(.mult transform (->vector3f %)) coords))
rlm@516	1901 transforms (feeler-pixel-coords geo image))))
rlm@516	1902 #+END_SRC
rlm@516	1903 #+end_listing
rlm@516	1904
rlm@516	1905 #+caption: Program to get the position of the base and tip of
rlm@516	1906 #+caption: each ``feeler''
rlm@516	1907 #+name: feeler-tips
rlm@516	1908 #+begin_listing clojure
rlm@516	1909 #+BEGIN_SRC clojure
rlm@516	1910 (defn feeler-origins
rlm@516	1911 "The world space coordinates of the root of each feeler."
rlm@516	1912 [#^Geometry geo image]
rlm@516	1913 (reduce concat (feeler-world-coords geo image)))
rlm@516	1914
rlm@516	1915 (defn feeler-tips
rlm@516	1916 "The world space coordinates of the tip of each feeler."
rlm@516	1917 [#^Geometry geo image]
rlm@516	1918 (let [world-coords (feeler-world-coords geo image)
rlm@516	1919 normals
rlm@516	1920 (map
rlm@516	1921 (fn [triangle]
rlm@516	1922 (.calculateNormal triangle)
rlm@516	1923 (.clone (.getNormal triangle)))
rlm@516	1924 (map ->triangle (triangles geo)))]
rlm@516	1925
rlm@516	1926 (mapcat (fn [origins normal]
rlm@516	1927 (map #(.add % normal) origins))
rlm@516	1928 world-coords normals)))
rlm@516	1929
rlm@516	1930 (defn touch-topology
rlm@516	1931 [#^Geometry geo image]
rlm@516	1932 (collapse (reduce concat (feeler-pixel-coords geo image))))
rlm@516	1933 #+END_SRC
rlm@516	1934 #+end_listing
rlm@516	1935
rlm@516	1936 *** Simulated Touch
rlm@516	1937
rlm@516	1938 Now that the functions to construct feelers are complete,
rlm@516	1939 =touch-kernel= generates functions to be called from within a
rlm@516	1940 simulation that perform the necessary physics collisions to
rlm@516	1941 collect tactile data, and =touch!= recursively applies it to every
rlm@516	1942 node in the creature.
rlm@516	1943
rlm@516	1944 #+caption: Efficient program to transform a ray from
rlm@516	1945 #+caption: one position to another.
rlm@516	1946 #+name: set-ray
rlm@516	1947 #+begin_listing clojure
rlm@516	1948 #+BEGIN_SRC clojure
rlm@516	1949 (defn set-ray [#^Ray ray #^Matrix4f transform
rlm@516	1950 #^Vector3f origin #^Vector3f tip]
rlm@516	1951 ;; Doing everything locally reduces garbage collection by enough to
rlm@516	1952 ;; be worth it.
rlm@516	1953 (.mult transform origin (.getOrigin ray))
rlm@516	1954 (.mult transform tip (.getDirection ray))
rlm@516	1955 (.subtractLocal (.getDirection ray) (.getOrigin ray))
rlm@516	1956 (.normalizeLocal (.getDirection ray)))
rlm@516	1957 #+END_SRC
rlm@516	1958 #+end_listing
rlm@516	1959
rlm@516	1960 #+caption: This is the core of touch in =CORTEX= each feeler
rlm@516	1961 #+caption: follows the object it is bound to, reporting any
rlm@516	1962 #+caption: collisions that may happen.
rlm@516	1963 #+name: touch-kernel
rlm@516	1964 #+begin_listing clojure
rlm@516	1965 #+BEGIN_SRC clojure
rlm@516	1966 (defn touch-kernel
rlm@516	1967 "Constructs a function which will return tactile sensory data from
rlm@516	1968 'geo when called from inside a running simulation"
rlm@516	1969 [#^Geometry geo]
rlm@516	1970 (if-let
rlm@516	1971 [profile (tactile-sensor-profile geo)]
rlm@516	1972 (let [ray-reference-origins (feeler-origins geo profile)
rlm@516	1973 ray-reference-tips (feeler-tips geo profile)
rlm@516	1974 ray-length (tactile-scale geo)
rlm@516	1975 current-rays (map (fn [_] (Ray.)) ray-reference-origins)
rlm@516	1976 topology (touch-topology geo profile)
rlm@516	1977 correction (float (* ray-length -0.2))]
rlm@516	1978 ;; slight tolerance for very close collisions.
rlm@516	1979 (dorun
rlm@516	1980 (map (fn [origin tip]
rlm@516	1981 (.addLocal origin (.mult (.subtract tip origin)
rlm@516	1982 correction)))
rlm@516	1983 ray-reference-origins ray-reference-tips))
rlm@516	1984 (dorun (map #(.setLimit % ray-length) current-rays))
rlm@516	1985 (fn [node]
rlm@516	1986 (let [transform (.getWorldMatrix geo)]
rlm@516	1987 (dorun
rlm@516	1988 (map (fn [ray ref-origin ref-tip]
rlm@516	1989 (set-ray ray transform ref-origin ref-tip))
rlm@516	1990 current-rays ray-reference-origins
rlm@516	1991 ray-reference-tips))
rlm@516	1992 (vector
rlm@516	1993 topology
rlm@516	1994 (vec
rlm@516	1995 (for [ray current-rays]
rlm@516	1996 (do
rlm@516	1997 (let [results (CollisionResults.)]
rlm@516	1998 (.collideWith node ray results)
rlm@516	1999 (let [touch-objects
rlm@516	2000 (filter #(not (= geo (.getGeometry %)))
rlm@516	2001 results)
rlm@516	2002 limit (.getLimit ray)]
rlm@516	2003 [(if (empty? touch-objects)
rlm@516	2004 limit
rlm@516	2005 (let [response
rlm@516	2006 (apply min (map #(.getDistance %)
rlm@516	2007 touch-objects))]
rlm@516	2008 (FastMath/clamp
rlm@516	2009 (float
rlm@516	2010 (if (> response limit) (float 0.0)
rlm@516	2011 (+ response correction)))
rlm@516	2012 (float 0.0)
rlm@516	2013 limit)))
rlm@516	2014 limit])))))))))))
rlm@516	2015 #+END_SRC
rlm@516	2016 #+end_listing
rlm@516	2017
rlm@516	2018 Armed with the =touch!= function, =CORTEX= becomes capable of
rlm@516	2019 giving creatures a sense of touch. A simple test is to create a
rlm@516	2020 cube that is outfitted with a uniform distrubition of touch
rlm@516	2021 sensors. It can feel the ground and any balls that it touches.
rlm@516	2022
rlm@516	2023 #+caption: =CORTEX= interface for creating touch in a simulated
rlm@516	2024 #+caption: creature.
rlm@516	2025 #+name: touch
rlm@516	2026 #+begin_listing clojure
rlm@516	2027 #+BEGIN_SRC clojure
rlm@516	2028 (defn touch!
rlm@516	2029 "Endow the creature with the sense of touch. Returns a sequence of
rlm@516	2030 functions, one for each body part with a tactile-sensor-profile,
rlm@516	2031 each of which when called returns sensory data for that body part."
rlm@516	2032 [#^Node creature]
rlm@516	2033 (filter
rlm@516	2034 (comp not nil?)
rlm@516	2035 (map touch-kernel
rlm@516	2036 (filter #(isa? (class %) Geometry)
rlm@516	2037 (node-seq creature)))))
rlm@516	2038 #+END_SRC
rlm@516	2039 #+end_listing
rlm@516	2040
rlm@516	2041 The tactile-sensor-profile image for the touch cube is a simple
rlm@516	2042 cross with a unifom distribution of touch sensors:
rlm@516	2043
rlm@516	2044 #+caption: The touch profile for the touch-cube. Each pure white
rlm@516	2045 #+caption: pixel defines a touch sensitive feeler.
rlm@516	2046 #+name: touch-cube-uv-map
rlm@516	2047 #+ATTR_LaTeX: :width 7cm
rlm@516	2048 [[./images/touch-profile.png]]
rlm@516	2049
rlm@516	2050 #+caption: The touch cube reacts to canonballs. The black, red,
rlm@516	2051 #+caption: and white cross on the right is a visual display of
rlm@516	2052 #+caption: the creature's touch. White means that it is feeling
rlm@516	2053 #+caption: something strongly, black is not feeling anything,
rlm@516	2054 #+caption: and gray is in-between. The cube can feel both the
rlm@516	2055 #+caption: floor and the ball. Notice that when the ball causes
rlm@516	2056 #+caption: the cube to tip, that the bottom face can still feel
rlm@516	2057 #+caption: part of the ground.
rlm@516	2058 #+name: touch-cube-uv-map
rlm@516	2059 #+ATTR_LaTeX: :width 15cm
rlm@516	2060 [[./images/touch-cube.png]]
rlm@516	2061
rlm@516	2062 ** Proprioception is the sense that makes everything ``real''
rlm@516	2063
rlm@516	2064 Close your eyes, and touch your nose with your right index finger.
rlm@516	2065 How did you do it? You could not see your hand, and neither your
rlm@516	2066 hand nor your nose could use the sense of touch to guide the path
rlm@516	2067 of your hand. There are no sound cues, and Taste and Smell
rlm@516	2068 certainly don't provide any help. You know where your hand is
rlm@516	2069 without your other senses because of Proprioception.
rlm@516	2070
rlm@516	2071 Humans can sometimes loose this sense through viral infections or
rlm@516	2072 damage to the spinal cord or brain, and when they do, they loose
rlm@516	2073 the ability to control their own bodies without looking directly at
rlm@516	2074 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
rlm@516	2075 Hat]], a woman named Christina looses this sense and has to learn how
rlm@516	2076 to move by carefully watching her arms and legs. She describes
rlm@516	2077 proprioception as the "eyes of the body, the way the body sees
rlm@516	2078 itself".
rlm@516	2079
rlm@516	2080 Proprioception in humans is mediated by [[http://en.wikipedia.org/wiki/Articular_capsule][joint capsules]], [[http://en.wikipedia.org/wiki/Muscle_spindle][muscle
rlm@516	2081 spindles]], and the [[http://en.wikipedia.org/wiki/Golgi_tendon_organ][Golgi tendon organs]]. These measure the relative
rlm@516	2082 positions of each body part by monitoring muscle strain and length.
rlm@516	2083
rlm@516	2084 It's clear that this is a vital sense for fluid, graceful movement.
rlm@516	2085 It's also particularly easy to implement in jMonkeyEngine.
rlm@516	2086
rlm@516	2087 My simulated proprioception calculates the relative angles of each
rlm@516	2088 joint from the rest position defined in the blender file. This
rlm@516	2089 simulates the muscle-spindles and joint capsules. I will deal with
rlm@516	2090 Golgi tendon organs, which calculate muscle strain, in the next
rlm@516	2091 section.
rlm@516	2092
rlm@516	2093 *** Helper functions
rlm@516	2094
rlm@516	2095 =absolute-angle= calculates the angle between two vectors,
rlm@516	2096 relative to a third axis vector. This angle is the number of
rlm@516	2097 radians you have to move counterclockwise around the axis vector
rlm@516	2098 to get from the first to the second vector. It is not commutative
rlm@516	2099 like a normal dot-product angle is.
rlm@516	2100
rlm@516	2101 The purpose of these functions is to build a system of angle
rlm@516	2102 measurement that is biologically plausable.
rlm@516	2103
rlm@516	2104 #+caption: Program to measure angles along a vector
rlm@516	2105 #+name: helpers
rlm@516	2106 #+begin_listing clojure
rlm@516	2107 #+BEGIN_SRC clojure
rlm@516	2108 (defn right-handed?
rlm@516	2109 "true iff the three vectors form a right handed coordinate
rlm@516	2110 system. The three vectors do not have to be normalized or
rlm@516	2111 orthogonal."
rlm@516	2112 [vec1 vec2 vec3]
rlm@516	2113 (pos? (.dot (.cross vec1 vec2) vec3)))
rlm@516	2114
rlm@516	2115 (defn absolute-angle
rlm@516	2116 "The angle between 'vec1 and 'vec2 around 'axis. In the range
rlm@516	2117 [0 (* 2 Math/PI)]."
rlm@516	2118 [vec1 vec2 axis]
rlm@516	2119 (let [angle (.angleBetween vec1 vec2)]
rlm@516	2120 (if (right-handed? vec1 vec2 axis)
rlm@516	2121 angle (- (* 2 Math/PI) angle))))
rlm@516	2122 #+END_SRC
rlm@516	2123 #+end_listing
rlm@516	2124
rlm@516	2125 *** Proprioception Kernel
rlm@516	2126
rlm@516	2127 Given a joint, =proprioception-kernel= produces a function that
rlm@516	2128 calculates the Euler angles between the the objects the joint
rlm@516	2129 connects. The only tricky part here is making the angles relative
rlm@516	2130 to the joint's initial ``straightness''.
rlm@516	2131
rlm@516	2132 #+caption: Program to return biologially reasonable proprioceptive
rlm@516	2133 #+caption: data for each joint.
rlm@516	2134 #+name: proprioception
rlm@516	2135 #+begin_listing clojure
rlm@516	2136 #+BEGIN_SRC clojure
rlm@516	2137 (defn proprioception-kernel
rlm@516	2138 "Returns a function which returns proprioceptive sensory data when
rlm@516	2139 called inside a running simulation."
rlm@516	2140 [#^Node parts #^Node joint]
rlm@516	2141 (let [[obj-a obj-b] (joint-targets parts joint)
rlm@516	2142 joint-rot (.getWorldRotation joint)
rlm@516	2143 x0 (.mult joint-rot Vector3f/UNIT_X)
rlm@516	2144 y0 (.mult joint-rot Vector3f/UNIT_Y)
rlm@516	2145 z0 (.mult joint-rot Vector3f/UNIT_Z)]
rlm@516	2146 (fn []
rlm@516	2147 (let [rot-a (.clone (.getWorldRotation obj-a))
rlm@516	2148 rot-b (.clone (.getWorldRotation obj-b))
rlm@516	2149 x (.mult rot-a x0)
rlm@516	2150 y (.mult rot-a y0)
rlm@516	2151 z (.mult rot-a z0)
rlm@516	2152
rlm@516	2153 X (.mult rot-b x0)
rlm@516	2154 Y (.mult rot-b y0)
rlm@516	2155 Z (.mult rot-b z0)
rlm@516	2156 heading (Math/atan2 (.dot X z) (.dot X x))
rlm@516	2157 pitch (Math/atan2 (.dot X y) (.dot X x))
rlm@516	2158
rlm@516	2159 ;; rotate x-vector back to origin
rlm@516	2160 reverse
rlm@516	2161 (doto (Quaternion.)
rlm@516	2162 (.fromAngleAxis
rlm@516	2163 (.angleBetween X x)
rlm@516	2164 (let [cross (.normalize (.cross X x))]
rlm@516	2165 (if (= 0 (.length cross)) y cross))))
rlm@516	2166 roll (absolute-angle (.mult reverse Y) y x)]
rlm@516	2167 [heading pitch roll]))))
rlm@516	2168
rlm@516	2169 (defn proprioception!
rlm@516	2170 "Endow the creature with the sense of proprioception. Returns a
rlm@516	2171 sequence of functions, one for each child of the \"joints\" node in
rlm@516	2172 the creature, which each report proprioceptive information about
rlm@516	2173 that joint."
rlm@516	2174 [#^Node creature]
rlm@516	2175 ;; extract the body's joints
rlm@516	2176 (let [senses (map (partial proprioception-kernel creature)
rlm@516	2177 (joints creature))]
rlm@516	2178 (fn []
rlm@516	2179 (map #(%) senses))))
rlm@516	2180 #+END_SRC
rlm@516	2181 #+end_listing
rlm@516	2182
rlm@516	2183 =proprioception!= maps =proprioception-kernel= across all the
rlm@516	2184 joints of the creature. It uses the same list of joints that
rlm@516	2185 =joints= uses. Proprioception is the easiest sense to implement in
rlm@516	2186 =CORTEX=, and it will play a crucial role when efficiently
rlm@516	2187 implementing empathy.
rlm@516	2188
rlm@516	2189 #+caption: In the upper right corner, the three proprioceptive
rlm@516	2190 #+caption: angle measurements are displayed. Red is yaw, Green is
rlm@516	2191 #+caption: pitch, and White is roll.
rlm@516	2192 #+name: proprio
rlm@516	2193 #+ATTR_LaTeX: :width 11cm
rlm@516	2194 [[./images/proprio.png]]
rlm@516	2195
rlm@516	2196 ** Muscles are both effectors and sensors
rlm@516	2197
rlm@516	2198 Surprisingly enough, terrestrial creatures only move by using
rlm@516	2199 torque applied about their joints. There's not a single straight
rlm@516	2200 line of force in the human body at all! (A straight line of force
rlm@516	2201 would correspond to some sort of jet or rocket propulsion.)
rlm@516	2202
rlm@516	2203 In humans, muscles are composed of muscle fibers which can contract
rlm@516	2204 to exert force. The muscle fibers which compose a muscle are
rlm@516	2205 partitioned into discrete groups which are each controlled by a
rlm@516	2206 single alpha motor neuron. A single alpha motor neuron might
rlm@516	2207 control as little as three or as many as one thousand muscle
rlm@516	2208 fibers. When the alpha motor neuron is engaged by the spinal cord,
rlm@516	2209 it activates all of the muscle fibers to which it is attached. The
rlm@516	2210 spinal cord generally engages the alpha motor neurons which control
rlm@516	2211 few muscle fibers before the motor neurons which control many
rlm@516	2212 muscle fibers. This recruitment strategy allows for precise
rlm@516	2213 movements at low strength. The collection of all motor neurons that
rlm@516	2214 control a muscle is called the motor pool. The brain essentially
rlm@516	2215 says "activate 30% of the motor pool" and the spinal cord recruits
rlm@516	2216 motor neurons until 30% are activated. Since the distribution of
rlm@516	2217 power among motor neurons is unequal and recruitment goes from
rlm@516	2218 weakest to strongest, the first 30% of the motor pool might be 5%
rlm@516	2219 of the strength of the muscle.
rlm@516	2220
rlm@516	2221 My simulated muscles follow a similar design: Each muscle is
rlm@516	2222 defined by a 1-D array of numbers (the "motor pool"). Each entry in
rlm@516	2223 the array represents a motor neuron which controls a number of
rlm@516	2224 muscle fibers equal to the value of the entry. Each muscle has a
rlm@516	2225 scalar strength factor which determines the total force the muscle
rlm@516	2226 can exert when all motor neurons are activated. The effector
rlm@516	2227 function for a muscle takes a number to index into the motor pool,
rlm@516	2228 and then "activates" all the motor neurons whose index is lower or
rlm@516	2229 equal to the number. Each motor-neuron will apply force in
rlm@516	2230 proportion to its value in the array. Lower values cause less
rlm@516	2231 force. The lower values can be put at the "beginning" of the 1-D
rlm@516	2232 array to simulate the layout of actual human muscles, which are
rlm@516	2233 capable of more precise movements when exerting less force. Or, the
rlm@516	2234 motor pool can simulate more exotic recruitment strategies which do
rlm@516	2235 not correspond to human muscles.
rlm@516	2236
rlm@516	2237 This 1D array is defined in an image file for ease of
rlm@516	2238 creation/visualization. Here is an example muscle profile image.
rlm@516	2239
rlm@516	2240 #+caption: A muscle profile image that describes the strengths
rlm@516	2241 #+caption: of each motor neuron in a muscle. White is weakest
rlm@516	2242 #+caption: and dark red is strongest. This particular pattern
rlm@516	2243 #+caption: has weaker motor neurons at the beginning, just
rlm@516	2244 #+caption: like human muscle.
rlm@516	2245 #+name: muscle-recruit
rlm@516	2246 #+ATTR_LaTeX: :width 7cm
rlm@516	2247 [[./images/basic-muscle.png]]
rlm@516	2248
rlm@516	2249 *** Muscle meta-data
rlm@516	2250
rlm@516	2251 #+caption: Program to deal with loading muscle data from a blender
rlm@516	2252 #+caption: file's metadata.
rlm@516	2253 #+name: motor-pool
rlm@516	2254 #+begin_listing clojure
rlm@516	2255 #+BEGIN_SRC clojure
rlm@516	2256 (defn muscle-profile-image
rlm@516	2257 "Get the muscle-profile image from the node's blender meta-data."
rlm@516	2258 [#^Node muscle]
rlm@516	2259 (if-let [image (meta-data muscle "muscle")]
rlm@516	2260 (load-image image)))
rlm@516	2261
rlm@516	2262 (defn muscle-strength
rlm@516	2263 "Return the strength of this muscle, or 1 if it is not defined."
rlm@516	2264 [#^Node muscle]
rlm@516	2265 (if-let [strength (meta-data muscle "strength")]
rlm@516	2266 strength 1))
rlm@516	2267
rlm@516	2268 (defn motor-pool
rlm@516	2269 "Return a vector where each entry is the strength of the \"motor
rlm@516	2270 neuron\" at that part in the muscle."
rlm@516	2271 [#^Node muscle]
rlm@516	2272 (let [profile (muscle-profile-image muscle)]
rlm@516	2273 (vec
rlm@516	2274 (let [width (.getWidth profile)]
rlm@516	2275 (for [x (range width)]
rlm@516	2276 (- 255
rlm@516	2277 (bit-and
rlm@516	2278 0x0000FF
rlm@516	2279 (.getRGB profile x 0))))))))
rlm@516	2280 #+END_SRC
rlm@516	2281 #+end_listing
rlm@516	2282
rlm@516	2283 Of note here is =motor-pool= which interprets the muscle-profile
rlm@516	2284 image in a way that allows me to use gradients between white and
rlm@516	2285 red, instead of shades of gray as I've been using for all the
rlm@516	2286 other senses. This is purely an aesthetic touch.
rlm@516	2287
rlm@516	2288 *** Creating muscles
rlm@516	2289
rlm@516	2290 #+caption: This is the core movement functoion in =CORTEX=, which
rlm@516	2291 #+caption: implements muscles that report on their activation.
rlm@516	2292 #+name: muscle-kernel
rlm@516	2293 #+begin_listing clojure
rlm@516	2294 #+BEGIN_SRC clojure
rlm@516	2295 (defn movement-kernel
rlm@516	2296 "Returns a function which when called with a integer value inside a
rlm@516	2297 running simulation will cause movement in the creature according
rlm@516	2298 to the muscle's position and strength profile. Each function
rlm@516	2299 returns the amount of force applied / max force."
rlm@516	2300 [#^Node creature #^Node muscle]
rlm@516	2301 (let [target (closest-node creature muscle)
rlm@516	2302 axis
rlm@516	2303 (.mult (.getWorldRotation muscle) Vector3f/UNIT_Y)
rlm@516	2304 strength (muscle-strength muscle)
rlm@516	2305
rlm@516	2306 pool (motor-pool muscle)
rlm@516	2307 pool-integral (reductions + pool)
rlm@516	2308 forces
rlm@516	2309 (vec (map #(float (* strength (/ % (last pool-integral))))
rlm@516	2310 pool-integral))
rlm@516	2311 control (.getControl target RigidBodyControl)]
rlm@516	2312 ;;(println-repl (.getName target) axis)
rlm@516	2313 (fn [n]
rlm@516	2314 (let [pool-index (max 0 (min n (dec (count pool))))
rlm@516	2315 force (forces pool-index)]
rlm@516	2316 (.applyTorque control (.mult axis force))
rlm@516	2317 (float (/ force strength))))))
rlm@516	2318
rlm@516	2319 (defn movement!
rlm@516	2320 "Endow the creature with the power of movement. Returns a sequence
rlm@516	2321 of functions, each of which accept an integer value and will
rlm@516	2322 activate their corresponding muscle."
rlm@516	2323 [#^Node creature]
rlm@516	2324 (for [muscle (muscles creature)]
rlm@516	2325 (movement-kernel creature muscle)))
rlm@516	2326 #+END_SRC
rlm@516	2327 #+end_listing
rlm@516	2328
rlm@516	2329
rlm@516	2330 =movement-kernel= creates a function that will move the nearest
rlm@516	2331 physical object to the muscle node. The muscle exerts a rotational
rlm@516	2332 force dependent on it's orientation to the object in the blender
rlm@516	2333 file. The function returned by =movement-kernel= is also a sense
rlm@516	2334 function: it returns the percent of the total muscle strength that
rlm@516	2335 is currently being employed. This is analogous to muscle tension
rlm@516	2336 in humans and completes the sense of proprioception begun in the
rlm@516	2337 last section.
rlm@516	2338
rlm@516	2339 ** =CORTEX= brings complex creatures to life!
rlm@516	2340
rlm@516	2341 The ultimate test of =CORTEX= is to create a creature with the full
rlm@516	2342 gamut of senses and put it though its paces.
rlm@516	2343
rlm@516	2344 With all senses enabled, my right hand model looks like an
rlm@516	2345 intricate marionette hand with several strings for each finger:
rlm@516	2346
rlm@516	2347 #+caption: View of the hand model with all sense nodes. You can see
rlm@516	2348 #+caption: the joint, muscle, ear, and eye nodess here.
rlm@516	2349 #+name: hand-nodes-1
rlm@516	2350 #+ATTR_LaTeX: :width 11cm
rlm@516	2351 [[./images/hand-with-all-senses2.png]]
rlm@516	2352
rlm@516	2353 #+caption: An alternate view of the hand.
rlm@516	2354 #+name: hand-nodes-2
rlm@516	2355 #+ATTR_LaTeX: :width 15cm
rlm@516	2356 [[./images/hand-with-all-senses3.png]]
rlm@516	2357
rlm@516	2358 With the hand fully rigged with senses, I can run it though a test
rlm@516	2359 that will test everything.
rlm@516	2360
rlm@516	2361 #+caption: A full test of the hand with all senses. Note expecially
rlm@516	2362 #+caption: the interactions the hand has with itself: it feels
rlm@516	2363 #+caption: its own palm and fingers, and when it curls its fingers,
rlm@516	2364 #+caption: it sees them with its eye (which is located in the center
rlm@516	2365 #+caption: of the palm. The red block appears with a pure tone sound.
rlm@516	2366 #+caption: The hand then uses its muscles to launch the cube!
rlm@516	2367 #+name: integration
rlm@516	2368 #+ATTR_LaTeX: :width 16cm
rlm@516	2369 [[./images/integration.png]]
rlm@516	2370
rlm@516	2371 ** =CORTEX= enables many possiblities for further research
rlm@516	2372
rlm@516	2373 Often times, the hardest part of building a system involving
rlm@516	2374 creatures is dealing with physics and graphics. =CORTEX= removes
rlm@516	2375 much of this initial difficulty and leaves researchers free to
rlm@516	2376 directly pursue their ideas. I hope that even undergrads with a
rlm@516	2377 passing curiosity about simulated touch or creature evolution will
rlm@516	2378 be able to use cortex for experimentation. =CORTEX= is a completely
rlm@516	2379 simulated world, and far from being a disadvantage, its simulated
rlm@516	2380 nature enables you to create senses and creatures that would be
rlm@516	2381 impossible to make in the real world.
rlm@516	2382
rlm@516	2383 While not by any means a complete list, here are some paths
rlm@516	2384 =CORTEX= is well suited to help you explore:
rlm@516	2385
rlm@516	2386 - Empathy :: my empathy program leaves many areas for
rlm@516	2387 improvement, among which are using vision to infer
rlm@516	2388 proprioception and looking up sensory experience with imagined
rlm@516	2389 vision, touch, and sound.
rlm@516	2390 - Evolution :: Karl Sims created a rich environment for
rlm@516	2391 simulating the evolution of creatures on a connection
rlm@516	2392 machine. Today, this can be redone and expanded with =CORTEX=
rlm@516	2393 on an ordinary computer.
rlm@516	2394 - Exotic senses :: Cortex enables many fascinating senses that are
rlm@516	2395 not possible to build in the real world. For example,
rlm@516	2396 telekinesis is an interesting avenue to explore. You can also
rlm@516	2397 make a ``semantic'' sense which looks up metadata tags on
rlm@516	2398 objects in the environment the metadata tags might contain
rlm@516	2399 other sensory information.
rlm@516	2400 - Imagination via subworlds :: this would involve a creature with
rlm@516	2401 an effector which creates an entire new sub-simulation where
rlm@516	2402 the creature has direct control over placement/creation of
rlm@516	2403 objects via simulated telekinesis. The creature observes this
rlm@516	2404 sub-world through it's normal senses and uses its observations
rlm@516	2405 to make predictions about its top level world.
rlm@516	2406 - Simulated prescience :: step the simulation forward a few ticks,
rlm@516	2407 gather sensory data, then supply this data for the creature as
rlm@516	2408 one of its actual senses. The cost of prescience is slowing
rlm@516	2409 the simulation down by a factor proportional to however far
rlm@516	2410 you want the entities to see into the future. What happens
rlm@516	2411 when two evolved creatures that can each see into the future
rlm@516	2412 fight each other?
rlm@516	2413 - Swarm creatures :: Program a group of creatures that cooperate
rlm@516	2414 with each other. Because the creatures would be simulated, you
rlm@516	2415 could investigate computationally complex rules of behavior
rlm@516	2416 which still, from the group's point of view, would happen in
rlm@516	2417 ``real time''. Interactions could be as simple as cellular
rlm@516	2418 organisms communicating via flashing lights, or as complex as
rlm@516	2419 humanoids completing social tasks, etc.
rlm@516	2420 - =HACKER= for writing muscle-control programs :: Presented with
rlm@516	2421 low-level muscle control/ sense API, generate higher level
rlm@516	2422 programs for accomplishing various stated goals. Example goals
rlm@516	2423 might be "extend all your fingers" or "move your hand into the
rlm@516	2424 area with blue light" or "decrease the angle of this joint".
rlm@516	2425 It would be like Sussman's HACKER, except it would operate
rlm@516	2426 with much more data in a more realistic world. Start off with
rlm@516	2427 "calisthenics" to develop subroutines over the motor control
rlm@516	2428 API. This would be the "spinal chord" of a more intelligent
rlm@516	2429 creature. The low level programming code might be a turning
rlm@516	2430 machine that could develop programs to iterate over a "tape"
rlm@516	2431 where each entry in the tape could control recruitment of the
rlm@516	2432 fibers in a muscle.
rlm@516	2433 - Sense fusion :: There is much work to be done on sense
rlm@516	2434 integration -- building up a coherent picture of the world and
rlm@516	2435 the things in it with =CORTEX= as a base, you can explore
rlm@516	2436 concepts like self-organizing maps or cross modal clustering
rlm@516	2437 in ways that have never before been tried.
rlm@516	2438 - Inverse kinematics :: experiments in sense guided motor control
rlm@516	2439 are easy given =CORTEX='s support -- you can get right to the
rlm@516	2440 hard control problems without worrying about physics or
rlm@516	2441 senses.
rlm@516	2442
rlm@516	2443 * Empathy in a simulated worm
rlm@516	2444
rlm@516	2445 Here I develop a computational model of empathy, using =CORTEX= as a
rlm@516	2446 base. Empathy in this context is the ability to observe another
rlm@516	2447 creature and infer what sorts of sensations that creature is
rlm@516	2448 feeling. My empathy algorithm involves multiple phases. First is
rlm@516	2449 free-play, where the creature moves around and gains sensory
rlm@516	2450 experience. From this experience I construct a representation of the
rlm@516	2451 creature's sensory state space, which I call \Phi-space. Using
rlm@516	2452 \Phi-space, I construct an efficient function which takes the
rlm@516	2453 limited data that comes from observing another creature and enriches
rlm@516	2454 it full compliment of imagined sensory data. I can then use the
rlm@516	2455 imagined sensory data to recognize what the observed creature is
rlm@516	2456 doing and feeling, using straightforward embodied action predicates.
rlm@516	2457 This is all demonstrated with using a simple worm-like creature, and
rlm@516	2458 recognizing worm-actions based on limited data.
rlm@516	2459
rlm@516	2460 #+caption: Here is the worm with which we will be working.
rlm@516	2461 #+caption: It is composed of 5 segments. Each segment has a
rlm@516	2462 #+caption: pair of extensor and flexor muscles. Each of the
rlm@516	2463 #+caption: worm's four joints is a hinge joint which allows
rlm@516	2464 #+caption: about 30 degrees of rotation to either side. Each segment
rlm@516	2465 #+caption: of the worm is touch-capable and has a uniform
rlm@516	2466 #+caption: distribution of touch sensors on each of its faces.
rlm@516	2467 #+caption: Each joint has a proprioceptive sense to detect
rlm@516	2468 #+caption: relative positions. The worm segments are all the
rlm@516	2469 #+caption: same except for the first one, which has a much
rlm@516	2470 #+caption: higher weight than the others to allow for easy
rlm@516	2471 #+caption: manual motor control.
rlm@516	2472 #+name: basic-worm-view
rlm@516	2473 #+ATTR_LaTeX: :width 10cm
rlm@516	2474 [[./images/basic-worm-view.png]]
rlm@516	2475
rlm@516	2476 #+caption: Program for reading a worm from a blender file and
rlm@516	2477 #+caption: outfitting it with the senses of proprioception,
rlm@516	2478 #+caption: touch, and the ability to move, as specified in the
rlm@516	2479 #+caption: blender file.
rlm@516	2480 #+name: get-worm
rlm@516	2481 #+begin_listing clojure
rlm@516	2482 #+begin_src clojure
rlm@516	2483 (defn worm []
rlm@516	2484 (let [model (load-blender-model "Models/worm/worm.blend")]
rlm@516	2485 {:body (doto model (body!))
rlm@516	2486 :touch (touch! model)
rlm@516	2487 :proprioception (proprioception! model)
rlm@516	2488 :muscles (movement! model)}))
rlm@516	2489 #+end_src
rlm@516	2490 #+end_listing
rlm@516	2491
rlm@516	2492 ** Embodiment factors action recognition into managable parts
rlm@516	2493
rlm@516	2494 Using empathy, I divide the problem of action recognition into a
rlm@516	2495 recognition process expressed in the language of a full compliment
rlm@516	2496 of senses, and an imaganitive process that generates full sensory
rlm@516	2497 data from partial sensory data. Splitting the action recognition
rlm@516	2498 problem in this manner greatly reduces the total amount of work to
rlm@516	2499 recognize actions: The imaganitive process is mostly just matching
rlm@516	2500 previous experience, and the recognition process gets to use all
rlm@516	2501 the senses to directly describe any action.
rlm@516	2502
rlm@516	2503 ** Action recognition is easy with a full gamut of senses
rlm@516	2504
rlm@516	2505 Embodied representations using multiple senses such as touch,
rlm@516	2506 proprioception, and muscle tension turns out be be exceedingly
rlm@516	2507 efficient at describing body-centered actions. It is the ``right
rlm@516	2508 language for the job''. For example, it takes only around 5 lines
rlm@516	2509 of LISP code to describe the action of ``curling'' using embodied
rlm@516	2510 primitives. It takes about 10 lines to describe the seemingly
rlm@516	2511 complicated action of wiggling.
rlm@516	2512
rlm@516	2513 The following action predicates each take a stream of sensory
rlm@516	2514 experience, observe however much of it they desire, and decide
rlm@516	2515 whether the worm is doing the action they describe. =curled?=
rlm@516	2516 relies on proprioception, =resting?= relies on touch, =wiggling?=
rlm@516	2517 relies on a fourier analysis of muscle contraction, and
rlm@516	2518 =grand-circle?= relies on touch and reuses =curled?= as a gaurd.
rlm@516	2519
rlm@516	2520 #+caption: Program for detecting whether the worm is curled. This is the
rlm@516	2521 #+caption: simplest action predicate, because it only uses the last frame
rlm@516	2522 #+caption: of sensory experience, and only uses proprioceptive data. Even
rlm@516	2523 #+caption: this simple predicate, however, is automatically frame
rlm@516	2524 #+caption: independent and ignores vermopomorphic differences such as
rlm@516	2525 #+caption: worm textures and colors.
rlm@516	2526 #+name: curled
rlm@516	2527 #+begin_listing clojure
rlm@516	2528 #+begin_src clojure
rlm@516	2529 (defn curled?
rlm@516	2530 "Is the worm curled up?"
rlm@516	2531 [experiences]
rlm@516	2532 (every?
rlm@516	2533 (fn [[_ _ bend]]
rlm@516	2534 (> (Math/sin bend) 0.64))
rlm@516	2535 (:proprioception (peek experiences))))
rlm@516	2536 #+end_src
rlm@516	2537 #+end_listing
rlm@516	2538
rlm@516	2539 #+caption: Program for summarizing the touch information in a patch
rlm@516	2540 #+caption: of skin.
rlm@516	2541 #+name: touch-summary
rlm@516	2542 #+begin_listing clojure
rlm@516	2543 #+begin_src clojure
rlm@516	2544 (defn contact
rlm@516	2545 "Determine how much contact a particular worm segment has with
rlm@516	2546 other objects. Returns a value between 0 and 1, where 1 is full
rlm@516	2547 contact and 0 is no contact."
rlm@516	2548 [touch-region [coords contact :as touch]]
rlm@516	2549 (-> (zipmap coords contact)
rlm@516	2550 (select-keys touch-region)
rlm@516	2551 (vals)
rlm@516	2552 (#(map first %))
rlm@516	2553 (average)
rlm@516	2554 (* 10)
rlm@516	2555 (- 1)
rlm@516	2556 (Math/abs)))
rlm@516	2557 #+end_src
rlm@516	2558 #+end_listing
rlm@516	2559
rlm@516	2560
rlm@516	2561 #+caption: Program for detecting whether the worm is at rest. This program
rlm@516	2562 #+caption: uses a summary of the tactile information from the underbelly
rlm@516	2563 #+caption: of the worm, and is only true if every segment is touching the
rlm@516	2564 #+caption: floor. Note that this function contains no references to
rlm@516	2565 #+caption: proprioction at all.
rlm@516	2566 #+name: resting
rlm@516	2567 #+begin_listing clojure
rlm@516	2568 #+begin_src clojure
rlm@516	2569 (def worm-segment-bottom (rect-region [8 15] [14 22]))
rlm@516	2570
rlm@516	2571 (defn resting?
rlm@516	2572 "Is the worm resting on the ground?"
rlm@516	2573 [experiences]
rlm@516	2574 (every?
rlm@516	2575 (fn [touch-data]
rlm@516	2576 (< 0.9 (contact worm-segment-bottom touch-data)))
rlm@516	2577 (:touch (peek experiences))))
rlm@516	2578 #+end_src
rlm@516	2579 #+end_listing
rlm@516	2580
rlm@516	2581 #+caption: Program for detecting whether the worm is curled up into a
rlm@516	2582 #+caption: full circle. Here the embodied approach begins to shine, as
rlm@516	2583 #+caption: I am able to both use a previous action predicate (=curled?=)
rlm@516	2584 #+caption: as well as the direct tactile experience of the head and tail.
rlm@516	2585 #+name: grand-circle
rlm@516	2586 #+begin_listing clojure
rlm@516	2587 #+begin_src clojure
rlm@516	2588 (def worm-segment-bottom-tip (rect-region [15 15] [22 22]))
rlm@516	2589
rlm@516	2590 (def worm-segment-top-tip (rect-region [0 15] [7 22]))
rlm@516	2591
rlm@516	2592 (defn grand-circle?
rlm@516	2593 "Does the worm form a majestic circle (one end touching the other)?"
rlm@516	2594 [experiences]
rlm@516	2595 (and (curled? experiences)
rlm@516	2596 (let [worm-touch (:touch (peek experiences))
rlm@516	2597 tail-touch (worm-touch 0)
rlm@516	2598 head-touch (worm-touch 4)]
rlm@516	2599 (and (< 0.55 (contact worm-segment-bottom-tip tail-touch))
rlm@516	2600 (< 0.55 (contact worm-segment-top-tip head-touch))))))
rlm@516	2601 #+end_src
rlm@516	2602 #+end_listing
rlm@516	2603
rlm@516	2604
rlm@516	2605 #+caption: Program for detecting whether the worm has been wiggling for
rlm@516	2606 #+caption: the last few frames. It uses a fourier analysis of the muscle
rlm@516	2607 #+caption: contractions of the worm's tail to determine wiggling. This is
rlm@516	2608 #+caption: signigicant because there is no particular frame that clearly
rlm@516	2609 #+caption: indicates that the worm is wiggling --- only when multiple frames
rlm@516	2610 #+caption: are analyzed together is the wiggling revealed. Defining
rlm@516	2611 #+caption: wiggling this way also gives the worm an opportunity to learn
rlm@516	2612 #+caption: and recognize ``frustrated wiggling'', where the worm tries to
rlm@516	2613 #+caption: wiggle but can't. Frustrated wiggling is very visually different
rlm@516	2614 #+caption: from actual wiggling, but this definition gives it to us for free.
rlm@516	2615 #+name: wiggling
rlm@516	2616 #+begin_listing clojure
rlm@516	2617 #+begin_src clojure
rlm@516	2618 (defn fft [nums]
rlm@516	2619 (map
rlm@516	2620 #(.getReal %)
rlm@516	2621 (.transform
rlm@516	2622 (FastFourierTransformer. DftNormalization/STANDARD)
rlm@516	2623 (double-array nums) TransformType/FORWARD)))
rlm@516	2624
rlm@516	2625 (def indexed (partial map-indexed vector))
rlm@516	2626
rlm@516	2627 (defn max-indexed [s]
rlm@516	2628 (first (sort-by (comp - second) (indexed s))))
rlm@516	2629
rlm@516	2630 (defn wiggling?
rlm@516	2631 "Is the worm wiggling?"
rlm@516	2632 [experiences]
rlm@516	2633 (let [analysis-interval 0x40]
rlm@516	2634 (when (> (count experiences) analysis-interval)
rlm@516	2635 (let [a-flex 3
rlm@516	2636 a-ex 2
rlm@516	2637 muscle-activity
rlm@516	2638 (map :muscle (vector:last-n experiences analysis-interval))
rlm@516	2639 base-activity
rlm@516	2640 (map #(- (% a-flex) (% a-ex)) muscle-activity)]
rlm@516	2641 (= 2
rlm@516	2642 (first
rlm@516	2643 (max-indexed
rlm@516	2644 (map #(Math/abs %)
rlm@516	2645 (take 20 (fft base-activity))))))))))
rlm@516	2646 #+end_src
rlm@516	2647 #+end_listing
rlm@516	2648
rlm@516	2649 With these action predicates, I can now recognize the actions of
rlm@516	2650 the worm while it is moving under my control and I have access to
rlm@516	2651 all the worm's senses.
rlm@516	2652
rlm@516	2653 #+caption: Use the action predicates defined earlier to report on
rlm@516	2654 #+caption: what the worm is doing while in simulation.
rlm@516	2655 #+name: report-worm-activity
rlm@516	2656 #+begin_listing clojure
rlm@516	2657 #+begin_src clojure
rlm@516	2658 (defn debug-experience
rlm@516	2659 [experiences text]
rlm@516	2660 (cond
rlm@516	2661 (grand-circle? experiences) (.setText text "Grand Circle")
rlm@516	2662 (curled? experiences) (.setText text "Curled")
rlm@516	2663 (wiggling? experiences) (.setText text "Wiggling")
rlm@516	2664 (resting? experiences) (.setText text "Resting")))
rlm@516	2665 #+end_src
rlm@516	2666 #+end_listing
rlm@516	2667
rlm@516	2668 #+caption: Using =debug-experience=, the body-centered predicates
rlm@516	2669 #+caption: work together to classify the behaviour of the worm.
rlm@516	2670 #+caption: the predicates are operating with access to the worm's
rlm@516	2671 #+caption: full sensory data.
rlm@516	2672 #+name: basic-worm-view
rlm@516	2673 #+ATTR_LaTeX: :width 10cm
rlm@516	2674 [[./images/worm-identify-init.png]]
rlm@516	2675
rlm@516	2676 These action predicates satisfy the recognition requirement of an
rlm@516	2677 empathic recognition system. There is power in the simplicity of
rlm@516	2678 the action predicates. They describe their actions without getting
rlm@516	2679 confused in visual details of the worm. Each one is frame
rlm@516	2680 independent, but more than that, they are each indepent of
rlm@516	2681 irrelevant visual details of the worm and the environment. They
rlm@516	2682 will work regardless of whether the worm is a different color or
rlm@516	2683 hevaily textured, or if the environment has strange lighting.
rlm@516	2684
rlm@516	2685 The trick now is to make the action predicates work even when the
rlm@516	2686 sensory data on which they depend is absent. If I can do that, then
rlm@516	2687 I will have gained much,
rlm@516	2688
rlm@516	2689 ** \Phi-space describes the worm's experiences
rlm@516	2690
rlm@516	2691 As a first step towards building empathy, I need to gather all of
rlm@516	2692 the worm's experiences during free play. I use a simple vector to
rlm@516	2693 store all the experiences.
rlm@516	2694
rlm@516	2695 Each element of the experience vector exists in the vast space of
rlm@516	2696 all possible worm-experiences. Most of this vast space is actually
rlm@516	2697 unreachable due to physical constraints of the worm's body. For
rlm@516	2698 example, the worm's segments are connected by hinge joints that put
rlm@516	2699 a practical limit on the worm's range of motions without limiting
rlm@516	2700 its degrees of freedom. Some groupings of senses are impossible;
rlm@516	2701 the worm can not be bent into a circle so that its ends are
rlm@516	2702 touching and at the same time not also experience the sensation of
rlm@516	2703 touching itself.
rlm@516	2704
rlm@516	2705 As the worm moves around during free play and its experience vector
rlm@516	2706 grows larger, the vector begins to define a subspace which is all
rlm@516	2707 the sensations the worm can practicaly experience during normal
rlm@516	2708 operation. I call this subspace \Phi-space, short for
rlm@516	2709 physical-space. The experience vector defines a path through
rlm@516	2710 \Phi-space. This path has interesting properties that all derive
rlm@516	2711 from physical embodiment. The proprioceptive components are
rlm@516	2712 completely smooth, because in order for the worm to move from one
rlm@516	2713 position to another, it must pass through the intermediate
rlm@516	2714 positions. The path invariably forms loops as actions are repeated.
rlm@516	2715 Finally and most importantly, proprioception actually gives very
rlm@516	2716 strong inference about the other senses. For example, when the worm
rlm@516	2717 is flat, you can infer that it is touching the ground and that its
rlm@516	2718 muscles are not active, because if the muscles were active, the
rlm@516	2719 worm would be moving and would not be perfectly flat. In order to
rlm@516	2720 stay flat, the worm has to be touching the ground, or it would
rlm@516	2721 again be moving out of the flat position due to gravity. If the
rlm@516	2722 worm is positioned in such a way that it interacts with itself,
rlm@516	2723 then it is very likely to be feeling the same tactile feelings as
rlm@516	2724 the last time it was in that position, because it has the same body
rlm@516	2725 as then. If you observe multiple frames of proprioceptive data,
rlm@516	2726 then you can become increasingly confident about the exact
rlm@516	2727 activations of the worm's muscles, because it generally takes a
rlm@516	2728 unique combination of muscle contractions to transform the worm's
rlm@516	2729 body along a specific path through \Phi-space.
rlm@516	2730
rlm@516	2731 There is a simple way of taking \Phi-space and the total ordering
rlm@516	2732 provided by an experience vector and reliably infering the rest of
rlm@516	2733 the senses.
rlm@516	2734
rlm@516	2735 ** Empathy is the process of tracing though \Phi-space
rlm@516	2736
rlm@516	2737 Here is the core of a basic empathy algorithm, starting with an
rlm@516	2738 experience vector:
rlm@516	2739
rlm@516	2740 First, group the experiences into tiered proprioceptive bins. I use
rlm@516	2741 powers of 10 and 3 bins, and the smallest bin has an approximate
rlm@516	2742 size of 0.001 radians in all proprioceptive dimensions.
rlm@516	2743
rlm@516	2744 Then, given a sequence of proprioceptive input, generate a set of
rlm@516	2745 matching experience records for each input, using the tiered
rlm@516	2746 proprioceptive bins.
rlm@516	2747
rlm@516	2748 Finally, to infer sensory data, select the longest consective chain
rlm@516	2749 of experiences. Conecutive experience means that the experiences
rlm@516	2750 appear next to each other in the experience vector.
rlm@516	2751
rlm@516	2752 This algorithm has three advantages:
rlm@516	2753
rlm@516	2754 1. It's simple
rlm@516	2755
rlm@516	2756 3. It's very fast -- retrieving possible interpretations takes
rlm@516	2757 constant time. Tracing through chains of interpretations takes
rlm@516	2758 time proportional to the average number of experiences in a
rlm@516	2759 proprioceptive bin. Redundant experiences in \Phi-space can be
rlm@516	2760 merged to save computation.
rlm@516	2761
rlm@516	2762 2. It protects from wrong interpretations of transient ambiguous
rlm@516	2763 proprioceptive data. For example, if the worm is flat for just
rlm@516	2764 an instant, this flattness will not be interpreted as implying
rlm@516	2765 that the worm has its muscles relaxed, since the flattness is
rlm@516	2766 part of a longer chain which includes a distinct pattern of
rlm@516	2767 muscle activation. Markov chains or other memoryless statistical
rlm@516	2768 models that operate on individual frames may very well make this
rlm@516	2769 mistake.
rlm@516	2770
rlm@516	2771 #+caption: Program to convert an experience vector into a
rlm@516	2772 #+caption: proprioceptively binned lookup function.
rlm@516	2773 #+name: bin
rlm@516	2774 #+begin_listing clojure
rlm@516	2775 #+begin_src clojure
rlm@516	2776 (defn bin [digits]
rlm@516	2777 (fn [angles]
rlm@516	2778 (->> angles
rlm@516	2779 (flatten)
rlm@516	2780 (map (juxt #(Math/sin %) #(Math/cos %)))
rlm@516	2781 (flatten)
rlm@516	2782 (mapv #(Math/round (* % (Math/pow 10 (dec digits))))))))
rlm@516	2783
rlm@516	2784 (defn gen-phi-scan
rlm@516	2785 "Nearest-neighbors with binning. Only returns a result if
rlm@516	2786 the propriceptive data is within 10% of a previously recorded
rlm@516	2787 result in all dimensions."
rlm@516	2788 [phi-space]
rlm@516	2789 (let [bin-keys (map bin [3 2 1])
rlm@516	2790 bin-maps
rlm@516	2791 (map (fn [bin-key]
rlm@516	2792 (group-by
rlm@516	2793 (comp bin-key :proprioception phi-space)
rlm@516	2794 (range (count phi-space)))) bin-keys)
rlm@516	2795 lookups (map (fn [bin-key bin-map]
rlm@516	2796 (fn [proprio] (bin-map (bin-key proprio))))
rlm@516	2797 bin-keys bin-maps)]
rlm@516	2798 (fn lookup [proprio-data]
rlm@516	2799 (set (some #(% proprio-data) lookups)))))
rlm@516	2800 #+end_src
rlm@516	2801 #+end_listing
rlm@516	2802
rlm@516	2803 #+caption: =longest-thread= finds the longest path of consecutive
rlm@516	2804 #+caption: experiences to explain proprioceptive worm data.
rlm@516	2805 #+name: phi-space-history-scan
rlm@516	2806 #+ATTR_LaTeX: :width 10cm
rlm@516	2807 [[./images/aurellem-gray.png]]
rlm@516	2808
rlm@516	2809 =longest-thread= infers sensory data by stitching together pieces
rlm@516	2810 from previous experience. It prefers longer chains of previous
rlm@516	2811 experience to shorter ones. For example, during training the worm
rlm@516	2812 might rest on the ground for one second before it performs its
rlm@516	2813 excercises. If during recognition the worm rests on the ground for
rlm@516	2814 five seconds, =longest-thread= will accomodate this five second
rlm@516	2815 rest period by looping the one second rest chain five times.
rlm@516	2816
rlm@516	2817 =longest-thread= takes time proportinal to the average number of
rlm@516	2818 entries in a proprioceptive bin, because for each element in the
rlm@516	2819 starting bin it performes a series of set lookups in the preceeding
rlm@516	2820 bins. If the total history is limited, then this is only a constant
rlm@516	2821 multiple times the number of entries in the starting bin. This
rlm@516	2822 analysis also applies even if the action requires multiple longest
rlm@516	2823 chains -- it's still the average number of entries in a
rlm@516	2824 proprioceptive bin times the desired chain length. Because
rlm@516	2825 =longest-thread= is so efficient and simple, I can interpret
rlm@516	2826 worm-actions in real time.
rlm@516	2827
rlm@516	2828 #+caption: Program to calculate empathy by tracing though \Phi-space
rlm@516	2829 #+caption: and finding the longest (ie. most coherent) interpretation
rlm@516	2830 #+caption: of the data.
rlm@516	2831 #+name: longest-thread
rlm@516	2832 #+begin_listing clojure
rlm@516	2833 #+begin_src clojure
rlm@516	2834 (defn longest-thread
rlm@516	2835 "Find the longest thread from phi-index-sets. The index sets should
rlm@516	2836 be ordered from most recent to least recent."
rlm@516	2837 [phi-index-sets]
rlm@516	2838 (loop [result '()
rlm@516	2839 [thread-bases & remaining :as phi-index-sets] phi-index-sets]
rlm@516	2840 (if (empty? phi-index-sets)
rlm@516	2841 (vec result)
rlm@516	2842 (let [threads
rlm@516	2843 (for [thread-base thread-bases]
rlm@516	2844 (loop [thread (list thread-base)
rlm@516	2845 remaining remaining]
rlm@516	2846 (let [next-index (dec (first thread))]
rlm@516	2847 (cond (empty? remaining) thread
rlm@516	2848 (contains? (first remaining) next-index)
rlm@516	2849 (recur
rlm@516	2850 (cons next-index thread) (rest remaining))
rlm@516	2851 :else thread))))
rlm@516	2852 longest-thread
rlm@516	2853 (reduce (fn [thread-a thread-b]
rlm@516	2854 (if (> (count thread-a) (count thread-b))
rlm@516	2855 thread-a thread-b))
rlm@516	2856 '(nil)
rlm@516	2857 threads)]
rlm@516	2858 (recur (concat longest-thread result)
rlm@516	2859 (drop (count longest-thread) phi-index-sets))))))
rlm@516	2860 #+end_src
rlm@516	2861 #+end_listing
rlm@516	2862
rlm@516	2863 There is one final piece, which is to replace missing sensory data
rlm@516	2864 with a best-guess estimate. While I could fill in missing data by
rlm@516	2865 using a gradient over the closest known sensory data points,
rlm@516	2866 averages can be misleading. It is certainly possible to create an
rlm@516	2867 impossible sensory state by averaging two possible sensory states.
rlm@516	2868 Therefore, I simply replicate the most recent sensory experience to
rlm@516	2869 fill in the gaps.
rlm@516	2870
rlm@516	2871 #+caption: Fill in blanks in sensory experience by replicating the most
rlm@516	2872 #+caption: recent experience.
rlm@516	2873 #+name: infer-nils
rlm@516	2874 #+begin_listing clojure
rlm@516	2875 #+begin_src clojure
rlm@516	2876 (defn infer-nils
rlm@516	2877 "Replace nils with the next available non-nil element in the
rlm@516	2878 sequence, or barring that, 0."
rlm@516	2879 [s]
rlm@516	2880 (loop [i (dec (count s))
rlm@516	2881 v (transient s)]
rlm@516	2882 (if (zero? i) (persistent! v)
rlm@516	2883 (if-let [cur (v i)]
rlm@516	2884 (if (get v (dec i) 0)
rlm@516	2885 (recur (dec i) v)
rlm@516	2886 (recur (dec i) (assoc! v (dec i) cur)))
rlm@516	2887 (recur i (assoc! v i 0))))))
rlm@516	2888 #+end_src
rlm@516	2889 #+end_listing
rlm@516	2890
rlm@516	2891 ** Efficient action recognition with =EMPATH=
rlm@516	2892
rlm@516	2893 To use =EMPATH= with the worm, I first need to gather a set of
rlm@516	2894 experiences from the worm that includes the actions I want to
rlm@516	2895 recognize. The =generate-phi-space= program (listing
rlm@516	2896 \ref{generate-phi-space} runs the worm through a series of
rlm@516	2897 exercices and gatheres those experiences into a vector. The
rlm@516	2898 =do-all-the-things= program is a routine expressed in a simple
rlm@516	2899 muscle contraction script language for automated worm control. It
rlm@516	2900 causes the worm to rest, curl, and wiggle over about 700 frames
rlm@516	2901 (approx. 11 seconds).
rlm@516	2902
rlm@516	2903 #+caption: Program to gather the worm's experiences into a vector for
rlm@516	2904 #+caption: further processing. The =motor-control-program= line uses
rlm@516	2905 #+caption: a motor control script that causes the worm to execute a series
rlm@516	2906 #+caption: of ``exercices'' that include all the action predicates.
rlm@516	2907 #+name: generate-phi-space
rlm@516	2908 #+begin_listing clojure
rlm@516	2909 #+begin_src clojure
rlm@516	2910 (def do-all-the-things
rlm@516	2911 (concat
rlm@516	2912 curl-script
rlm@516	2913 [[300 :d-ex 40]
rlm@516	2914 [320 :d-ex 0]]
rlm@516	2915 (shift-script 280 (take 16 wiggle-script))))
rlm@516	2916
rlm@516	2917 (defn generate-phi-space []
rlm@516	2918 (let [experiences (atom [])]
rlm@516	2919 (run-world
rlm@516	2920 (apply-map
rlm@516	2921 worm-world
rlm@516	2922 (merge
rlm@516	2923 (worm-world-defaults)
rlm@516	2924 {:end-frame 700
rlm@516	2925 :motor-control
rlm@516	2926 (motor-control-program worm-muscle-labels do-all-the-things)
rlm@516	2927 :experiences experiences})))
rlm@516	2928 @experiences))
rlm@516	2929 #+end_src
rlm@516	2930 #+end_listing
rlm@516	2931
rlm@516	2932 #+caption: Use longest thread and a phi-space generated from a short
rlm@516	2933 #+caption: exercise routine to interpret actions during free play.
rlm@516	2934 #+name: empathy-debug
rlm@516	2935 #+begin_listing clojure
rlm@516	2936 #+begin_src clojure
rlm@516	2937 (defn init []
rlm@516	2938 (def phi-space (generate-phi-space))
rlm@516	2939 (def phi-scan (gen-phi-scan phi-space)))
rlm@516	2940
rlm@516	2941 (defn empathy-demonstration []
rlm@516	2942 (let [proprio (atom ())]
rlm@516	2943 (fn
rlm@516	2944 [experiences text]
rlm@516	2945 (let [phi-indices (phi-scan (:proprioception (peek experiences)))]
rlm@516	2946 (swap! proprio (partial cons phi-indices))
rlm@516	2947 (let [exp-thread (longest-thread (take 300 @proprio))
rlm@516	2948 empathy (mapv phi-space (infer-nils exp-thread))]
rlm@516	2949 (println-repl (vector:last-n exp-thread 22))
rlm@516	2950 (cond
rlm@516	2951 (grand-circle? empathy) (.setText text "Grand Circle")
rlm@516	2952 (curled? empathy) (.setText text "Curled")
rlm@516	2953 (wiggling? empathy) (.setText text "Wiggling")
rlm@516	2954 (resting? empathy) (.setText text "Resting")
rlm@516	2955 :else (.setText text "Unknown")))))))
rlm@516	2956
rlm@516	2957 (defn empathy-experiment [record]
rlm@516	2958 (.start (worm-world :experience-watch (debug-experience-phi)
rlm@516	2959 :record record :worm worm*)))
rlm@516	2960 #+end_src
rlm@516	2961 #+end_listing
rlm@516	2962
rlm@516	2963 The result of running =empathy-experiment= is that the system is
rlm@516	2964 generally able to interpret worm actions using the action-predicates
rlm@516	2965 on simulated sensory data just as well as with actual data. Figure
rlm@516	2966 \ref{empathy-debug-image} was generated using =empathy-experiment=:
rlm@516	2967
rlm@516	2968 #+caption: From only proprioceptive data, =EMPATH= was able to infer
rlm@516	2969 #+caption: the complete sensory experience and classify four poses
rlm@516	2970 #+caption: (The last panel shows a composite image of \emph{wriggling},
rlm@516	2971 #+caption: a dynamic pose.)
rlm@516	2972 #+name: empathy-debug-image
rlm@516	2973 #+ATTR_LaTeX: :width 10cm :placement [H]
rlm@516	2974 [[./images/empathy-1.png]]
rlm@516	2975
rlm@516	2976 One way to measure the performance of =EMPATH= is to compare the
rlm@516	2977 sutiability of the imagined sense experience to trigger the same
rlm@516	2978 action predicates as the real sensory experience.
rlm@516	2979
rlm@516	2980 #+caption: Determine how closely empathy approximates actual
rlm@516	2981 #+caption: sensory data.
rlm@516	2982 #+name: test-empathy-accuracy
rlm@516	2983 #+begin_listing clojure
rlm@516	2984 #+begin_src clojure
rlm@516	2985 (def worm-action-label
rlm@516	2986 (juxt grand-circle? curled? wiggling?))
rlm@516	2987
rlm@516	2988 (defn compare-empathy-with-baseline [matches]
rlm@516	2989 (let [proprio (atom ())]
rlm@516	2990 (fn
rlm@516	2991 [experiences text]
rlm@516	2992 (let [phi-indices (phi-scan (:proprioception (peek experiences)))]
rlm@516	2993 (swap! proprio (partial cons phi-indices))
rlm@516	2994 (let [exp-thread (longest-thread (take 300 @proprio))
rlm@516	2995 empathy (mapv phi-space (infer-nils exp-thread))
rlm@516	2996 experience-matches-empathy
rlm@516	2997 (= (worm-action-label experiences)
rlm@516	2998 (worm-action-label empathy))]
rlm@516	2999 (println-repl experience-matches-empathy)
rlm@516	3000 (swap! matches #(conj % experience-matches-empathy)))))))
rlm@516	3001
rlm@516	3002 (defn accuracy [v]
rlm@516	3003 (float (/ (count (filter true? v)) (count v))))
rlm@516	3004
rlm@516	3005 (defn test-empathy-accuracy []
rlm@516	3006 (let [res (atom [])]
rlm@516	3007 (run-world
rlm@516	3008 (worm-world :experience-watch
rlm@516	3009 (compare-empathy-with-baseline res)
rlm@516	3010 :worm worm*))
rlm@516	3011 (accuracy @res)))
rlm@516	3012 #+end_src
rlm@516	3013 #+end_listing
rlm@516	3014
rlm@516	3015 Running =test-empathy-accuracy= using the very short exercise
rlm@516	3016 program defined in listing \ref{generate-phi-space}, and then doing
rlm@516	3017 a similar pattern of activity manually yeilds an accuracy of around
rlm@516	3018 73%. This is based on very limited worm experience. By training the
rlm@516	3019 worm for longer, the accuracy dramatically improves.
rlm@516	3020
rlm@516	3021 #+caption: Program to generate \Phi-space using manual training.
rlm@516	3022 #+name: manual-phi-space
rlm@516	3023 #+begin_listing clojure
rlm@516	3024 #+begin_src clojure
rlm@516	3025 (defn init-interactive []
rlm@516	3026 (def phi-space
rlm@516	3027 (let [experiences (atom [])]
rlm@516	3028 (run-world
rlm@516	3029 (apply-map
rlm@516	3030 worm-world
rlm@516	3031 (merge
rlm@516	3032 (worm-world-defaults)
rlm@516	3033 {:experiences experiences})))
rlm@516	3034 @experiences))
rlm@516	3035 (def phi-scan (gen-phi-scan phi-space)))
rlm@516	3036 #+end_src
rlm@516	3037 #+end_listing
rlm@516	3038
rlm@516	3039 After about 1 minute of manual training, I was able to achieve 95%
rlm@516	3040 accuracy on manual testing of the worm using =init-interactive= and
rlm@516	3041 =test-empathy-accuracy=. The majority of errors are near the
rlm@516	3042 boundaries of transitioning from one type of action to another.
rlm@516	3043 During these transitions the exact label for the action is more open
rlm@516	3044 to interpretation, and dissaggrement between empathy and experience
rlm@516	3045 is more excusable.
rlm@516	3046
rlm@516	3047 ** Digression: bootstrapping touch using free exploration
rlm@516	3048
rlm@516	3049 In the previous section I showed how to compute actions in terms of
rlm@516	3050 body-centered predicates which relied averate touch activation of
rlm@516	3051 pre-defined regions of the worm's skin. What if, instead of recieving
rlm@516	3052 touch pre-grouped into the six faces of each worm segment, the true
rlm@516	3053 topology of the worm's skin was unknown? This is more similiar to how
rlm@516	3054 a nerve fiber bundle might be arranged. While two fibers that are
rlm@516	3055 close in a nerve bundle /might/ correspond to two touch sensors that
rlm@516	3056 are close together on the skin, the process of taking a complicated
rlm@516	3057 surface and forcing it into essentially a circle requires some cuts
rlm@516	3058 and rerragenments.
rlm@516	3059
rlm@516	3060 In this section I show how to automatically learn the skin-topology of
rlm@516	3061 a worm segment by free exploration. As the worm rolls around on the
rlm@516	3062 floor, large sections of its surface get activated. If the worm has
rlm@516	3063 stopped moving, then whatever region of skin that is touching the
rlm@516	3064 floor is probably an important region, and should be recorded.
rlm@516	3065
rlm@516	3066 #+caption: Program to detect whether the worm is in a resting state
rlm@516	3067 #+caption: with one face touching the floor.
rlm@516	3068 #+name: pure-touch
rlm@516	3069 #+begin_listing clojure
rlm@516	3070 #+begin_src clojure
rlm@516	3071 (def full-contact [(float 0.0) (float 0.1)])
rlm@516	3072
rlm@516	3073 (defn pure-touch?
rlm@516	3074 "This is worm specific code to determine if a large region of touch
rlm@516	3075 sensors is either all on or all off."
rlm@516	3076 [[coords touch :as touch-data]]
rlm@516	3077 (= (set (map first touch)) (set full-contact)))
rlm@516	3078 #+end_src
rlm@516	3079 #+end_listing
rlm@516	3080
rlm@516	3081 After collecting these important regions, there will many nearly
rlm@516	3082 similiar touch regions. While for some purposes the subtle
rlm@516	3083 differences between these regions will be important, for my
rlm@516	3084 purposes I colapse them into mostly non-overlapping sets using
rlm@516	3085 =remove-similiar= in listing \ref{remove-similiar}
rlm@516	3086
rlm@516	3087 #+caption: Program to take a lits of set of points and ``collapse them''
rlm@516	3088 #+caption: so that the remaining sets in the list are siginificantly
rlm@516	3089 #+caption: different from each other. Prefer smaller sets to larger ones.
rlm@516	3090 #+name: remove-similiar
rlm@516	3091 #+begin_listing clojure
rlm@516	3092 #+begin_src clojure
rlm@516	3093 (defn remove-similar
rlm@516	3094 [coll]
rlm@516	3095 (loop [result () coll (sort-by (comp - count) coll)]
rlm@516	3096 (if (empty? coll) result
rlm@516	3097 (let [[x & xs] coll
rlm@516	3098 c (count x)]
rlm@516	3099 (if (some
rlm@516	3100 (fn [other-set]
rlm@516	3101 (let [oc (count other-set)]
rlm@516	3102 (< (- (count (union other-set x)) c) (* oc 0.1))))
rlm@516	3103 xs)
rlm@516	3104 (recur result xs)
rlm@516	3105 (recur (cons x result) xs))))))
rlm@516	3106 #+end_src
rlm@516	3107 #+end_listing
rlm@516	3108
rlm@516	3109 Actually running this simulation is easy given =CORTEX='s facilities.
rlm@516	3110
rlm@516	3111 #+caption: Collect experiences while the worm moves around. Filter the touch
rlm@516	3112 #+caption: sensations by stable ones, collapse similiar ones together,
rlm@516	3113 #+caption: and report the regions learned.
rlm@516	3114 #+name: learn-touch
rlm@516	3115 #+begin_listing clojure
rlm@516	3116 #+begin_src clojure
rlm@516	3117 (defn learn-touch-regions []
rlm@516	3118 (let [experiences (atom [])
rlm@516	3119 world (apply-map
rlm@516	3120 worm-world
rlm@516	3121 (assoc (worm-segment-defaults)
rlm@516	3122 :experiences experiences))]
rlm@516	3123 (run-world world)
rlm@516	3124 (->>
rlm@516	3125 @experiences
rlm@516	3126 (drop 175)
rlm@516	3127 ;; access the single segment's touch data
rlm@516	3128 (map (comp first :touch))
rlm@516	3129 ;; only deal with "pure" touch data to determine surfaces
rlm@516	3130 (filter pure-touch?)
rlm@516	3131 ;; associate coordinates with touch values
rlm@516	3132 (map (partial apply zipmap))
rlm@516	3133 ;; select those regions where contact is being made
rlm@516	3134 (map (partial group-by second))
rlm@516	3135 (map #(get % full-contact))
rlm@516	3136 (map (partial map first))
rlm@516	3137 ;; remove redundant/subset regions
rlm@516	3138 (map set)
rlm@516	3139 remove-similar)))
rlm@516	3140
rlm@516	3141 (defn learn-and-view-touch-regions []
rlm@516	3142 (map view-touch-region
rlm@516	3143 (learn-touch-regions)))
rlm@516	3144 #+end_src
rlm@516	3145 #+end_listing
rlm@516	3146
rlm@516	3147 The only thing remining to define is the particular motion the worm
rlm@516	3148 must take. I accomplish this with a simple motor control program.
rlm@516	3149
rlm@516	3150 #+caption: Motor control program for making the worm roll on the ground.
rlm@516	3151 #+caption: This could also be replaced with random motion.
rlm@516	3152 #+name: worm-roll
rlm@516	3153 #+begin_listing clojure
rlm@516	3154 #+begin_src clojure
rlm@516	3155 (defn touch-kinesthetics []
rlm@516	3156 [[170 :lift-1 40]
rlm@516	3157 [190 :lift-1 19]
rlm@516	3158 [206 :lift-1 0]
rlm@516	3159
rlm@516	3160 [400 :lift-2 40]
rlm@516	3161 [410 :lift-2 0]
rlm@516	3162
rlm@516	3163 [570 :lift-2 40]
rlm@516	3164 [590 :lift-2 21]
rlm@516	3165 [606 :lift-2 0]
rlm@516	3166
rlm@516	3167 [800 :lift-1 30]
rlm@516	3168 [809 :lift-1 0]
rlm@516	3169
rlm@516	3170 [900 :roll-2 40]
rlm@516	3171 [905 :roll-2 20]
rlm@516	3172 [910 :roll-2 0]
rlm@516	3173
rlm@516	3174 [1000 :roll-2 40]
rlm@516	3175 [1005 :roll-2 20]
rlm@516	3176 [1010 :roll-2 0]
rlm@516	3177
rlm@516	3178 [1100 :roll-2 40]
rlm@516	3179 [1105 :roll-2 20]
rlm@516	3180 [1110 :roll-2 0]
rlm@516	3181 ])
rlm@516	3182 #+end_src
rlm@516	3183 #+end_listing
rlm@516	3184
rlm@516	3185
rlm@516	3186 #+caption: The small worm rolls around on the floor, driven
rlm@516	3187 #+caption: by the motor control program in listing \ref{worm-roll}.
rlm@516	3188 #+name: worm-roll
rlm@516	3189 #+ATTR_LaTeX: :width 12cm
rlm@516	3190 [[./images/worm-roll.png]]
rlm@516	3191
rlm@516	3192
rlm@516	3193 #+caption: After completing its adventures, the worm now knows
rlm@516	3194 #+caption: how its touch sensors are arranged along its skin. These
rlm@516	3195 #+caption: are the regions that were deemed important by
rlm@516	3196 #+caption: =learn-touch-regions=. Note that the worm has discovered
rlm@516	3197 #+caption: that it has six sides.
rlm@516	3198 #+name: worm-touch-map
rlm@516	3199 #+ATTR_LaTeX: :width 12cm
rlm@516	3200 [[./images/touch-learn.png]]
rlm@516	3201
rlm@516	3202 While simple, =learn-touch-regions= exploits regularities in both
rlm@516	3203 the worm's physiology and the worm's environment to correctly
rlm@516	3204 deduce that the worm has six sides. Note that =learn-touch-regions=
rlm@516	3205 would work just as well even if the worm's touch sense data were
rlm@516	3206 completely scrambled. The cross shape is just for convienence. This
rlm@516	3207 example justifies the use of pre-defined touch regions in =EMPATH=.
rlm@516	3208
rlm@516	3209 * Contributions
rlm@516	3210
rlm@516	3211 In this thesis you have seen the =CORTEX= system, a complete
rlm@516	3212 environment for creating simulated creatures. You have seen how to
rlm@516	3213 implement five senses including touch, proprioception, hearing,
rlm@516	3214 vision, and muscle tension. You have seen how to create new creatues
rlm@516	3215 using blender, a 3D modeling tool. I hope that =CORTEX= will be
rlm@516	3216 useful in further research projects. To this end I have included the
rlm@516	3217 full source to =CORTEX= along with a large suite of tests and
rlm@516	3218 examples. I have also created a user guide for =CORTEX= which is
rlm@516	3219 inculded in an appendix to this thesis.
rlm@516	3220
rlm@516	3221 You have also seen how I used =CORTEX= as a platform to attach the
rlm@516	3222 /action recognition/ problem, which is the problem of recognizing
rlm@516	3223 actions in video. You saw a simple system called =EMPATH= which
rlm@516	3224 ientifies actions by first describing actions in a body-centerd,
rlm@516	3225 rich sense language, then infering a full range of sensory
rlm@516	3226 experience from limited data using previous experience gained from
rlm@516	3227 free play.
rlm@516	3228
rlm@516	3229 As a minor digression, you also saw how I used =CORTEX= to enable a
rlm@516	3230 tiny worm to discover the topology of its skin simply by rolling on
rlm@516	3231 the ground.
rlm@516	3232
rlm@516	3233 In conclusion, the main contributions of this thesis are:
rlm@516	3234
rlm@516	3235 - =CORTEX=, a system for creating simulated creatures with rich
rlm@516	3236 senses.
rlm@516	3237 - =EMPATH=, a program for recognizing actions by imagining sensory
rlm@516	3238 experience.
rlm@516	3239
rlm@516	3240 # An anatomical joke:
rlm@516	3241 # - Training
rlm@516	3242 # - Skeletal imitation
rlm@516	3243 # - Sensory fleshing-out
rlm@516	3244 # - Classification
rlm@516	3245 #+BEGIN_LaTeX
rlm@516	3246 \appendix
rlm@516	3247 #+END_LaTeX
rlm@516	3248 * Appendix: =CORTEX= User Guide
rlm@516	3249
rlm@516	3250 Those who write a thesis should endeavor to make their code not only
rlm@516	3251 accessable, but actually useable, as a way to pay back the community
rlm@516	3252 that made the thesis possible in the first place. This thesis would
rlm@516	3253 not be possible without Free Software such as jMonkeyEngine3,
rlm@516	3254 Blender, clojure, emacs, ffmpeg, and many other tools. That is why I
rlm@516	3255 have included this user guide, in the hope that someone else might
rlm@516	3256 find =CORTEX= useful.
rlm@516	3257
rlm@516	3258 ** Obtaining =CORTEX=
rlm@516	3259
rlm@516	3260 You can get cortex from its mercurial repository at
rlm@516	3261 http://hg.bortreb.com/cortex. You may also download =CORTEX=
rlm@516	3262 releases at http://aurellem.org/cortex/releases/. As a condition of
rlm@516	3263 making this thesis, I have also provided Professor Winston the
rlm@516	3264 =CORTEX= source, and he knows how to run the demos and get started.
rlm@516	3265 You may also email me at =cortex@aurellem.org= and I may help where
rlm@516	3266 I can.
rlm@516	3267
rlm@516	3268 ** Running =CORTEX=
rlm@516	3269
rlm@516	3270 =CORTEX= comes with README and INSTALL files that will guide you
rlm@516	3271 through installation and running the test suite. In particular you
rlm@516	3272 should look at test =cortex.test= which contains test suites that
rlm@516	3273 run through all senses and multiple creatures.
rlm@516	3274
rlm@516	3275 ** Creating creatures
rlm@516	3276
rlm@516	3277 Creatures are created using /Blender/, a free 3D modeling program.
rlm@516	3278 You will need Blender version 2.6 when using the =CORTEX= included
rlm@516	3279 in this thesis. You create a =CORTEX= creature in a similiar manner
rlm@516	3280 to modeling anything in Blender, except that you also create
rlm@516	3281 several trees of empty nodes which define the creature's senses.
rlm@516	3282
rlm@516	3283 *** Mass
rlm@516	3284
rlm@516	3285 To give an object mass in =CORTEX=, add a ``mass'' metadata label
rlm@516	3286 to the object with the mass in jMonkeyEngine units. Note that
rlm@516	3287 setting the mass to 0 causes the object to be immovable.
rlm@516	3288
rlm@516	3289 *** Joints
rlm@516	3290
rlm@516	3291 Joints are created by creating an empty node named =joints= and
rlm@516	3292 then creating any number of empty child nodes to represent your
rlm@516	3293 creature's joints. The joint will automatically connect the
rlm@516	3294 closest two physical objects. It will help to set the empty node's
rlm@516	3295 display mode to ``Arrows'' so that you can clearly see the
rlm@516	3296 direction of the axes.
rlm@516	3297
rlm@516	3298 Joint nodes should have the following metadata under the ``joint''
rlm@516	3299 label:
rlm@516	3300
rlm@516	3301 #+BEGIN_SRC clojure
rlm@516	3302 ;; ONE OF the following, under the label "joint":
rlm@516	3303 {:type :point}
rlm@516	3304
rlm@516	3305 ;; OR
rlm@516	3306
rlm@516	3307 {:type :hinge
rlm@516	3308 :limit [<limit-low> <limit-high>]
rlm@516	3309 :axis (Vector3f. <x> <y> <z>)}
rlm@516	3310 ;;(:axis defaults to (Vector3f. 1 0 0) if not provided for hinge joints)
rlm@516	3311
rlm@516	3312 ;; OR
rlm@516	3313
rlm@516	3314 {:type :cone
rlm@516	3315 :limit-xz <lim-xz>
rlm@516	3316 :limit-xy <lim-xy>
rlm@516	3317 :twist <lim-twist>} ;(use XZY rotation mode in blender!)
rlm@516	3318 #+END_SRC
rlm@516	3319
rlm@516	3320 *** Eyes
rlm@516	3321
rlm@516	3322 Eyes are created by creating an empty node named =eyes= and then
rlm@516	3323 creating any number of empty child nodes to represent your
rlm@516	3324 creature's eyes.
rlm@516	3325
rlm@516	3326 Eye nodes should have the following metadata under the ``eye''
rlm@516	3327 label:
rlm@516	3328
rlm@516	3329 #+BEGIN_SRC clojure
rlm@516	3330 {:red <red-retina-definition>
rlm@516	3331 :blue <blue-retina-definition>
rlm@516	3332 :green <green-retina-definition>
rlm@516	3333 :all <all-retina-definition>
rlm@516	3334 (<0xrrggbb> <custom-retina-image>)...
rlm@516	3335 }
rlm@516	3336 #+END_SRC
rlm@516	3337
rlm@516	3338 Any of the color channels may be omitted. You may also include
rlm@516	3339 your own color selectors, and in fact :red is equivalent to
rlm@516	3340 0xFF0000 and so forth. The eye will be placed at the same position
rlm@516	3341 as the empty node and will bind to the neatest physical object.
rlm@516	3342 The eye will point outward from the X-axis of the node, and ``up''
rlm@516	3343 will be in the direction of the X-axis of the node. It will help
rlm@516	3344 to set the empty node's display mode to ``Arrows'' so that you can
rlm@516	3345 clearly see the direction of the axes.
rlm@516	3346
rlm@516	3347 Each retina file should contain white pixels whever you want to be
rlm@516	3348 sensitive to your chosen color. If you want the entire field of
rlm@516	3349 view, specify :all of 0xFFFFFF and a retinal map that is entirely
rlm@516	3350 white.
rlm@516	3351
rlm@516	3352 Here is a sample retinal map:
rlm@516	3353
rlm@516	3354 #+caption: An example retinal profile image. White pixels are
rlm@516	3355 #+caption: photo-sensitive elements. The distribution of white
rlm@516	3356 #+caption: pixels is denser in the middle and falls off at the
rlm@516	3357 #+caption: edges and is inspired by the human retina.
rlm@516	3358 #+name: retina
rlm@516	3359 #+ATTR_LaTeX: :width 7cm :placement [H]
rlm@516	3360 [[./images/retina-small.png]]
rlm@516	3361
rlm@516	3362 *** Hearing
rlm@516	3363
rlm@516	3364 Ears are created by creating an empty node named =ears= and then
rlm@516	3365 creating any number of empty child nodes to represent your
rlm@516	3366 creature's ears.
rlm@516	3367
rlm@516	3368 Ear nodes do not require any metadata.
rlm@516	3369
rlm@516	3370 The ear will bind to and follow the closest physical node.
rlm@516	3371
rlm@516	3372 *** Touch
rlm@516	3373
rlm@516	3374 Touch is handled similarly to mass. To make a particular object
rlm@516	3375 touch sensitive, add metadata of the following form under the
rlm@516	3376 object's ``touch'' metadata field:
rlm@516	3377
rlm@516	3378 #+BEGIN_EXAMPLE
rlm@516	3379 <touch-UV-map-file-name>
rlm@516	3380 #+END_EXAMPLE
rlm@516	3381
rlm@516	3382 You may also include an optional ``scale'' metadata number to
rlm@516	3383 specifiy the length of the touch feelers. The default is $0.1$,
rlm@516	3384 and this is generally sufficient.
rlm@516	3385
rlm@516	3386 The touch UV should contain white pixels for each touch sensor.
rlm@516	3387
rlm@516	3388 Here is an example touch-uv map that approximates a human finger,
rlm@516	3389 and its corresponding model.
rlm@516	3390
rlm@516	3391 #+caption: This is the tactile-sensor-profile for the upper segment
rlm@516	3392 #+caption: of a fingertip. It defines regions of high touch sensitivity
rlm@516	3393 #+caption: (where there are many white pixels) and regions of low
rlm@516	3394 #+caption: sensitivity (where white pixels are sparse).
rlm@516	3395 #+name: guide-fingertip-UV
rlm@516	3396 #+ATTR_LaTeX: :width 9cm :placement [H]
rlm@516	3397 [[./images/finger-UV.png]]
rlm@516	3398
rlm@516	3399 #+caption: The fingertip UV-image form above applied to a simple
rlm@516	3400 #+caption: model of a fingertip.
rlm@516	3401 #+name: guide-fingertip
rlm@516	3402 #+ATTR_LaTeX: :width 9cm :placement [H]
rlm@516	3403 [[./images/finger-2.png]]
rlm@516	3404
rlm@516	3405 *** Propriocepotion
rlm@516	3406
rlm@516	3407 Proprioception is tied to each joint node -- nothing special must
rlm@516	3408 be done in a blender model to enable proprioception other than
rlm@516	3409 creating joint nodes.
rlm@516	3410
rlm@516	3411 *** Muscles
rlm@516	3412
rlm@516	3413 Muscles are created by creating an empty node named =muscles= and
rlm@516	3414 then creating any number of empty child nodes to represent your
rlm@516	3415 creature's muscles.
rlm@516	3416
rlm@516	3417
rlm@516	3418 Muscle nodes should have the following metadata under the
rlm@516	3419 ``muscle'' label:
rlm@516	3420
rlm@516	3421 #+BEGIN_EXAMPLE
rlm@516	3422 <muscle-profile-file-name>
rlm@516	3423 #+END_EXAMPLE
rlm@516	3424
rlm@516	3425 Muscles should also have a ``strength'' metadata entry describing
rlm@516	3426 the muscle's total strength at full activation.
rlm@516	3427
rlm@516	3428 Muscle profiles are simple images that contain the relative amount
rlm@516	3429 of muscle power in each simulated alpha motor neuron. The width of
rlm@516	3430 the image is the total size of the motor pool, and the redness of
rlm@516	3431 each neuron is the relative power of that motor pool.
rlm@516	3432
rlm@516	3433 While the profile image can have any dimensions, only the first
rlm@516	3434 line of pixels is used to define the muscle. Here is a sample
rlm@516	3435 muscle profile image that defines a human-like muscle.
rlm@516	3436
rlm@516	3437 #+caption: A muscle profile image that describes the strengths
rlm@516	3438 #+caption: of each motor neuron in a muscle. White is weakest
rlm@516	3439 #+caption: and dark red is strongest. This particular pattern
rlm@516	3440 #+caption: has weaker motor neurons at the beginning, just
rlm@516	3441 #+caption: like human muscle.
rlm@516	3442 #+name: muscle-recruit
rlm@516	3443 #+ATTR_LaTeX: :width 7cm :placement [H]
rlm@516	3444 [[./images/basic-muscle.png]]
rlm@516	3445
rlm@516	3446 Muscles twist the nearest physical object about the muscle node's
rlm@516	3447 Z-axis. I recommend using the ``Single Arrow'' display mode for
rlm@516	3448 muscles and using the right hand rule to determine which way the
rlm@516	3449 muscle will twist. To make a segment that can twist in multiple
rlm@516	3450 directions, create multiple, differently aligned muscles.
rlm@516	3451
rlm@516	3452 ** =CORTEX= API
rlm@516	3453
rlm@516	3454 These are the some functions exposed by =CORTEX= for creating
rlm@516	3455 worlds and simulating creatures. These are in addition to
rlm@516	3456 jMonkeyEngine3's extensive library, which is documented elsewhere.
rlm@516	3457
rlm@516	3458 *** Simulation
rlm@516	3459 - =(world root-node key-map setup-fn update-fn)= :: create
rlm@516	3460 a simulation.
rlm@516	3461 - /root-node/ :: a =com.jme3.scene.Node= object which
rlm@516	3462 contains all of the objects that should be in the
rlm@516	3463 simulation.
rlm@516	3464
rlm@516	3465 - /key-map/ :: a map from strings describing keys to
rlm@516	3466 functions that should be executed whenever that key is
rlm@516	3467 pressed. the functions should take a SimpleApplication
rlm@516	3468 object and a boolean value. The SimpleApplication is the
rlm@516	3469 current simulation that is running, and the boolean is true
rlm@516	3470 if the key is being pressed, and false if it is being
rlm@516	3471 released. As an example,
rlm@516	3472 #+BEGIN_SRC clojure
rlm@516	3473 {"key-j" (fn [game value] (if value (println "key j pressed")))}
rlm@516	3474 #+END_SRC
rlm@516	3475 is a valid key-map which will cause the simulation to print
rlm@516	3476 a message whenever the 'j' key on the keyboard is pressed.
rlm@516	3477
rlm@516	3478 - /setup-fn/ :: a function that takes a =SimpleApplication=
rlm@516	3479 object. It is called once when initializing the simulation.
rlm@516	3480 Use it to create things like lights, change the gravity,
rlm@516	3481 initialize debug nodes, etc.
rlm@516	3482
rlm@516	3483 - /update-fn/ :: this function takes a =SimpleApplication=
rlm@516	3484 object and a float and is called every frame of the
rlm@516	3485 simulation. The float tells how many seconds is has been
rlm@516	3486 since the last frame was rendered, according to whatever
rlm@516	3487 clock jme is currently using. The default is to use IsoTimer
rlm@516	3488 which will result in this value always being the same.
rlm@516	3489
rlm@516	3490 - =(position-camera world position rotation)= :: set the position
rlm@516	3491 of the simulation's main camera.
rlm@516	3492
rlm@516	3493 - =(enable-debug world)= :: turn on debug wireframes for each
rlm@516	3494 simulated object.
rlm@516	3495
rlm@516	3496 - =(set-gravity world gravity)= :: set the gravity of a running
rlm@516	3497 simulation.
rlm@516	3498
rlm@516	3499 - =(box length width height & {options})= :: create a box in the
rlm@516	3500 simulation. Options is a hash map specifying texture, mass,
rlm@516	3501 etc. Possible options are =:name=, =:color=, =:mass=,
rlm@516	3502 =:friction=, =:texture=, =:material=, =:position=,
rlm@516	3503 =:rotation=, =:shape=, and =:physical?=.
rlm@516	3504
rlm@516	3505 - =(sphere radius & {options})= :: create a sphere in the simulation.
rlm@516	3506 Options are the same as in =box=.
rlm@516	3507
rlm@516	3508 - =(load-blender-model file-name)= :: create a node structure
rlm@516	3509 representing that described in a blender file.
rlm@516	3510
rlm@516	3511 - =(light-up-everything world)= :: distribute a standard compliment
rlm@516	3512 of lights throught the simulation. Should be adequate for most
rlm@516	3513 purposes.
rlm@516	3514
rlm@516	3515 - =(node-seq node)= :: return a recursuve list of the node's
rlm@516	3516 children.
rlm@516	3517
rlm@516	3518 - =(nodify name children)= :: construct a node given a node-name and
rlm@516	3519 desired children.
rlm@516	3520
rlm@516	3521 - =(add-element world element)= :: add an object to a running world
rlm@516	3522 simulation.
rlm@516	3523
rlm@516	3524 - =(set-accuracy world accuracy)= :: change the accuracy of the
rlm@516	3525 world's physics simulator.
rlm@516	3526
rlm@516	3527 - =(asset-manager)= :: get an /AssetManager/, a jMonkeyEngine
rlm@516	3528 construct that is useful for loading textures and is required
rlm@516	3529 for smooth interaction with jMonkeyEngine library functions.
rlm@516	3530
rlm@516	3531 - =(load-bullet)= :: unpack native libraries and initialize
rlm@516	3532 blender. This function is required before other world building
rlm@516	3533 functions are called.
rlm@516	3534
rlm@516	3535 *** Creature Manipulation / Import
rlm@516	3536
rlm@516	3537 - =(body! creature)= :: give the creature a physical body.
rlm@516	3538
rlm@516	3539 - =(vision! creature)= :: give the creature a sense of vision.
rlm@516	3540 Returns a list of functions which will each, when called
rlm@516	3541 during a simulation, return the vision data for the channel of
rlm@516	3542 one of the eyes. The functions are ordered depending on the
rlm@516	3543 alphabetical order of the names of the eye nodes in the
rlm@516	3544 blender file. The data returned by the functions is a vector
rlm@516	3545 containing the eye's /topology/, a vector of coordinates, and
rlm@516	3546 the eye's /data/, a vector of RGB values filtered by the eye's
rlm@516	3547 sensitivity.
rlm@516	3548
rlm@516	3549 - =(hearing! creature)= :: give the creature a sense of hearing.
rlm@516	3550 Returns a list of functions, one for each ear, that when
rlm@516	3551 called will return a frame's worth of hearing data for that
rlm@516	3552 ear. The functions are ordered depending on the alphabetical
rlm@516	3553 order of the names of the ear nodes in the blender file. The
rlm@516	3554 data returned by the functions is an array PCM encoded wav
rlm@516	3555 data.
rlm@516	3556
rlm@516	3557 - =(touch! creature)= :: give the creature a sense of touch. Returns
rlm@516	3558 a single function that must be called with the /root node/ of
rlm@516	3559 the world, and which will return a vector of /touch-data/
rlm@516	3560 one entry for each touch sensitive component, each entry of
rlm@516	3561 which contains a /topology/ that specifies the distribution of
rlm@516	3562 touch sensors, and the /data/, which is a vector of
rlm@516	3563 =[activation, length]= pairs for each touch hair.
rlm@516	3564
rlm@516	3565 - =(proprioception! creature)= :: give the creature the sense of
rlm@516	3566 proprioception. Returns a list of functions, one for each
rlm@516	3567 joint, that when called during a running simulation will
rlm@516	3568 report the =[headnig, pitch, roll]= of the joint.
rlm@516	3569
rlm@516	3570 - =(movement! creature)= :: give the creature the power of movement.
rlm@516	3571 Creates a list of functions, one for each muscle, that when
rlm@516	3572 called with an integer, will set the recruitment of that
rlm@516	3573 muscle to that integer, and will report the current power
rlm@516	3574 being exerted by the muscle. Order of muscles is determined by
rlm@516	3575 the alphabetical sort order of the names of the muscle nodes.
rlm@516	3576
rlm@516	3577 *** Visualization/Debug
rlm@516	3578
rlm@516	3579 - =(view-vision)= :: create a function that when called with a list
rlm@516	3580 of visual data returned from the functions made by =vision!=,
rlm@516	3581 will display that visual data on the screen.
rlm@516	3582
rlm@516	3583 - =(view-hearing)= :: same as =view-vision= but for hearing.
rlm@516	3584
rlm@516	3585 - =(view-touch)= :: same as =view-vision= but for touch.
rlm@516	3586
rlm@516	3587 - =(view-proprioception)= :: same as =view-vision= but for
rlm@516	3588 proprioception.
rlm@516	3589
rlm@516	3590 - =(view-movement)= :: same as =view-vision= but for
rlm@516	3591 proprioception.
rlm@516	3592
rlm@516	3593 - =(view anything)= :: =view= is a polymorphic function that allows
rlm@516	3594 you to inspect almost anything you could reasonably expect to
rlm@516	3595 be able to ``see'' in =CORTEX=.
rlm@516	3596
rlm@516	3597 - =(text anything)= :: =text= is a polymorphic function that allows
rlm@516	3598 you to convert practically anything into a text string.
rlm@516	3599
rlm@516	3600 - =(println-repl anything)= :: print messages to clojure's repl
rlm@516	3601 instead of the simulation's terminal window.
rlm@516	3602
rlm@516	3603 - =(mega-import-jme3)= :: for experimenting at the REPL. This
rlm@516	3604 function will import all jMonkeyEngine3 classes for immediate
rlm@516	3605 use.
rlm@516	3606
rlm@516	3607 - =(display-dialated-time world timer)= :: Shows the time as it is
rlm@516	3608 flowing in the simulation on a HUD display.
rlm@516	3609
rlm@516	3610
rlm@516	3611

Mercurial > cortex

annotate thesis/old-cortex.org @ 516:ced955c3c84f