Merge pull request #5 from Space-Robotics-Laboratory/release/v1.0

Release/v1.0

.gitignore

@@ -0,0 +1,19 @@
+# Ignore figure files
+*.eps
+*.png
+!docs/media/*.png
+*.fig
+
+# Ignore files inside data
+dat/
+!dat/.gitkeep
+*.csv
+*.dat
+*.avi
+
+# Ignore USER configuration file
+/config/USER/*
+!/config/USER/config_USER_param_template.m
+
+# Ignore MATLAB temporary files
+*.asv

README.md

@@ -1,2 +1,54 @@
-# climbing_simulator
-climbing simulator written in Matlab 
+# ClimbLab - Climbing robot Matlab simulator
+
+![ex3_uneven_dynamic_Uno-gait-planning_stability_polyhedron.gif](./docs/media/ex3_uneven_dynamic_Uno-gait-planning_stability_polyhedron.gif)
+
+Author(s) and maintainer(s): [Space Robotics Lab.](http://www.astro.mech.tohoku.ac.jp/e/index.html) Climbing Robotics Team
+
+[![srl-logo-original.jpg](./docs/media/srl-logo-original.jpg)](http://www.astro.mech.tohoku.ac.jp/e/index.html)
+![crt_color_logo_a_hi-reso.png](./docs/media/crt_color_logo_a_hi-reso.png)
+
+The climbing simulator is being developed by the Climbing Robotics Team in [Space Robotics Laboratory](http://www.astro.mech.tohoku.ac.jp/e/index.html) at Tohoku University, Japan. 
+
+The source code is released under a [BSD 3-Clause license](./LICENSE).
+
+## Overview
+This simulator wraps up functions for:
+* [x] Dynamic analysis and simulation of articulated multi-body systems with a floating base (*This is performed by [SpaceDyn](https://github.com/Space-Robotics-Laboratory/SpaceDyn)* [1])
+* [x] Design of legged robotic system
+* [x] Environment demonstration (different terrain shape, inclination, and gravity)
+* [x] Visualization (Robot, map, support polygons, stability criterion, and time-history of any state variables) 
+
+#### Simulation examples
+| ![ex1_uneven_dynamic_fixed_stride.gif](./docs/media/ex1_uneven_dynamic_fixed_stride.gif) | ![ex2_flat_kinematic_Uno-gait-planning.gif](./docs/media/ex2_flat_kinematic_Uno-gait-planning.gif) |![GIA-poly-hedoron.png](./docs/media/GIA-poly-hedoron.png)|
+|--------|--------|--------|
+| 1) Standard gait on uneven terrain | 2) Optimal foothold selection on descrete grippable points [1] | 3) Stability region visualization [2] |
+
+## Usage
+
+If you use this simulator in academic context, please put citations of the following publications [1] and [2].
+
+#### Requirements
+We confirmed the code is working with:
+* Matlab 2018b or higher
+* [SpaceDyn](http://www.astro.mech.tohoku.ac.jp/spacedyn/) - a MATLAB Toolbox for Space and Mobile Robots (version 2, release 0)
+  - SpaceDyn toolbox v2r0 is also installed by cloning this repository (under `lib/spacedyn_v2r0`)
+
+#### Build and Run
+* Download the files from this repository
+* Open MATLAB
+* Select `ClimbLab/` as the current folder for MATLAB
+  - You should see `config/`, `dat/`, `docs/`, `lib/` and `src/` directories under it
+* Setup the parameters as you want by changing the variable `config`.
+  - Note: If you select USER configuration type, follow instructions described in the `config/USER/config_USER_param_template.m`.
+* Run `src/climb_main.m` file (**Note: MATLAB might ask you to change folder or add path. Choose to "add path"**)
+
+## Publications
+
+[1] Kentaro Uno *et al*., "[Gait Planning for a Free-Climbing Robot Based on Tumble Stability](https://ieeexplore.ieee.org/document/8700455)", Proceedings of the 2019 IEEE/SICE International Symposium on System Integration (SII), Paris, France, 2019, pp. 289-294, [doi: 10.1109/SII.2019.8700455](https://doi.org/10.1109/SII.2019.8700455).
+
+[2] Warley F. R. Ribeiro *et al*., "[Dynamic Equilibrium of Climbing Robots based on Stability Polyhedron for Gravito-Inertial Acceleration](https://clawar.org/conference-proceedings/clawar-conference/clawar-2020-proceedings/)", Proceedings of the 23rd International Conference on Climbing and Walking Robots and the Support Technologies for Mobile Machines, Moscow, Russian Federation, 2020, pp. 297-304, [doi: 10.13180/clawar.2020.24-26.08.18](https://doi.org/10.13180/clawar.2020.24-26.08.18).
+
+## FAQ
+Please contact us by sending an email to the following address if there is any question or suggestion.
+
+    limb[at]astro.mech.tohoku.ac.jp

config/USER/config_USER_param_template.m

@@ -0,0 +1,57 @@
+%%%%%% THIS FILE IS A TEMPLATE. Please copy it to the folder config/USER with the name config_USER_param.m
+%%%%%% 
+%%%%%% Configuration
+%%%%%% config_USER_param
+%%%%%% 
+%%%%%% Define USER parameters
+%%%%%% 
+%%%%%% Created 2020-07-08
+%%%%%% Warley Ribeiro
+%%%%%% Last update: 2020-07-08
+%
+%
+% Load configurations for parameters defined by the USER 
+%
+% Function variables:
+%
+%     OUTPUT
+%         robot_param
+%         environment_param
+%         gait_param
+%         control_param
+%         equilibrium_eval_param
+%         ani_settings
+%         save_settings
+%         plot_settings
+%     INPUT
+%         -
+
+function [robot_param, environment_param, gait_param, control_param, equilibrium_eval_param, ani_settings, save_settings, ...
+    plot_settings] = config_USER_param(robot_param, environment_param, gait_param, control_param, ...
+    equilibrium_eval_param, ani_settings, save_settings, plot_settings)
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Robot Parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Environment Parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% Maximum simulation time [s]
+environment_param.time_max = 2;
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Gait Parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Control Parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Equilibrium Parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Animation Settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Save Settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+save_settings.csv_file = 'off';
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Plot Settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+end

config/config_animation_settings.m

@@ -0,0 +1,163 @@
+%%%%%% Configuration
+%%%%%% config_animation_settings
+%%%%%% 
+%%%%%% Configure default animation settings
+%%%%%% 
+%%%%%% Created 2020-07-08
+%%%%%% Warley Ribeiro
+%%%%%% Last update: 2020-07-08
+%
+%
+% Load default configurations for saving
+%
+% Function variables:
+%
+%     OUTPUT
+%         ani_settings
+%     INPUT
+%         -
+
+function ani_settings = config_animation_settings()
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% General settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Display animation on/off
+ani_settings.display = 'on';
+%%% Save animation
+ani_settings.save = 'off';
+
+%%% Frame rate [frames/s] [20,25,50]
+ani_settings.frame_rate = 20;
+%%% Animation video resolution [px] [[1280 720], [640 480]]
+ani_settings.animation_resolution = [640 480];
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Camera related %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% x-axis limits [m] [[-0.25, 0.4], [-0.25, .25], [0, .5]]
+ani_settings.x_lim = [-0.25, 0.4];
+%%% y-axis limits [m] [[-0.25, 0.4], [-0.25, .25]]
+ani_settings.y_lim = [-0.25, 0.25];
+%%% z-axis limits [m] [[-0.08, 0.1], [-0.1, .14]] [-0.25 0.25]
+ani_settings.z_lim = [-0.18, 0.15];
+%%% Lower z-axis limit same as lower point on surface on/off
+ani_settings.z_lim_low_is_surface = 'on';
+
+%%% 'on' camera follows robot, 'off' camera fixed
+ani_settings.move_camera = 'on';
+    %%% x-axis visualization range [m] [[-0.25, 0.4], [-0.25, .25], [0, .5]]
+    ani_settings.x_vis_range = ani_settings.x_lim - mean(ani_settings.x_lim);
+    %%% y-axis visualization range [m] [[-0.25, 0.4], [-0.25, .25]]
+    ani_settings.y_vis_range = ani_settings.y_lim - mean(ani_settings.y_lim);
+    %%% z-axis visualization range [m] [[-0.08, 0.1], [-0.1, .14]]
+    ani_settings.z_vis_range = ani_settings.z_lim - mean(ani_settings.z_lim);
+
+
+%%% Camera angle azimuth and elevation [deg]
+ani_settings.camera_az =-20;
+ani_settings.camera_el = 12;
+
+%%% Font name
+ani_settings.font_name = 'Times New Roman';
+%%% Font size
+ani_settings.font_size = 25;
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Robot related %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% Link radius [m]
+ani_settings.link_radius = 0.012;
+%%% Base thickness [m]
+ani_settings.base_thickness = 0.03;
+
+%%% Robot color
+ani_settings.robot_color = [0.2, 0.2, 0];
+%%% Robot transparency
+ani_settings.robot_alpha = 0.8;
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Surface related %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% Surface grid color
+ani_settings.grid_color = [0.9 0.9 0.9];
+%%% Surface color
+ani_settings.surface_color = gray;
+
+%%% Graspable points viz. on/off
+ani_settings.graspable_points_show = 'off';
+    %%% Graspable points color
+    ani_settings.graspable_points_color = [0, 0, 1.0];
+    %%% Graspable points marker
+    ani_settings.graspable_points_marker = '.';
+    %%% Graspable points size
+    ani_settings.graspable_points_size = 5;
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Gait related %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Graspable points in reachable area viz. on/off
+ani_settings.graspable_points_in_reachable_area_show = 'off';
+    %%% Graspable points in reachable area color
+    ani_settings.graspable_points_in_reachable_area_color = [0, 1.0, 0];
+    %%% Graspable points in reachable area marker
+    ani_settings.graspable_points_in_reachable_area_marker = '.';
+    %%% Graspable points in reachable area size
+    ani_settings.graspable_points_in_reachable_area_size = 20;
+
+%%% Reachable area viz. on/off
+ani_settings.reachable_area_show = 'off';
+    %%% Reachable area line color
+    ani_settings.reachable_area_line_color = 'magenta';
+    %%% Reachable area line width
+    ani_settings.reachable_area_line_width = 1;
+
+%%% Goal vis. on/off
+ani_settings.goal_show = 'off';
+    %%% Goal color
+    ani_settings.goal_color = [0 0 1.0];
+    %%% Goal marker
+    ani_settings.goal_marker = '.';
+    %%% Goal size
+    ani_settings.goal_size = 25;
+
+%%% Next desired position vis. on/off
+ani_settings.next_desired_position_show = 'off';
+    %%% Next desired position line color  m : magenta
+    ani_settings.next_desired_position_color = 'm';
+    %%% Next desired position line width
+    ani_settings.next_desired_position_line_width = 1;
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Equilibrium related %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Support triangle visualization
+ani_settings.support_triangle_show = 'off';
+    %%% Support triangle color
+    ani_settings.support_triangle_color =[0 1.0 1.0];
+    %%% Support triangle transparency
+    ani_settings.support_triangle_alpha = 0.5;
+
+%%% Stability polyhedron face color
+ani_settings.polyh_Face_color = [0 0 1];
+%%% Stability polyhedron face alpha
+ani_settings.polyh_Face_alpha = 0.25;
+%%% Stability polyhedron edge color
+ani_settings.polyh_Edge_color = [0 0 1];
+%%% Stability polyhedron edge width
+ani_settings.polyh_Edge_width = 2;
+
+%%% Gravity vector visualize on/off
+ani_settings.gravity_vec_show = 'off';
+    %%% Gravity vector color
+    ani_settings.gravity_vec_color = [0 0.7 0];
+    %%% Gravity vector width
+    ani_settings.gravity_vec_width = 3;
+
+%%% GIA vector visualize on/off
+ani_settings.gia_vec_show = 'off';
+    %%% GIA vector color
+    ani_settings.gia_vec_color = [1 0 0];
+    %%% GIA vector width
+    ani_settings.gia_vec_width = 3;
+
+%%% CoM projection point vis. on/off
+ani_settings.com_projection_show = 'off';
+    %%% CoM projection point color
+    ani_settings.com_projection_color = [1 0 0];
+    %%% CoM projection point marker
+    ani_settings.com_projection_marker = '.';
+    %%% CoM projection point size
+    ani_settings.com_projection_size = 25;
+
+end

config/config_control_param.m

@@ -0,0 +1,34 @@
+%%%%%% Configuration
+%%%%%% config_control_param
+%%%%%% 
+%%%%%% Configure default control parameters
+%%%%%% 
+%%%%%% Created 2020-07-08
+%%%%%% Warley Ribeiro
+%%%%%% Last update: 2020-07-08
+%
+%
+% Load default configurations for control methods
+%
+% Function variables:
+%
+%     OUTPUT
+%         control_param
+%     INPUT
+%         -
+
+function control_param = config_control_param()
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% General settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Controller type ('do_nothing', 'torque_PD')
+control_param.type = 'torque_PD';
+
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% PD controller settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Controller Proportional (P) gain
+control_param.kp = 3.00;
+%%% Controller Derivative (D) gain
+control_param.kd = 0.02;
+
+end

config/config_environment_param.m

@@ -0,0 +1,49 @@
+%%%%%% Configuration
+%%%%%% config_environment_param
+%%%%%% 
+%%%%%% Configure default environment parameters
+%%%%%% 
+%%%%%% Created 2020-07-08
+%%%%%% Warley Ribeiro
+%%%%%% Last update: 2020-07-08
+%
+%
+% Load default configurations for environments
+%
+% Function variables:
+%
+%     OUTPUT
+%         environment_param
+%     INPUT
+%         -
+
+function environment_param = config_environment_param()
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% General settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Type of the surface ('flat_HR', 'rough', 'flat_003', 'flat_006', 'flat_008', 'flat_009', 'flat_012') 
+environment_param.surface_type = 'rough';
+%%% Gravity [G]
+environment_param.grav = 1/6;
+
+%%% Dynamics on/off
+environment_param.dynamics_flag = 'on';
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Time settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Time-step [s]
+environment_param.time_step = 0.001;
+%%% Maximum simulation time [s]
+environment_param.time_max = 8;
+
+%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Surface settings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% Surface Inclination [deg]
+environment_param.inc = 0;
+%%% Ground reaction force stiffness coefficient
+environment_param.surface_K = 1000;
+%%% Ground reaction force damping coefficient (scalar)
+environment_param.surface_D = 1;
+%%% Graspable points detection type
+environment_param.graspable_points_detection_type = 'all';
+
+end