Skip to content
EGAD! an Evolved Grasping Analysis Dataset
Python Shell
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
egad Fix reeb output bug in singularity, update script args Feb 20, 2020
scripts fix docs Feb 20, 2020
singularity Link singularity to dexnet deployment on github Feb 20, 2020
.gitignore Initial commit Feb 19, 2020
LICENSE Initial commit Feb 14, 2020 Add acknowledgements to README Mar 5, 2020 add dependency_links for to work with setuptools Feb 19, 2020


EGAD! an Evolved Grasping Analysis Dataset for diversity and reproducibility in robotic manipulation

See Project Website for overview and multimedia material.

arXiv Paper

Installing as a Library

This code was developed on Ubuntu 18.04 with Python 3.7.4.

git clone 
cd egad
pip3 install -e .

Resizing Evaluation Objects

To resize the object meshes for a specific gripper width, use in the scripts folder:

>>> python --help

usage: [-h] [--stl] width path

Process meshes for specific gripper.

positional arguments:
  width       Gripper width maximum. Either meters or millimeters depending on
              desired output.
  path        Path to directory containing .obj files.

optional arguments:
  -h, --help  show this help message and exit
  --stl       Output .stl rather than .obj files (useful for printing)


python 120 ~/Downloads/egad_eval_set --stl

Will resize the meshes in ~/Downloads/egad_eval_set to the appropriate size for a 120mm wide antipodal gripper, and output a set of .stl files to ~/Downloads/egad_eval_set/processed_meshes

Note on units

Depending on the software used, it may either assume that meshes are specified in meters or millimeters. e.g. some 3D-printing software assumes meshes are in mm, while some simulation software (e.g. VREP) assumes meters. If your meshes appear 1000x too small or large, change the unit of the gripper width used to generate the meshes (i.e. specify 0.12 instead of 120).

Generating an Object Dataset

We provide a Singularity container (similar to Docker but optimised for HPC clusters) to ease reproduction and deployment of our code. This helps streamline the deployment of dependencies and also allows for easy deployment on computing clusters.

Note that the code will take a very long time to run on a desktop PC.
The evaluation step can be largely parallelised, so running on a computer with many cores is recommended.

1. Install Singularity

Follow the installation instructions at This code has been run and tested with Singularity 3.5.

2. Clone this repo

git clone
cd egad
pip3 install -e .

3. Build the singularity container

cd singularity
sudo singularity build egad.sif singularity.def 

# You can test that the compile worked by running a shell inside the container.
singularity run egad.sif

# exit with ctrl+D

Once built, the container can be deployed on any other machine running Singularity, e.g. a HPC cluster.

4. Run with the default arguments

Running the datasetgen app of the container will run the object generation script.

The singularity container requires a directory on the host machine to output data, which is mapped internally to /output. Specify this with -B /path/to/local/output/directory:/output, replacing this with a path on your machine.

singularity run -B /path/to/local/output/directory:/output --app datasetgen egad.sif

If running correctly, updates will be printed to the screen.

Data will appear in a timestamped subdirectory of the output directory with the following structure:

│   gen_<gen>.json 
│   (JSON dict of current state of the search space as of generation <gen>. 
│    Keys = position in map "(<complexity>, <difficulty>)".
│    Values = list of mesh ids, corresponding to files in the pool directory)
│       <generation>_<uniqueid>.ext 
│       (raw outputs e.g. meshes, reeb graphs, thumbnails)
│       <checkpoints for the NEAT algorithm>
│       gen_div_<gen>.json
│       (current diversity of every mesh as of generation <gen>)

5. Visualise results

(On the host machine)

This script will populate the /path/to/local/output/directory/<timestamp>/viz directory with a visualisation of the algorithm's progress at each generation.

cd <path/to/egad>/scripts
python /path/to/local/output/directory/<timestamp>

6. Running with custom arguments

Arguments can be provided to the script by appending them to the above singularity command. For example, one can change the size of the search space, or the number of parallel processes used for evaluation.

A full list of arguments can be viewed by providing the --help tag:

singularity run -B --app datasetgen egad.sif --help

usage: [-h] [--cppnsize CPPNSIZE]
                           [--cppnconfig CPPNCONFIG] [--mapsize MAPSIZE]
                           [--complexitydims COMPLEXITYDIMS]
                           [--difficultydims DIFFICULTYDIMS]
                           [--cellsize CELLSIZE] [--neighbours NEIGHBOURS]
                           [--divthreshold DIVTHRESHOLD]
                           [--processes PROCESSES] [--chunksize CHUNKSIZE]
                           [--reebpath REEBPATH] [--dexnetenv DEXNETENV]
                           [--outputdir OUTPUTDIR] [--resume]

Generate shape dataset using CPPNs.

optional arguments:
  -h, --help            show this help message and exit
  --cppnsize CPPNSIZE   Dimension of CPPN voxel grid.
  --cppnconfig CPPNCONFIG
                        path to CPPN config file
  --mapsize MAPSIZE     Dimension of the search space
  --complexitydims COMPLEXITYDIMS
                        Number of cells in complexity dimension
  --difficultydims DIFFICULTYDIMS
                        Number of cells in difficulty dimension
  --cellsize CELLSIZE   Meshes to keep per cell
  --neighbours NEIGHBOURS
                        Number of neighbours to compute diversity
  --divthreshold DIVTHRESHOLD
                        Minimum threshold for object diversity
  --processes PROCESSES
                        Number of procesing threads
  --chunksize CHUNKSIZE
                        Number of jobs per thread at a time
  --reebpath REEBPATH   Path to reeb graph implementation
  --dexnetenv DEXNETENV
                        Python environment for dexnet
  --outputdir OUTPUTDIR
  --resume              resume from last run

7. Running with local/custom code

NB: If your custom code requires extra dependencies these will have to be build into the singularity container by modifiying singularity/singularity.def, as the container filesystem can not be modified after compile.

Inside the container, the egad code is pulled from github and stored in /home/co/egad. You can overwrite this with code the host machine using the -B bind command to the container. This way, you can test new code without having to rebuild the container.

# e.g. to overwrite the entire directory with a local copy.
singularity run -B /path/to/local/output/directory:/output -B /home/user/dev/egad/:/home/co/egad --app datasetgen egad.sif

# e.g. to overwrite a single file (scripts/ in this case)
singularity run -B /path/to/local/output/directory:/output -B /home/user/dev/egad/scripts/ --app datasetgen egad.sif

References and Acknowledgements

This project wouldn't have been possible without the following projects:

You can’t perform that action at this time.