cortex: thesis/cortex.org annotate

annotate thesis/cortex.org @ 530:21b8389922ee

fix vermopomorphic footnote.

author	Robert McIntyre <rlm@mit.edu>
date	Sat, 26 Apr 2014 19:36:13 -0400
parents	96c189d4d15e
children	749452f063e5

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

Mercurial > cortex

annotate thesis/cortex.org @ 530:21b8389922ee