SCAD - Creating simpler URDF colliders

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");

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

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);

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);
}

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);

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).

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.