1. Obtain robot description folder

cp -r ~/downloads/path/to/robot/desciptions/h1_description ~/desktop

Next, make a directory for the preprocessed robot, and copy the robots urdf into it.

mkdir ~/documents/apollo-resources/robots/h1
cp ~/desktop/path/to/robot/desciptions/h1_description/urdf/h1.urdf ~/documents/apollo-resources/robots/h1/

2. Preprocess robot

2.1. Initial steps

Inside the apollo-rust-preprocessor/src/bin folder, create a rust file as follows:

use apollo_rust_preprocessor::{PreprocessorModule, ResourcesSubDirectoryTrait};
use apollo_rust_modules::ResourcesRootDirectory;

fn main() {
    let r = ResourcesRootDirectory::new_from_default_apollo_robots_directory();
    let s = r.get_subdirectory("h1");
    s.preprocess_robot(false); // Select if you want to rebuild all preprocessed modules
}

Running this will build/rebuild packages as necessary and begin preprocessing the robot. After the initial preprocessing has finished, a visualization will be launched where you can use the sliders to ensure basic kinematic information has been correctly parsed. You can select different mesh types as well as view link shape approximations including convex hulls and decompositions, and oriented bounding boxes and bounding spheres (for both links and decomposed links). If the visualization looks good, then you should proceed by clicking the green “Verified” button. Otherwise you can still proceed with the subsequent steps, but record that something is incorrect by selecting “Not Verified” in red.

2.2. Manually set link skips

After clicking “Verified,” a new window will appear that provides information about pairwise distances between links. Specifically, the panel labeled “Pairwise Distances Raw” gives the current distance between two robot links (in meters). On the other hand, the panel labeled “Pairwise Distances wrt Average” gives the distance normalized by the average gap between these links across sampled states in the space of robot configurations. This information can be useful for motion planning and control (e.g., for collision avoidance). However, not all pairwise distances are meaningful. For example, links directly adjacent to each other will naturally be close, and their proximity should not be penalized. Thus, this interface can help you skip these unnecessary pairwise distance computations.

In the second column of the “set link skips” window (as visualized below), you can see the distance between each pair of links in the current state. For links which have no chance of intersecting, or links that are always close together but should not be counted as self intersections, select the pair (note that the links in question will be highlighted while the remaining links will become light grey) and double click “Set selected as skip,” which appears in the third column.

Additionally, this same procedure can be done using the pairwise distances with respect to their average distances, which are sampled over the space of robot configurations.

This process can be done for full convex hulls and convex decompositions, representing each link shape as either the actual convex hull, an oriented bounding box, or a bounding sphere. Once all link pair skips have been selected, you can click “Save and exit” to complete the process.

3. Resetting link skips after robot has been preprocessed

In the case you wish to modify your original link skips selections, you can re-launch the “set link skips” window with the following code segment.

let r = ResourcesRootDirectory::new_from_default_apollo_robots_directory();
let s = r.get_subdirectory("h1_test");
let mut c = s.to_chain_nalgebra();

c.refine_link_shapes_skips_module();

The interface is identical to the original window, and you can make changes using the same instructions as in (2.2). Once finished, make sure to double click “Save and exit” to include your updates.