SCAD - Creating simpler URDF colliders

1 What is scad and why should it be used?
2 Creating .scad-files
- 2.1 Importing .stl-files into OpenSCAD
- 2.2 Adding scad shapes
- 2.3 Using variables
- 2.4 Combining scad shapes to a scad model
3 Using .scad-files with the onshape-to-robot export tool

What is scad and why should it be used?

When generating URDF files from our onshape repository using onshape-to-robot, the complex geometry of the source .stl files is used for collision detection. This can be extremely computation heavy in the simulation programs.

To remedy this, onshape-to-robot features various options to use simpler geometries instead. One of these options is using “scad” files in place of the .stl files when the <collision>-Elements are created.

Scad-files are comprised of simple geometrical shapes like cubes, spheres, cylinders, as well as their two-dimensional counterparts.

Creating .scad-files

One readily accessible option is to use the OpenSCAD-Editor. It can be installed on all common operating systems. https://openscad.org/downloads.html

Within OpenSCAD you can define and combine simple shapes that can serve as collider replacement.

Importing .stl-files into OpenSCAD

To ensure the new 3D-models being created match the originals, the source .stl-files can be overlaid onto the OpenSCAD workspace to aid as a visual guide.

This can be done using the “import”-function with the .stl-pathfile as parameter.

% scale(1000) import("/../meshes/urdf_head.stl");

The scale factor depends on the unit size of the source .stl.

Currently within the pib project a scale of 1000 percent ensures that the scad-models match in size with the rest of the .stl files in the simulation programs.

If all was done correctly, the workspace should be filled with the semi transparent .stl-model.

Screenshots of the OpenSCAD workspace before and after the .stl-file was imported

Adding scad shapes

New shapes can be added to the workspace by typing the corresponding function into the editor.
Here is a useful cheat-sheet showing the most common functions and their parameters. https://openscad.org/cheatsheet/

Example:

If I want to add an approximation of pibs head, I can simply create a cube of the roughly matching size by entering this line into the editor:

cube([230 , 170, 200], center = false);

Screenshot of the OpenSCAD workspace with the .stl-file of pibs head and a cube in matching size

The problem is, that the cube is at the wrong position. If the import this scad file together with the rest of pibs model, it will also be in the wrong place and thus the collision calculation will be completely false.

To move the cube to the right position, the “translate”-function can be used.

translate([-115, -145, -68]) {
    cube([230 , 170, 200], 
        center = false);
}

Screenshot of the scad model being laid over the .stl-models

Now the .scad-model matches the .stl-model.

Using variables

All numbers within .scad-files can be easily switched out for variables making the models easier to maintain.

cube_width=230;
cube_depth=170;
cube_height=200;
cube([cube_width , cube_depth, cube_heigth], center = false);

As of right now, we haven’t decided on best practices when creating scad files.
This includes when to use variables instead of hard coded numbers.

Combining scad shapes to a scad model

Some parts may require more complex scad shapes to accurately match their collision properties.
These can be easily assembled by adding multiple shapes to the editor together with translation functions.

Example:

translate([-115, -145, -68]) {
    cube([230 , 170, 200], 
        center = false);
}

translate([115, -145, -68]) {
    cylinder(200, 200, center = false);
}

Using .scad-files with the onshape-to-robot export tool

1. Install onshape-to-robot

Run this command from a linux console to install the tool:

pip install onshape-to-robot

2. Create a config.json file

For onshape-to-robot to run you need a file containing the export parameters. This is a json file simply named “config.json”. Put this file into the folder where the export data should be exported into.

You can use one of the config.json files from our digital-twin github repository.
The parameters should already be prepared for a correct pib export. All you need to add is your onshape_access_key and onshape_secret_key. Which you can find on the “API Keys”-section of the onshape dev portal (https://dev-portal.onshape.com/keys).

The onshape-to-robot website contains a guide explaining all export parameters in detail

3. Install OpenSCAD and MeshLab

For Onshape-To-Robot to apply the scad models, OpenSCAD and MeshLab need to be installed on the Linux system where you want to run the export. It can be installed using this command:

sudo apt-get install openscad meshlab

If one of the programs is missing, the export will still produce an URDF-file, but it will use the .stl meshes instead instead of the .scad models. The only notification you will get is the this console error message right after starting the export:

4. Move the scad files into the config.json folder

You need to move all your .scad-files into the same directory that also contains your config.json-file.

Onshape-to-robot will then replace all collision elements that would normally use the .stl meshes with the corresponding scad models. For this to work, the .scad and .stl files need to have the same name.

5. Run the export

If all prior steps were completed, you should now be able to successfully export an URDF-file containing the scad models as colliders with the following command:

onshape-to-robot your_target_folder_name

The files should now be generated in the target folder.

Screenshot of the export target folder before and after