1) *** What is HuManS / HuMAnS Web Site *** HuManS is a Scilab toolbox for Humanoid Motion Analysis and Simulation. More informations can be found at the following web site : http://bipop.inrialpes.fr/software/humans/index.html 2) *** Who develops HuMAnS *** HuMAnS is mainly developped by the HuMAnS development team at the INRIA Rhone-Alpes. It can be reached at the following email adress, humans-devel@inrialpes.fr. Contributors are warmly welcomed. 3) *** Software Licence *** This program is Copyright (C) INRIA 1999-2005. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. We would prefer however that any interested person asks for this software directly by email to humans-devel@inrialpes.fr. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. See Licence.txt or Licence.html for more details. 4) *** Requirements *** * fsqp 1.2 * Scilab 4.0 * Doxygen 1.3.9 (if you generate source code documentation) 5) *** How to compile and install on Unix Systems (Linux, MacOs) *** * - Linux - set SCIDIR to scilab directory in the MakefileSys file If SCIDIR is not set, the default directory is /usr/lib/scilab-4.0 - Mac - in your environment you have three variables to set MACOSX_DEPLOYMENT_TARGET 10.3 SCI /Applications/Scilab.app/Contents/Resources/scilab-4.0 SCIDIR /Applications/Scilab.app/Contents/Resources/scilab-4.0 Of course adapt the path accordingly to the location of your Scilab software * compile fsqp fsqp will be not in the next release > cd Kernel/OptimizationTools/ > make all * compile HuMAnS > cd ../.. > make all * Doxygen documentation > make doc see Documentation/Doxygen/html/index.html NOTE: For doxygen documentation, you need the 'scitoc' pre-processor located on Documentation/bin(Windows|Linux|Darwin). Do not forget to add this location in the variable PATH. For the moment, only Linux is supported. 6) *** How to compile and install on Windows XP Systems *** * set SCIDIR to scilab directory in the Makefile.mak If SCIDIR is not set, the default dir is c:\Program Files\scilab-4.0 * set variable of compilation (if Makefile compilation is used) > Documentation\vsvars32.bat * compile fsqp fsqp will be not in the next release > cd Kernel\OptimizationTools\ > nmake -f Makefile.mak * compile HuMAnS with Makefile > cd ..\.. > nmake -f Makefile.mak or with visual .NET > open the project Humans and launch 'Build Solution' 7) *** How to use the sample Applications and what they are supposed to do *** Launch Scilab then... > exec BipOneStep.sci; * This sample application shows the Bip robot performing dynamically a statically stable step with the help of a task function control law. This simulated experiment starts and ends in a position where the robot is hanging safely from the ceiling. > exec FESSitToStand.sci; * This sample application shows a tentative stand-up with quadriceps stimulated at their maximum (and their resultant force multiplied by a factor of 10). The hips are dynamically constrained so that the center of mass always lies between the ankles for static stability. Note that this last condition implies a nearly horizontal position of the trunk. This simulation stops at a singularity. May not be continued and may be replaced by ChairSitToStand.sci. > exec FESSwingUp.sci; * This sample application shows the effect of an alternation of contractions of both quadriceps and both hamstrings when the human's position is completely rigid except for the right knee. > exec FESForceMeasurement.sci; * This sample application starts a series of simulations with varying stimulation frequencies of the quadriceps and measures the resulting contraction forces. > exec ChairSitToStand.sci; * This sample application shows a person balancing on a chair, with contacts of the feet on the ground and of the hips on the chair. It uses a NoDynamics ActuationModel with a ComputedTorque control law. Note that the center of pressure on the ground (sometimes called the ZMP) goes outside of the vertical projection of the contact points on the ground, what is normal considering the different heights of these contact points. > exec SpaceWalk.sci; * This sample application shows a person performing walking movements in space, that is without gravity and without contacts. The conservation of the translation momentum implies that the center of mass of the person doesn't move, but the conservation of the rotation momentum doesn't imply that the body doesn't rotate. This is because of the non-holonomy of this latter conservation law. It is this non-holonomy which is used by cats in order to always fall back on their legs. > exec HRP2Demo.sci; * Be careful: to run this sample application, you need to be allowed to manipulate the HRP2 model. If it's the case, send an email to humans-devel@inrialpes.fr to obtain the HRP2 Lagrangian Model. * This sample application shows the HRP2 robot grabbing something down and putting it up on a shelf. The trajectory is an interpolation between keyframes generated by Jacadi, tracked with the ComputedTorqueControl of the NoDynamics ActuationModel. A tentative and not so good TaskFunction is proposed for the interpolation: try Visu(InverseTaskFunction(TaskFunction(q1))) to see why it's not so good. Note also that the Jacadi posture generation tool is not as reliable here as it is with Bip: more degrees of freedom, more constraints make more local minima and harder convergence. There's room for improvement here. > exec PA10Infinity.sci; * This sample application shows the PA10 robot going over the "infinity" trajectory (which is the lemniscat of Bernouilli). The PA10 center of wrist must remain on this trajectory and the device orientation must remain constant. > exec RX90Circle.sci; * This sample application shows the RX90 robot going over a circle. The RX90 center of wrist must remain on this trajectory and its device orientation must remain constant. 8) *** What's new in version 1.0.6 *** - The bug in the dynamic model of the PA10 robot has been removed. - A Staubli RX90 model has been added in the LagrangianModel directory. - An ActuationDynamics/NoDynamics/TaskFunctionControl module has been added in order to control the movement of the robotics arms in the task space. Two modules PA10TaskFunctionDefinition and RX90TaskFunctionDefinition have been added to define the task function of respectively the PA10 and RX90 robots. Two sample applications which use these modules have been added. The PA10Infinity.sci application simulates the movement of a PA10 which wrist must go over the lemniscat of Bernoulli and which device orientation must remain constant. The RX90Circle.sci sample application simulates the mouvement of a RX90 robot whch wrist must go over a circle and which device must remain in the same orientation. - The bug of the Human36 model wasn't a bug of a model. During the simulation which throughs the problem, the model reaches a singularity position and then the simulation diverge. Then the model has no bug. - The Human27 model of the Reconstruction module has been replaced with the Human36 model. - The Reconstruction from optical sensors has been reorganized. An interface is now created when the user launch the MenuReconstruction.sci file. The reconstruction has been adapted to the Human36 model and some fonctionnalities has been added. More documentation about these fonctionnalities will be available in the next version. - the Visual C++ Project has been updated. *** What's new in version 1.0.5 *** - A biomechanical model with 42 degrees of freedom has been realized and put in the LagrangianModel directory. See the UserDocumentation manual for more informations about it. - A Mitsubishi PA10 model was set in the LagrangianModel directory. - The Reconstruction module has been improved (for more informations, see the HuMAnS/Documentation/UserDocumentation.pdf manual): - The Human27 model has sizible anatomical lengths and variables tags positions in their attached segments. The way to set and get these lengths and positions is explained in the UserDocumentation manual. - In the reconstruction from optical sensors, the following changes were made: - a new script exists: the AllSubjectsTrajectoriesReconstruction.sci script which allows the user to automate the treatment of the optotrack data. See the UserDocumentation manual to have more informations. - in the ConvertFromCsvToTags.sci function, the following additions were made: - the occulted led positions can be interpolated; - the led positions data can be filtered before or after this interpolation; - New Optotrack measures were added in the OpticalSensors/Measures directory and reorganizations in OpticalSensors/Measures and OpticalSensors/resultsMeasures have been made. - The user can now create the vrml file for the visualization of the human movement and of the measured leds positions. In this version, the size of the human isn't sizible, then the human model doesn't correspond to the measured leds position. This will be resolved in the next version. The generated vrml file is placed in the OpticalSensor directory. - In the reconstruction from inertial sensors, two functions (SetISOrientations(UserOrientations) and GetISOrientations()) allows the user to set and get the inertial sensors orientations relative to the frames of the segment at which they are attached. Then the Definitions.sci file has been removed. - The User Documentation has been improved with the documentation for the reconstruction, the Human36 model and for the Lagrangian model construction. - Windows Visual .NET compilation is debugged. *** What's new in version 1.0.4 *** - The MapleCodeGeneration of the Human and Bip LagrangianModels has been improved: the generation of the Inertia and NLEffects is faster and more efficient. - Evolution of the Jacadi Tool for less Bip-centricity and of the ComputedTorqueControl of the NoDynamics ActuationModel for less Human-centricity. Note that doing so, some interfaces of these functions have slightly changed. - Added a HRP2Demo sample application together with a LagrangianModel of the HRP2 robot, but with restricted access only. * Improved Documentation -Parts of the Documentation have been included in the Documentation/User repertory. Open the UserDocumentation.pdf or the UserDocumentation.ps to see it. This documentation is under construction, it will be completed soon. * VRML Visualization enhancement - The generation of the HAnim Visualization of the Bip and Human LagrangianModel has been reworked for speed and simplicity. - Futhermore, now the vrml file shows the different contact forces and their sum. The models can be tranparents in order to better visualize these forces. The scilab function which allows to generate the VRML File corresponding to the simulation is the CreateVRML function. It's parameters are: - The simulation time sampling; - The simulation position matrix Q; - The HAnimJointsNames variable; - The Name of the model ('Bip' or 'Human' or 'HRP2'); - The Resolution of the model ('High' for Bip and HRP2 and 'Low' for Human); - The name of the output file (which will be set in HuMAnS repertory); - The choice for the transparency(0=no transparency, 1=transparency); - The matrix LAMBDA containing the forces for all the simulation; - The name of the differents contact solids (in the HAnimContactSolidsNames variable); - and the RGB information to set the colors of the differents arrows representing the forces (HAnimContactSolidsRGB variable). The HAnimJointsNames, HAnimContactSolidsNames and HAnimContactSolidsRGB variables are defined in the SomeDefinitions.sci files in the LagrangianModel/NameOfModel/ repertories. * Visual .Net Projects -The Visual Projects have been reworked to update old projects and add new projects(JacadiModel and Human27Reconstruction). The build process works now fine. * Bugs -The scilab visualization (Visu functions) has been reworked in order to use the new graphic mode of the 3.1.1 version of scilab. The visualization bug in windows has been removed. Now you can rotate and replay the simulation(with the added "replay" button in the menu bar of the graphic window). -The reconstruction module has been debbuged for windows. Now the old script script.sh(in the Tools/Reconstruction/OpticalSensors/Measures repertory) is unused and then has been removed and the results of the reconstruction(that is to say the reconstructed positions) are saved in binary files. *** What's new in version 1.0.3 *** * Reconstruction A Reconstruction module has been added in Tools repertory. It reconstruct positions or trajectories from optical or inertial sensors. The optical sensors measure the positions of tags placed on a human. The inertial ones measure their acceleration and the magnetic field at their position and so those of the body segments at which they are attached. Optical measures have been made with optotrak, and the StaticAllTrajectoriesReconstruction application reconstruct all measured trajectories. The reconstruction from optical sensors is static in the way that all successive positions are considered as statics. The one from inertial sensors can be static or a draft of dynamics reconstruction. In order to execute reconstruction applications, do: 1) > chdir('Tools/Reconstruction/OpticalSensors'); > exec StaticAllTrajectoriesReconstruction.sci; or 2) > chdir('Tools/Reconstruction/InertialSensors'); > exec TrajectoryReconstruction.sci; See Tools/Reconstruction/README file for more informations. * A new Human model The reconstruction module uses a new human model with 27 articulations. This human model is described in repertory Tools/Reconstruction/KinematicModel/Human27 . For the moment, it is used only in Reconstruction module but it will be integrated soon in whole HuMAnS. * VRML Visualization enhancement - The VRML Visualization of Bip bug is resolved: the feet are no more sliding on the ground. - The white triangle has disappeared. You must touch the ground or the avatar(bip robot or human) to replay the simulation. * The used scilab version is now scilab-3.1.1 . So, set SCIDIR to scilab directory. If SCIDIR is not set, the default dir is /usr/lib/scilab-3.1.1 * Bugs - The simulation results seem still to be excessively different between Linux and Windows platforms: we're investigating. *** What's new in version 1.0.2 *** * Space movements Draft A ComputedTorqueInSpaceControl of the NoDynamics ActuationControl has been added. It compensates completely the gravity forces in order to simulate movements in space with no contact points and therefore conservation of the translation and rotation momenta. A slight correction of the Complete LagrangianDynamics ContactForces has been required. This is used to build the SpaceWalk sample application described in section 7 of this README file. * Automatic test procedures Automatic test procedures are in Test repertory. The references values are in InitValues repertory. The command 'make test' allows us to compare the results of applications to their references values. The test results are in Test.log file. See Test/README file for more informations. * Doxygen Documentation The Doxygen documentation is now complete. Open Documentation/Doxygen/html/index.html to have a look at it. * VRML Visualization enhancement The Bip Model is now complete and non h-anim compliant. The sizes of the human model are now the same as the sizes used in simulation. A ground has been added. * Other additions - Windows compilation debugged. - A Spy has been introduced, which is activated if SpyPeriod is set and draws a stick figure of the system every SpyPeriod. - SpyPeriod has been set in every Sample applications. - Visu can print now a Message above the stick figure. - Identification algorithms and experimental datas have been added in Tools/BipExperiments/Friction. * Bugs - The VRML Visualization of Bip is still slightly buggy (the feet are sliding on the ground). - The simulation results seem to be excessively different between Linux and Windows platforms: we're investigating. *** What's new in version 1.0.1 *** * Sit to stand Draft The Complete LagrangianDynamics has been modified to include a contribution from Christine Azevedo and Rodolphe Heliot. You can now specify a vector ActiveDOF to restrict the dynamics to a certain set of active degrees of freedom. The function Visu.sci has also been reworked in order to deal more efficiently with multiple contacting solids through the use of the vector ContactSolids defined in the files LagrangianModel/*/SomeDefinitions.sci. An empty ActuationModel has been introduced under the name NoDynamics. It includes a ComputedTorque control law. All this is used to build the ChairSitToStand sample application described in section 7 of this README file. * VRML Visualization Draft The repertories LagrangianModel/Bip/Visualization and LagrangianModel/Human/Vizualisation contain the functions which allow to create a VRML file corresponding to the simulation. The repertory LagrangianModel/Bip/Visualization (resp. LagrangianModel/Human/Vizualisation) will be used when you considere the Bip model (resp. the Human Model). How to use it in Scilab: In order to use the VisuVRML function in Scilab, the name and the number of the Joints used in simulation must be write in SomeDefinitions.sci file (In LagrangianModel/Bip or Human/Visualization repertory). The arguments of the VisuVRML function are: * the sequence of articular positions Q issued of simulation * the time sample deltat of the simulation * the name of the model used ('Human' or 'Bip') * the resolution of the model ('Low' or 'High') * and the name of the output VRML file. examples of use: VisuVRML(Q,1e-2,'Human','Low','ChairSitToStand.wrl') VisuVRML(Q,1e-2,'Bip','High','BipOneStep.wrl') The Geometry file are the VRML file which correspond to the geometric model used (without animations). They are in the repertories Visualization : * BipHigh.wrl for the Bip H-anim Model * HumanLow.wrl for the Mister Potato H-anim Model (the human Model). Note : For the moment, we have only BipHigh and HumanLow. Note 1: The output file are create in the repertory corresponding to the execution file used, ie in HuManS repertory. Note 2: It is better that the name of the output file was SimulationName.wrl . For example: ChairSitToStand.wrl . How to read the VRML File: See the topo h-anim made by Laurence Boissieux at the adress: http://www.inrialpes.fr/sed/people/boissieux/HUMANS/H-ANIM/#viewer Under Linux, Octaga is easier than ExaminerViewer to install and to use. When you touch the white triangle under the model, the visualization restart. Bugs and things to come: * The Human Model is a prototype, it should be improved later * The Human VRML has not yet the same dimensions that the model used to calculate the simulation. So the visualization isn't very good: body parts will perhaps enter in collision(example in the visualization of the FESSitToStand simulation). In the same way, in the visualization of the ChairSitToStand simulation, the foots move but in the simulation, they don't move. * The Computation of the position of the Bip Model has a bug: the foot position are false in the visualization of the BipOneStepSimulation. It would be resolved later. * The Bip Model BipHigh.wrl is a H-anim model, but it doesn't correspond to the real Bip Model. A more complete model should been proposed soon. * Compilation Process Complete You should be able now to compile the whole software yourself both on Unix and Windows XP systems following the instructions given in sections 5 and 6 of this README file. * Doxygen Draft First steps in building a technical documentation of all the functions of this software have been undertaken through the use of Doxygen. Only the Kernel is concerned so far. 9) Automatic Software Tests see Test/README