This page is a tutorial to help you in beginning to use the HuMAnS
toolbox. The main idea is also to explain what is done and how, giving
you a complete understanding of the software architecture. This way it
should be easier for you to see how to make your own applications. Lines
of code will be given, and when you want to know what a script or a
function does, click on its name to be directed to a page dedicated to
it. At first, the descriptions might not be very detailed, but new
tutorials should be added later to make them more precise. When a
function is explained, the full source code of the function will
probably not be given. You might find useful therefore to have a text
editor ready to read at will the corresponding source file.
Maybe a few words about the general architecture of the software before
starting, even if this is already detailed in the User Documentation. A
necessary module for all uses of the toolbox is the Kernel module/directory: of interest to
this Tutorial, it contains the Simulation
function and calls to functions updating the state of the contacts and
of the actuators. The mechanical model is defined in the LagrangianModel/*Name* module/directory.
module/directory concerns everything about the actuation: a model of the
actuators and of the control laws which can be applied. The LagrangianDynamics/*Name* module/directory
handles the way the dynamics will be computed, dealing with contact
forces and all other forces acting on the system.
What is needed
- It is assumed that you installed the HuMAnS toolbox and that it
works correctly (be sure that the different scripts described in the
README file work).
- To have an idea of the problems that can be solved by this
toolbox, a first glance at the User Documentation is strongly
advised if you haven't done so yet, at least sections 1.1 and 2.1 to
know in general what kind of problems are modeled and how they are
- It is assumed that you know how to use Scilab properly.
- A VRML viewer compatible with the H-Anim format can be useful,
but is not mandatory.
We are going to detail here a very simple application: we are going to
define a simple trajectory and apply it to an existing model (the human
biomechanical model called Human36, because of its 36 axes of rotation).
The trajectory will be defined later. Here we go:
Open a new Scilab script ('Tutorial.sci' for example), read and copy the
lines given in the next section. Another file will have to be modified:
please pay attention to the comments, which will give you directions to
Let's do some coding
// You always need to execute the KickStart first,
// then load the modules that will be used in your application
// Definition of the period (in seconds) with which the Spy function will
// be called (to check the evolution of the simulation)
SpyPeriod = 1e-1;
// Choice of the trajectory that will be used.
// The function Trajectory has to be
modified in this case,
// following the guidelines given here. In
a few words,
// a new trajectory name is defined so as not to lose the other existing
// trajectories defined in the rest of the function Trajectory
TrajectoryName = 'ArmMovement';
[q, qdot] = Trajectory(0);
// As its name says, this function realizes the simulation.
// This function is also detailed in chapter 5 of the User Documentation.
[T, Q, QDOT, Z, ACTUATIONSTATE, CONTACTSTATE] =
Simulation(0, 1, 1e-2, q, qdot);
// Now the simulation is finished and the rest of the program
// is devoted to the "analysis" of its results.
// Contact forces are computed here.
printf('\nComputing Contact Forces...\n');
ComputeContactForces(T, Q, QDOT, Z, ACTUATIONSTATE, CONTACTSTATE);
// Here the joint positions and the contact forces are plotted with regular
// Scilab functions
// This is to generate a VRML 3D animation of the simulation
printf('Creation of a VRML file...\n);
CreateVRML(1e-2, Q, HAnimJointsNames, 'Human36', 'High', 'Tutorial.wrl', LAMBDA, HAnimContactSolidsNames, HAnimContactSolidsRGB);
// This is to generate the plain Scilab stick figure 3D animation of the simulation
Visu(Q(:, 1:10:$), LAMBDA(:, 1:10:$));
Running the script
Now execute this script in Scilab and watch the result. If you get an
error message saying that 'position variable is undefined', it
probably means that you haven't read that.
Otherwise you should see a 3D stick figure moving the right arm up and
down. If a VRML viewer is installed on your computer, you can watch a
much nicer animation in the 'Tutorial.wrl' file. This application is
very simple because we did not use any specific model of actuators and
there is no change in the contact state, furthermore the joint
trajectory given here presents no change in the actuation state either.