Box-Simulator

Maarten Jongeneel

Simple robotics simulator for objects that experience impact and friction

This simulator was developed as part of my MSc Thesis

If you are using this simulator, please refer to it as

@MastersThesis{2020_JongeneelModelBasedVisual,
    author  = {Maarten Johannes Jongeneel},
    title   = {{Model-Based Visual Object Tracking with Collision Models}},
    school  = {Eindhoven University of Technology, Faculty of Mechanical Engineering,
                Dynamics \& Control Section},
    address = {the Netherlands},
    year    = {2020},
    month   = {March}
    }

Requirements

• MATLAB 2020a or later.

Introduction

This project contains the code I used during my MSc thesis for simulating a box impacting a surface. The code is numerical integration of a nonsmooth dynamical model with impacts and friction, using an augmented Lagrangian approach from [1]. By running the main script main.m, you can simulate a box being tossed on a contact surface. The simulator itself is fully contained in the function BoxSimulator.m, which contains all the necessary functions to run. All settings can be set within the main scripts listed above and the comments provided there should suffice to understand the script. The underlying theory is further explained in my thesis, which can be found here.

Table of content

• Overview
• Installation
• Usage of the scripts
• Contact

Overview

In current form, the simulator allows you to simulate a single box being tossed on one or multiple surfaces, which can each have a certain speed (to simulate e.g., a conveyor). This contact surface can have a certain position and orientation w.r.t. a world frame, and a certain velocity in any direction. The box can have a certain initial position, orientation, linear and angular velocity, and you can set the coefficients of friction, normal restitution, and tangential restitution. The video below shows two examples of simulations results, for which the scenes can be found in the scenes folder.

Figure 1: Two videos showing examples of simulation results. The two videos correspond to the two scenes described in the scenes folder.

Installation

The code of this repository is all written in MATLAB and can directly be cloned from this repository. To read the different scenes (see here), we make use of the readyaml matlab function as a submodule. Therefore, to clone this repo, follow these steps:

git clone --recurse-submodules https://github.com/MaartenJongeneel/box-simulator.git

Usage of the scripts

The simulator itself is the function BoxSimulator.m, which is a stand alone function. This function is called by the main script main.m, which contains all settings for the simulation and should be run to initialize the simulation and obtain the results. Below, we give some further details on the settings.

General settings

The general settings as shown below allow you to decide if you want to save the resulting trajectory (4x4 transformation matrices), if you want to plot the resulting trajectory (as shown in the video above), and if you want to save this trajectory to an .avi video.

%% General settings
dosave             = false;         %Save the trajectory (AH_B) to a .mat file
doPlot             = true;          %Show the trajectory of the box
MakeVideo          = false;         %Save the simulation result to video

Running scenes

In the scenes folder, some examples of scenes are provided. These scenes contain the information about the box and the surfaces that define the scene. In Matlab, these scenes are loaded via the following lines of code:

%% Read the scene that you want to run
scenefile = "DoubleConveyor.yml";
data = readyaml(scenefile);

where the variable for scenefile should be changed in case a different scene should be run.

Defining the Box

In the scene file, you define the box object following this structure:

# Parameters of the Box
box:
 mass: 1
 dimensions: [0.1, 0.15, 0.05]
 inertia_tensor:
  - [1, 0, 0, 0, 0, 0]
  - [0, 1, 0, 0, 0, 0]
  - [0, 0, 1, 0, 0, 0]
  - [0, 0, 0, 0.0021, 0, 0]
  - [0, 0, 0, 0, 0.001, 0]
  - [0, 0, 0, 0, 0, 0.0027]
 release:
  position: [0, 0, 0.2]
  orientation:
   - [1, 0, 0]
   - [0, 1, 0]
   - [0, 0, 1]
  linVel: [0, 0, 0]
  angVel: [3, 1, 0]
 parameters:
  mu: 0.5
  eN: 0.4
  eT: 0.0
discretization: 4

You can set here the mass, dimensions, and the 6x6 generalized inertia tensor. Furthermore, you need to specify the release position, orientation (3x3 rotation matrix), and linear and angular velocity. The parameters mu, eN, and eT define the coefficient of friction, normal restitution, and tangential restitution, respectively. Finally, the discretization parameter defines in how many contact points you want to discretize the surfaces. For the values given above, the image below show the resulting box model, with the contact points indicated in blue (note that the discretization of 4 in this case leads to 4 contact points in each dimension on the surface of the box.).

Figure 2: Geometric model of the box with the contact points indicated in blue.

Defining contact surfaces

The position and orientation of the contact surface are defined by the 4x4 transformation matrix, defining its position and orientation w.r.t. the world frame. The speed of the conveyor is defined in it's own frame in m/s (typically you would have this only in x- and y- direction, but sure, you can also put a z-velocity (out of plane).). The dimensions of the contact surface are in meters. In the yaml file that defines the scene, you can set these parameters. The example below shows how:

surface:
 - dim: [1, 2]
   speed: [0, 1, 0]
   transform:
    - [0.9962, 0, 0.0872, 0]
    - [0.0151, 0.9848, -0.1730, 0.5]
    - [-0.0858, 0.1736, 0.9811, 0]
    - [0, 0, 0, 1]

Simulation settings

In the settings below, we define the runtime of the simulation, the stepsize (c.dt), and the speed with which the simulation result is played back (step). The values for (c.a) and (c.tol) refer to the settings of the fixed-point iteration that is used to solve the contact problem, and define the auxilary parameter and the error tolerance of convergence, respectively.

%% Parameters for input
c.a                  = 0.001;         %Prox point auxilary parameter             [-]
c.tol                = 1e-7;          %Error tol for fixed-point                 [-]
c.m                  = 1;             %Mass of the box                           [kg]  
c.endtime            = 1.5;           %Runtime of the simulation                 [s]
c.dt                 = 1/1000;        %Timestep at which the simulator runs      [s]
step                 = 1/c.dt/100;    %Number of discrete points we skip per shown frame

Contact

In case you have questions or if you encountered an error, please contact us through the "Issues" functionality on GIT, or send an email to m.j.jongeneel@tue.nl.