.. _movements-tuto:

Movements
=========

.. _choregraphe-tuto-movement-from-scratch:

Creating a movement from scratch
--------------------------------

In Choregraphe, it is very easy to create simple movements in no time.

#. Drag and drop the **Template > Animation** box onto your diagram.

#. Double-click on the box to enter it.

   An empty timeline is displayed.

#. Select a frame by clicking in the motion section at an index different from 1.

   .. note::

      Having a keyframe at index 1 is not advised: it would mean that the robot, from an unknown position when entering the box,
	  should go to this position in no time and the keyframe would probably be ignored.

#. Click on one of the robot limbs to display the motion window.

   .. note::

      Whenever there is a current frame cursor (the blue line) on the timeline, the motion editing is on.

#. In the Motion window, you can add some joint values of the selected limb in the current keyframe,
   moving a limb will automatically add the joint value to the selected keyframe.

.. _choregraphe-tuto-movement-real-nao:

Creating a movement with a real NAO robot to define the joints values
---------------------------------------------------------------------

.. warning::

	Make sure you are connected to a real NAO.

	Head motors have to be un-enslaved, see page about enslave motor

This tutorial will explain how to use a real NAO robot to create a mouvement.

We will see how to define joints values by moving a real NAO robot.

Saving the head joints values using motion window
+++++++++++++++++++++++++++++++++++++++++++++++++

When you change the real NAO position, you can see that the virtual 3D NAO changes position too. Try to raise NAO's arm for example.

.. image:: /medias/dev/tutos/choregraphe/chore_position_reflected.jpg

Wouldn't it be nice to use this feature to create position keyframes on a motion timeline ?

Now, let’s say we want NAO to move its head up in the first keyframe and to keep its arms down:

#. Click on the first keyframe

#. Click on the head of the virtual 3D NAO to open the motion window.

#. Move the real NAO robot head to the position you want.

#. Click on the two record buttons of the motion window as in the following picture:

   .. image:: /medias/dev/tutos/choregraphe/chore_clicking_record.png

   The head joints values have been saved in the first keyframe.

Saving the arms joints values using the "Store joints in keyframe" options
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

#. Move the real NAO robot arms to put them down.

#. Click on **Enslave all on/off** in the motion window.

   The robot doesn't move.

#. Right-click on the first keyframe and select the **Store joints in keyframe** option.

   .. note::

      This feature allows you to save the joints values of NAO: the joints of the whole body, the head, the arms or the legs.

#. As we want to save the joints values of the arms, click on **Arms**.

   .. image:: /medias/dev/tutos/choregraphe/chore_store_joints.png

   The joints values of the arms have been saved in the first keyframe.

Raising the arms in a second keyframe
+++++++++++++++++++++++++++++++++++++

#. Left click the motion timeline to change the current edition frame (the blue line).

   A second keyframe is displayed on the motion timeline.

#. Move the real NAO robot arms to the position you want.

#. Click on **Enslave all on/off** in the motion window.

   The robot doesn't move.

#. Right click on the second keyframe and select **Store joints in keyframe > Arms**.

   The joints values of the arms have been saved in the second keyframe.

Thanks to the **Store joints in keyframe** option, we were able to save the values of 8 joints (4 joints per arm) in a keyframe in only a single click.

.. note::

   When you right-click on a keyframe, the **Remove joints from keyframe** option allows you to easily remove the joints values that have been saved in a keyframe.
   You can choose to remove the joints values of the whole body, or only the values of the head, arms, legs or forearms.

.. _choregraphe-tuto-recording-mode:

Creating a movement using the recording mode
--------------------------------------------

.. warning::

	Make sure you are connected to a real NAO

	Head motors have to be un-enslaved, see page about enslave motor

Now we are going to see the new recording mode, that allows you to record joints, without having to jump between the robot and the mouse!

Opening the recording mode
++++++++++++++++++++++++++

#. Drag and drop the **Templates** > **Animation** box onto your diagram.

#. Double click on it to see the timeline.

#. Open the timeline editor by clicking on the following button:

   .. image:: /medias/desktop/choregraphe/timeline_editor.png

#. Now activate the recording mode using the menu bar (**Record > Switch to recording mode**), or the toolbar by clicking on the folowing button:

   .. image:: /medias/desktop/choregraphe/recording_mode.png

   You should see two new columns in the tree on the left panel.

   .. image:: /medias/dev/tutos/choregraphe/chore_record_mode1.png

   You are now ready to record your first movement.

Recording movement
++++++++++++++++++

Let's create a new dance with arms movements.

#. In order to select the joints to record, click on the record columm in front of arms, the window should look like that:

   .. image:: /medias/dev/tutos/choregraphe/chore_record_mode2.png

#. Start the record using the menu bar (**Record > start**) or the toolbar by clicking on the folowing button:

   .. image:: /medias/desktop/choregraphe/chore_rec_start.png

#. Move the robot arms as you want and stop the recording whenever you want by clicking on the button:

   .. image:: /medias/desktop/choregraphe/chore_rec_stop.png

   You should obtain a timeline as follows:

   .. image:: /medias/dev/tutos/choregraphe/chore_record_mode3.png


Now, let's move the head accordingly to our nice arms movement.

#. Uncheck the "record" column of the arms.

#. Check the "replay" column of the arms.

#. Check the "record" column of the head.

   The window should look like that:

   .. image:: /medias/dev/tutos/choregraphe/chore_record_mode7.png

#. Enslave the arms.

   .. note::

      Enslave the arms is done in order to replay the arms movements during the recording of any movement of the head.



Now, let's change the recording mode:

#. Open the motion recorder settings using the menu bar (**Record > Settings**) or by cliking on the folowing button:

   .. image:: /medias/desktop/choregraphe/chore_rec_settings.png

#. Choose the interactive mode using bumpers.

   The robot is going to listen to its bumpers. A small panel should explain how it works.

Editing the recording
+++++++++++++++++++++

Now, you may want to edit the recording, and customize your movement.

Open the curves mode by clicking on the folowing button in the tool bar:

.. image:: /medias/desktop/choregraphe/timeline_curve_mode.png

The animation is now displayed with curves that represents the evolution of joints values for each keyframes.

.. image:: /medias/dev/tutos/choregraphe/chore_record_mode4.png

Before doing any edition, you can use the "simplify" method, that will remove useless keys from selection:

#. First, select a range of keyframes.

   .. image:: /medias/dev/tutos/choregraphe/chore_record_mode5.png

#. Click on **Simplify** button and try the default value:

   .. image:: /medias/desktop/choregraphe/chore_simplify.png

   You will see that non relevant points are now transparent: they will be deleted if you accept the simplification.

#. Click on **Close**.

   You will see that the result is a bit less frightening!
   At least, all the double keys have been removed, which make the whole movement easier to read/modify.

   .. image:: /medias/dev/tutos/choregraphe/chore_record_mode6.png

   Now, you are ready to edit the recording using all the timeline tools!

.. _choregraphe-tuto-animation-mode:

Creating a movement using animation mode
----------------------------------------

.. warning::

	Make sure you are connected to a real NAO

This tutorial will show you how to create a movement using the animation mode.

Starting from the **Init** pose of the pose library, we will animate NAO in order to put it in the position of the famous sculpture called **The thinker** by Rodin.

This movement will include legs, arms and head movements.

First, if you want more information about the animation mode see :ref:`How to use the animation mode <choregraphe-howto-use-animation-mode>` section.

If you feel ready to bring your NAO to life:

#. Enslave your NAO

   To know how to do it, see :ref:`How to enslave <choregraphe-howto-enslave>` section.

#. Put your robot into the **Init** position using the pose library.

#. Drag and drop the **Template > Animation** box.

   This box will store all the keyframes of the movement.

#. Double click on the box in order to display the timeline.

#. To edit the timeline, click on the folowing button:

   .. image:: /medias/desktop/choregraphe/timeline_editor.png

   The following window is displayed:

   .. image:: /medias/desktop/choregraphe/timeline_editor_window.png

#. Now we will select the record mode, click on the following tools button:

   .. image:: /medias/desktop/choregraphe/chore_rec_settings.png

#. Select the **Interactive using the chest button** mode, this mode will record NAO's position each time you press the chest button or say **Store position**.

#. Click on **Ok**.

#. Click on the following button to switch to the recording mode:

   .. image:: /medias/desktop/choregraphe/recording_mode.png

#. In the actuators list click on the intersection of the **record** column and the **All** row to activate the record of all actuators.

   The actuators list should look like that :

   .. image:: /medias/desktop/choregraphe/actuators_list_all.png

#. Now you are ready to start the recording of the movement, click on the following button to start the record:

   .. image:: /medias/desktop/choregraphe/chore_rec_start.png

   Don't worry no joints values are recorded until you have pushed the chest button or said **Store position** to your robot, this is the particularity of the recording mode you have choosen.

   Your robot in the **Init** pose should look like that:

   .. image:: /medias/desktop/choregraphe/animation_mode_mov1.png

   We will decompose the movement into several peaces in order to make it really simple, we will start by the leg:

#. As you enslaved your robot before, all the joints are rigid, to move legs, you will have to un-enslave it first, hold your NAO by the chest to prevent it to fall down and push the two bumpers to un-enslave legs. 

#. Lower the chest in order to flex legs, your robot should look like that:

   .. image:: /medias/desktop/choregraphe/animation_mode_mov2.png

#. Move the right foot forward and turn it a little on the right like in the following picture:

   .. image:: /medias/desktop/choregraphe/animation_mode_mov3.png

#. Enslave the legs, press the chest button to record the position.

#. The next part of the movement will involve the arms and the head of the robot, put the left arm on the left knee.

#. Un-enslave the head and lower it until it is no longer possible, tilt the chest forward, raise the right hand to the head

#. Enslave the robot and verify if the position is stable, if it is, record the position if not tilt the chest backward until the position remains stable and store the position.

   Your robot should look like that:

   .. image:: /medias/desktop/choregraphe/animation_mode_mov4.png

   The movement is finished congratulation!!!

#. To stop the record, click on the following stop record button:

   .. image:: /medias/desktop/choregraphe/chore_rec_stop.png

   You can see that all the keyframe recorded were added to the timeline.

#. To perform the animation, exit the animation box and link it to the beginning of the root behavior.

#. Click on the following play button to start the animation.

   .. note::

      If you want, you can get the .crg files here: /your intallation directory/doc/sample/choregraphe/tutorial_animation_mode.crg

You can now create outstanding movements very easily.

.. COMMENT: <presentation id="behavior_layer_1">
            <title>Getting starting with the behavior layer: basics</title>
            <para>In the <xref idref="creating_movement_from_scratch"/> tutorial, we have learned how to use motion layers and keyframes to create the Animation box (under Template). Now, we will focus on the behavior layer timeline.</para>
            <para>The behavior layers that you can find in timeline boxes allow you to create behaviors following a time-based approach and not only event-based ones. The concept is simple and quite similar to the way motion layer operates.</para>
            <subsection>
            <subtitle>Discovering the behavior layers</subtitle>
            <step>
            <item>Drag and drop the Hello box under Motions onto the diagram panel and double-click and double-click to open it.
            <result> > The timeline is displayed.</result>
            <screenshot src="medias/choregraphe/chore_tuto_dance_timeline.jpg" alt="Motion layer timeline"/>
            <result> > You can see a motion layer with keyframes on it, where the joints values are defined so that NAO can dance.</result>
            </item>
            <item>Click on the + icon next to the behavior layers pulldown menu at the top left.
            <result> > A behavior layer is displayed with a new keyframe.</result>
            <info type="note"><para>It is also possible to have more than one behavior layer on the same timeline. In this case, the behavior keyframes of the different layers will be executed in parallel. Be sure not to give contradictory orders to the same box.</para></info>
            <screenshot src="medias/choregraphe/chore_tuto_dance_various_timelines.jpg" alt="Motion and behavior layers timeline"/>
            </item>
            <item>Click on the behavior keyframe 1.
            <result>> A flow diagram zone in which you can drag and drop boxes.</result>
            <result>> In fact, the behavior you create inside a behavior keyframe will be running until another behavior keyframe is encountered.</result>
            <info type="note"><para>On a timeline, the behavior layers and the motion layers are executed in parallel.</para></info>
            </item>
            </step>
            </subsection>
            <subsection>
            <subtitle>Example</subtitle>
            <para>You would like NAO to dance and to switch on its LEDs at the same time, but you also would like to define precisely when and for how long each type of LED is switched on (face, ears and feet LEDs).</para>
            <step>

.. COMMENT: EP: Le comportement a bien changé depuis la 1.3.17, et cette doc ne marche donc plus trop... Je commente quelques gros bouts.

.. COMMENT: <item>Insert 2 new keyframes to our behavior layer.
            <screenshot src="medias/choregraphe/tuto_new_keyframes.jpg" alt="New keyframes in the behavior layer"/>
            </item>

.. COMMENT: <item>Click on keyframe 1 and drag and drop a FaceLeds box onto the flow diagram zone.</item>
            <item>Connect the FaceLeds box onStart input to the onLoad entry of the Dance box.
            <screenshot src="medias/choregraphe/chore_tuto_faceleds_connect.jpg" alt="Connecting onStart to onLoad"/>
            </item>
            <item>Click on <menu>Play</menu>.
            <result> NAO dances and switches on its face LEDs.</result>
            <info type="note"><para>Sometimes, a behavior can take a little more time than expected before it is completely executed. The reason is that, if your keyframe is too small (the lapse of time is too short), the behavior inside the keyframe will be cut or, even not executed at all.</para></info>
            </item>

.. COMMENT: <item>Click on keyframe 47 and connect the other LED boxes.
            <screenshot src="medias/choregraphe/tuto_otherconnects.jpg" alt="Connecting the LEDs at keyframe 47"/>
            <result>> If you click on <menu>Play</menu>, NAO dances and switches on its face LEDs.</result>
            <result>> Then, at keyframe 47 (after 3.1 seconds as we are currently working at 15 FPS: 47/15≈3.1), NAO switches on its other LEDs, without stopping dancing.</result>
            <info type="note"><para>You can change the FPS settings by clicking on the blue Edit button next to the timeline panel. The FPS default value is 15.</para></info>
            </item>
            <item>Click on the last keyframe of the behavior layer, the keyframe 93, and connect the LED boxes.
            <screenshot src="medias/choregraphe/tuto_otherconnects(2).jpg" alt="Connecting LEDs at keyframe 93"/>
            <result> > This keyframe behavior switches off all the LED boxes, one after the other, before stimulating the onStopped output of the Dance box.</result>
            </item>
            <item>Connect the Dance box to the main behavior entry and click on <menu>Play</menu>.
            <result> > If you are connected to a real NAO robot, you can first see NAO starting to dance (motion layer) and switch on its face LEDs at the same time (behavior keyframe1).</result>
            <result> > Then, 3.1 seconds later (behavior keyframe47 at 15 FPS), NAO switches on its other LEDs (ears and feet).</result>
            <result> > Finally, at behavior keyframe93, NAO switches off all its LEDs and stop dancing (the 4th motion keyframe on the motion layer has been reached).</result>
            </item>

.. COMMENT: </step>
            </subsection>
            </presentation>
            <presentation id="behavior_layer_2">
            <title>Getting starting with the behavior layer: Stop and GoTo</title>
            <subsection>
            <subtitle>Introduction</subtitle>
            <para>When it comes to behavior keyframes, a very important thing to understand is that the behavior you are creating inside a behavior keyframe has a limited lifetime: it will be running until another behavior keyframe is encountered and, then, the behavior in the first keyframe will be interrupted and unloaded.</para>
            <para>This statement can sound a bit frustrating but, fortunately some boxes exist in Choregraphe that allow you to juggle with the behavior keyframes in a box timeline: pause the keyframe or go to a specific keyframe.</para>
            </subsection>
            <subsection>
            <subtitle>Description of the boxes</subtitle>
            <para><table>
            <row>
            <cell><image src="medias/choregraphe/chore_stopbox.png" alt="The Stop box"/></cell>
            <cell>The Stop box has a single input entry. When this box is stimulated in a behavior keyframe, the timeline is paused. In that case, the timeline sequential logic is paused but the event logic inside the keyframe at that point continues to be executed until another timeline box is stimulated.</cell>
            </row>
            <row>
            <cell><image src="medias/choregraphe/chore_gotoandstop_box.png" alt="The gotoAndStop box"/></cell>
            <cell>The gotoAndStop box also has a single input entry. This box is used in a behavior keyframe to directly jump to a specific index (frame number) on the behavior timeline and, then, stop the timeline at this index (see how the Stop box works). Edit the box parameters to change the frame index you want to jump to.</cell>
            </row>
            <row>
            <cell><image src="medias/choregraphe/chore_gotoandplay_box.png" alt="The gotoAndPlay box"/></cell>
            <cell>The gotoAndPlay box is quite similar to the gotoAndStop box. The difference is that, once the behavior timeline has jumped to the index you have specified, this index isn’t stopped and the timeline keeps playing.</cell>
            </row>
            </table>
            </para>
            </subsection>
            <subsection>
            <subtitle>Example</subtitle>
            <step>
            <item>Drag and drop a Movement box onto the diagram panel and connect its onStart and onStopped entries respectively to the input and the output entries of the main behavior.</item>
            <item>Open the box and add a behavior layer to the timeline.</item>
            <item>On the behavior layer, insert keyframe1, keyframe40, keyframe75 and keyframe100.</item>
            <item>Click on keyframe1 and create the same box diagram as the one shown in this figure:
            <screenshot src="medias/choregraphe/chore_tuto_keyframe1.jpg" alt="Flow diagram at keyframe 1"/>
            </item>
            <item>Edit the gotoAndPlay box parameters and set the frame number to 40.</item>
            <item>Edit the gotoAndStop box parameters and set the frame number to 100.</item>
            <item>Click on keyframe40 and drag and drop a Dance box onto the diagram panel. Connect the onStart input of the Dance box to the input of behavior keyframe40.</item>
            <item>Click on keyframe75 and create the same box diagram as the one shown in the figure below:
            <screenshot src="medias/choregraphe/chore_tuto_keyframe75.jpg" alt="Flow diagram at keyframe 75"/>
            </item>
            <item>Edit the gotoAndStop box parameters and set the frame number to 1.</item>
            <item>Click on keyframe100 and drag and drop a FaceLeds box onto the diagram panel. Connect the onStart input of the Dance box to the input of behavior keyframe100 and the onStopped output of the Dance box to the output of behavior keyframe100.
            <result> > That's it, the behavior is ready to be tested.</result>
            </item>
            </step>
            </subsection>
            <subsection>
            <subtitle>Description of the Bumper box</subtitle>
            <para><image src="medias/choregraphe/chore_bumper_box.jpg" alt="The Bumper box"/></para>
            <para>The Bumper box is a sensor box. NAO has four bumper sensors, two on each feet.</para>
            <para>Double-click on the box to open its second level.</para>
            <para>
            <image src="medias/choregraphe/chore_bumper_inside.jpg" alt="Inside the Bumper box"/></para>
            <para>
            The left and right boxes represent the left and right bumpers.
            When the input entry of the Bumper box is stimulated, both boxes are loaded and wait for a signal to be stimulated: they are listening.
            The input entries of the left and right boxes are connected to ALMemory (see the <xref idref="intro_inputs_outputs"/> section). This means that the input entries of the two boxes will be stimulated every time the value subscribed to in ALMemory changes (the value is 1 or 0 depending on the bumpers position: pressed or unpressed) respecting a specific refresh period.
            Basically, when the left or right bumpers are stimulated, the left or right box detects a signal change coming from ALMemory (for example: 0,0,1,0). Then, this box stimulates its onstopped output which is linked to one of the two punctual outputs of the Bumper box.
            </para>
            <info type="note"><para>ALMemory is a NAOqi module which corresponds to NAO’s internal memory. Check NAOqi documentation for more information on ALMemory module.</para></info>
            </subsection>
            <subsection>
            <subtitle>How does it work?</subtitle>
            <step>
            <item>When you click Play, the Movement box onStart input is stimulated.
            <result> > The behavior keyframe 1 is loaded.</result>
            </item>
            <item>In the keyframe1 behavior, the Stop box and the Bumper box are stimulated. The Stop box orders the timeline to pause on keyframe 1.
            <result> > The timeline sequential logic is paused but the boxes event logic in keyframe 1 is executed: NAO is waiting for one of its two bumpers to be stimulated.</result>
            </item>
            <item>At this point, there are two possibilities for the behavior: either the left bumper is stimulated or the right one is. Let's say we push on NAO's left bumper.
            <result> > The Bumper box stimulates its left punctual output which is linked to the gotoAndPlay box.</result>
            <info type="note"><para>The top and bottom punctual outputs of the Bumper box respectively correspond to the left and right bumpers.</para></info>
            <screenshot src="medias/choregraphe/chore_GoTo.png" alt="The left bumper is stimulated"/>
            </item>
            <item>We have set the frame number of the gotoAndPlay box to 40.
            <result> > The timeline will jump to index 40 and load behavior keyframe40.</result>
            </item>
            <item>In behavior keyframe 40, the Dance box is stimulated.
            <result> > NAO starts dancing.</result>
            <screenshot src="medias/choregraphe/chore_tuto_dance40.jpg" alt="At keyframe 40, the Dance box is stimulated"/>
            </item>
            <item>We have used a gotoAndPlay box and not a gotoAndStop box to jump to index 40.
            <result> > The timeline is not stopped and keyframe75 is loaded at the end of keyframe40.</result>
            <result> > A Walk box is stimulated so that NAO starts to walk.</result>
            <result> > A Bumper box is also stimulated but, as the timeline is not paused (no Stop box is being stimulated), if the bumpers are not stimulated until the end of behavior keyframe75 on the timeline (25 frames/15 FPS=1,7 seconds), keyframe100 will be loaded and keyframe75 will be interrupted and unloaded: NAO will stop walking and the Bumper box behavior will be unloaded.</result>
            <info type="note"><para>You can change the FPS settings by clicking on the blue Edit button next to the timeline panel. The FPS default value is 10.</para></info>
            </item>
            <item>On the contrary, if the bumpers in keyframe 75 are stimulated before keyframe 100 is loaded, two things can happen.
            <result> > If the left bumper is stimulated, the main behavior will be stopped (the left punctual output is connected to the onStopped entry of Movement).</result>
            <result> > If the right bumper is stimulated, the gotoAndStop is stimulated and the timeline is ordered to jump to index 1. The keyframe1 is loaded and the timeline is paused once again.</result>
            <screenshot src="medias/choregraphe/chore_bumper.png" alt="Left or right bumper is stimulated"/>
            </item>
            <item>Now, let’s say that the bumpers have not been stimulated before the end of behavior 75 on the timeline.
            <result> > Keyframe100 is now loaded and FaceLeds is stimulated: NAO switches on the LEDs of its face.</result>
            <result> > Then, the onStopped entry of Movement is stimulated: the main behavior is stopped.</result>
            <screenshot src="medias/choregraphe/chore_tuto_faceled_stimul.jpg" alt="FaceLED is stimulated at keyframe100"/>
            </item>
            <item>Let’s go back to the beginning of our behavior at keyframe 1 and let’s say we click on NAO’s right bumper instead of the left one.
            <screenshot src="medias/choregraphe/chore_GoTo2.png" alt="The right bumper is stimulated"/>
            <result> > The gotoAndStop box is stimulated and the timeline is ordered to jump to index 100 and pause.</result>
            <result> > Behavior keyframe 100 is loaded.</result>
            </item>
            <item>The Face LEDs are switched on.
            <result> > The onStopped entry of Movement is stimulated: the main behavior is stopped.</result>
            <info type="note"><para>We could have jumped to index 100 with gotoAndPlay instead of gotoAndStop. This would not have changed the fact that the onStopped entry is stimulated at the end of behavior keyframe100: the main behavior will have stopped anyway.</para></info>
            </item>
            </step>
            </subsection>
            </presentation>