#+title: Simulated Muscles

 #+author: Robert McIntyre

 #+email: rlm@mit.edu

 #+description: muscles for a simulated creature

 #+keywords: simulation, jMonkeyEngine3, clojure

 #+SETUPFILE: ../../aurellem/org/setup.org

 #+INCLUDE: ../../aurellem/org/level-0.org

 

 

 * Muscles

 

 Surprisingly enough, terristerial creatures only move by using torque

 applied about their joints.  There's not a single straight line of

 force in the human body at all!  (A straight line of force would

 correspond to some sort of jet or rocket propulsion.)

 

 *(next paragraph is from memory and needs to be checked!)*

 

 In humans, muscles are composed of millions of sarcomeres, which can

 contract to exert force. A single motor neuron might control 100-1,000

 sarcomeres. When the motor neuron is engaged by the brain, it

 activates all of the sarcomeres to which it is attached. Some motor

 neurons command many sarcomeres, and some command only a few. The

 spinal cord generally engages the motor neurons which control few

 sarcomeres before the motor neurons which control many sarcomeres.

 This recruitment stragety allows for percise movements at low

 strength. The collection of all motor neurons that control a muscle is

 called the motor pool. The brain essentially says "activate 30% of the

 motor pool" and the spinal cord recruits motor neurons untill 30% are

 activated. Since the distribution of power among motor neurons is

 unequal and recruitment goes from weakest to strongest, the first 30%

 of the motor pool might be 5% of the strength of the muscle.

 

 My simulated muscles follow a similiar design: Each muscle is defined

 by a 1-D array of numbers (the "motor pool"). Each entry in the array

 represents a motor neuron which controlls a number of sarcomeres equal

 to the value of the entry. A muscle also has a scalar :strength factor

 which determines the total force the muscle can exert when all motor

 neurons are activated.  The effector function for a muscle takes a

 number to index into the motor pool, and that number "activates" all

 the motor neurons whose index is lower or equal to the number.  Each

 motor-neuron will apply force in proportion to its value in the array.

 Lower values cause less force.  The lower values can be put at the

 "beginning" of the 1-D array to simulate the layout of actual human

 muscles, which are capable of more percise movements when exerting

 less force. Or, the motor pool can simulate more exoitic recruitment

 strageties which do not correspond to human muscles.

 

 This 1D array is defined in an image file for ease of

 creation/visualization. Here is an example muscle profile image.

 

 #+caption: A muscle profile image that describes the strengths of each motor neuron in a muscle. White is weakest and dark red is strongest. This particular pattern has weaker motor neurons at the beginning, just like human muscle.

 [[../images/basic-muscle.png]]

 

 * Blender Meta-data

 

 In blender, each muscle is an empty node whose top level parent is

 named "muscles", just like eyes, ears, and joints.

 

 These functions define the expected meta-data for a muscle node.

 

 #+name: muscle-meta-data

 #+begin_src clojure 

 (in-ns 'cortex.movement)

 

 (defvar 

   ^{:arglists '([creature])}

   muscles

   (sense-nodes "muscles")

   "Return the children of the creature's \"muscles\" node.")

 

 (defn muscle-profile-image

   "Get the muscle-profile image from the node's blender meta-data."

   [#^Node muscle]

   (if-let [image (meta-data muscle "muscle")]

     (load-image image)))

 

 (defn muscle-strength

   "Return the strength of this muscle, or 1 if it is not defined."

   [#^Node muscle]

   (if-let [strength (meta-data muscle "strength")]

     strength 1))

 

 (defn motor-pool

   "Return a vector where each entry is the strength of the \"motor

    neuron\" at that part in the muscle."

   [#^Node muscle]

   (let [profile (muscle-profile-image muscle)]

     (vec

      (let [width (.getWidth profile)]

        (for [x (range width)]

        (- 255

           (bit-and

            0x0000FF

            (.getRGB profile x 0))))))))

 #+end_src

 

 Of note here is =(motor-pool)= which interprets the muscle-profile

 image in a way that allows me to use gradients between white and red,

 instead of shades of gray as I've been using for all the other

 senses. This is purely an aesthetic touch.

 

 * Creating Muscles

 #+name: muscle-kernel

 #+begin_src clojure

 (in-ns 'cortex.movement)

 

 (defn movement-kernel

   "Returns a function which when called with a integer value inside a

    running simulation will cause movement in the creature according

    to the muscle's position and strength profile. Each function

    returns the amount of force applied / max force."

   [#^Node creature #^Node muscle]

   (let [target (closest-node creature muscle)

         axis

         (.mult (.getWorldRotation muscle) Vector3f/UNIT_Y)

         strength (muscle-strength muscle)

         

         pool (motor-pool muscle)

         pool-integral (reductions + pool)

         force-index

         (vec (map  #(float (* strength (/ % (last pool-integral))))

               pool-integral))

         control (.getControl target RigidBodyControl)]

     (fn [n]

       (let [pool-index (max 0 (min n (dec (count pool))))

             force (force-index pool-index)]

         (.applyTorque control (.mult axis force))

         (float (/ force strength))))))

 

 (defn movement!

   "Endow the creature with the power of movement. Returns a sequence

    of functions, each of which accept an integer value and will

    activate their corresponding muscle."

   [#^Node creature]

     (for [muscle (muscles creature)]

       (movement-kernel creature muscle)))

 #+end_src

 

 =(movement-kernel)= creates a function that will move the nearest

 physical object to the muscle node. The muscle exerts a rotational

 force dependant on it's orientation to the object in the blender

 file. The function returned by =(movement-kernel)= is also a sense

 function: it returns the percent of the total muscle strength that is

 currently being employed. This is analogous to muscle tension in

 humans and completes the sense of proprioception begun in the last

 post. 

 

 * Visualizing Muscle Tension

 Muscle exertion is a percent of a total, so the visulazation is just a

 simple percent bar.

 

 #+name: visualization

 #+begin_src clojure

 (defn movement-display-kernel

   "Display muscle exertion data as a bar filling up with red."

   [exertion]

      (let [height 20

            width 300

            image (BufferedImage. width height

                                  BufferedImage/TYPE_INT_RGB)

            fill (min (int (* width exertion)) width)]

        (dorun

         (for [x (range fill)

               y (range height)]

           (.setRGB image x y 0xFF0000)))

        image))

 

 (defn view-movement

   "Creates a function which accepts a list of muscle-exertion data and

   displays each element of the list to the screen."

   []

   (view-sense movement-display-kernel))

 #+end_src

 

 * Adding Touch to the Worm

 

 #+begin_src clojure

 (defn test-movement

   ([] (test-movement false))

   ([record?]

      (let [creature (doto (worm) (body!))

 

            muscle-exertion (atom 0)

            muscles (movement! creature)

            muscle-display (view-movement)]

        (.setMass

         (.getControl (.getChild creature "worm-11") RigidBodyControl)

         (float 0))

        (world

         (nodify [creature (floor)])

         (merge standard-debug-controls

                {"key-h"

                 (fn [_ value]

                   (if value

                     (swap!  muscle-exertion (partial + 20))))

                 "key-n"

                 (fn [_ value]

                   (if value

                     (swap! muscle-exertion (fn [v] (- v 20)))))})

         (fn [world]

           (if record?

             (Capture/captureVideo

              world

              (File. "/home/r/proj/cortex/render/worm-muscles/main-view")))

           (light-up-everything world)

           (enable-debug world)

           (.setTimer world (RatchetTimer. 60))

           (set-gravity world (Vector3f. 0 0 0))

           (.setLocation (.getCamera world)

                         (Vector3f. -4.912815, 2.004171, 0.15710819))

           (.setRotation (.getCamera world)

                         (Quaternion. 0.13828252, 0.65516764, 

                                      -0.12370994, 0.7323449))

 

           (comment 

             (com.aurellem.capture.Capture/captureVideo

              world (file-str "/home/r/proj/ai-videos/hand"))))

         (fn [world tpf]

           (muscle-display

            (map #(% @muscle-exertion) muscles)

            (if record?

              (File. "/home/r/proj/cortex/render/worm-muscles/muscles"))))))))

 #+end_src

 

 * Video Demonstration 

 

 #+begin_html

 <div class="figure">

 <center>

 <video controls="controls" width="550">

   <source src="../video/worm-muscles.ogg" type="video/ogg"

 	  preload="none" poster="../images/aurellem-1280x480.png" />

 </video>

 </center>

 <p>The worm is now able to move. The bar in the lower right displays

   the power output of the muscle . Each jump causes 20 more motor neurons to

   be recruited.  Notice that the power output increases non-linearly

   with motror neuron recruitement, similiar to a human muscle.</p>

 </div>

 #+end_html

 

 

 ** Making the Worm Muscles Video

 #+name: magick7

 #+begin_src clojure

 (ns cortex.video.magick7

   (:import java.io.File)

   (:use clojure.contrib.shell-out))

 

 (defn images [path]

   (sort (rest (file-seq (File. path)))))

 

 (def base "/home/r/proj/cortex/render/worm-muscles/")

 

 (defn pics [file]

   (images (str base file)))

 

 (defn combine-images []

   (let [main-view (pics "main-view")

         muscles (pics "muscles/0")

         targets (map

                  #(File. (str base "out/" (format "%07d.png" %)))

                  (range 0 (count main-view)))]

     (dorun

      (pmap

       (comp

        (fn [[ main-view muscles target]]

          (println target)

          (sh "convert"

              main-view 

              muscles "-geometry" "+320+440" "-composite"

              target))

        (fn [& args] (map #(.getCanonicalPath %) args)))

        main-view muscles targets))))

 #+end_src

 

 #+begin_src sh :results silent

 cd ~/proj/cortex/render/worm-muscles

 ffmpeg -r 60 -i out/%07d.png -b:v 9000k -c:v libtheora worm-muscles.ogg

 #+end_src

 

 * Headers

 #+name: muscle-header

 #+begin_src clojure

 (ns cortex.movement

   "Give simulated creatures defined in special blender files the power

    to move around in a simulated environment."

   {:author "Robert McIntyre"}

   (:use (cortex world util sense body))

   (:use clojure.contrib.def)

   (:import java.awt.image.BufferedImage)

   (:import com.jme3.scene.Node)

   (:import com.jme3.math.Vector3f)

   (:import com.jme3.bullet.control.RigidBodyControl))

 #+end_src

 

 #+name: test-header

 #+begin_src clojure

 (ns cortex.test.movement

   (:use (cortex world util sense body movement))

   (:use cortex.test.body)

   (:use clojure.contrib.def)

   (:import java.io.File)

   (:import java.awt.image.BufferedImage)

   (:import com.jme3.scene.Node)

   (:import com.jme3.math.Vector3f)

   (:import (com.aurellem.capture Capture RatchetTimer))

   (:import com.jme3.bullet.control.RigidBodyControl))

 

 (cortex.import/mega-import-jme3)

 #+end_src

 

 * Source Listing

   - [[../src/cortex/movement.clj][cortex.movement]]

   - [[../src/cortex/test/movement.clj][cortex.test.movement]]

   - [[../src/cortex/video/magick7.clj][cortex.video.magick7]]

 #+html: <ul> <li> <a href="../org/movement.org">This org file</a> </li> </ul>

   - [[http://hg.bortreb.com ][source-repository]]

 

 * COMMENT code generation

 #+begin_src clojure :tangle ../src/cortex/movement.clj

 <<muscle-header>>

 <<muscle-meta-data>>

 <<muscle-kernel>>

 <<visualization>>

 #+end_src

 

 #+begin_src clojure :tangle ../src/cortex/test/movement.clj

 <<test-header>>

 <<test-movement>>

 #+end_src

 

 #+begin_src clojure :tangle ../src/cortex/video/magick7.clj

 <<magick7>>

 #+end_src