ShapeNet Importer

About

The ShapeNet Importer Extension allows users to import and convert 3D models from the ShapeNet V2 database into Omniverse as USD files. ShapeNet is an ongoing effort to establish a richly-annotated, large-scale dataset of 3D shapes.

This extension is enabled by default. If it is ever disabled, it can be re-enabled from the Extension Manager by searching for ShapeNet.

To access this Extension, go to the top menu bar and click Isaac Utils > ShapeNet Loader.

../_images/isaac_shapenet_shapes.png

Requirements

This extension requires a web browser to fully function since it uses the webbot python package for login automation when it creates the Shapenet Database Index File the first time it is used.

This extension requires a valid ShapeNet login to download and import ShapeNet models into Omniverse. Please register a ShapeNet account at shapenet.org prior to using this extension.

API Documentation

See the API Documentation for complete usage information.

Running the extension for the first time

When you run the ShapeNet Importer Extension for the first time, and before you can add a ShapeNet model into the omniverse scene, you must create a shapenet database index file, and there will be a button with that name at the top of the extension window.

When you click on the Create ShapeNet Database Index File button, the ShapeNet Importer Extension will verify your shapenet.org login and download the CSV files from the ShapeNet V1 database.

These CSV files are used to build a ShapeNet Database Index File.

  • The Shapenet Database Index File is just a list of valid shapnetId mapped to the class names associated with them.

  • The Shapenet Database Index File is only created once. This step is skipped when the database is discoverable on your local storage.

Storing the ShapeNet Database Locally

There are over 50,000 3D models in the ShapeNet database. To avoid downloading models multiple times, and to facilitate pre-downloading the database, the SHAPENET_LOCAL_DIR environment variable is used to point the extension to where the database is stored locally.

If the ShapeNet V2 database already exists locally, if you already download the ShapeNet v2 database locally, you should set an environment variable SHAPENET_LOCAL_DIR to its current location. That way the extension will use the existing local copy instead of downloading individual models each time a new model is added for the first time.

If not defined by the user, SHAPENET_LOCAL_DIR is automatically set to the local Omniverse ${data}/shapenet folder.

Note

The local copies of the ShapeNet obj files are also convenient places to alter the original obj files with any changes if you wish to alter the obj files directly.

In Linux

The SHAPENET_LOCAL_DIR environment variable is defined in a single shell session with the command:

export SHAPENET_LOCAL_DIR=/folder/where/shapenetv2/was/extracted

and that command can be added to the user’s ~/.profile file so that it is persistent in every session.

In Windows

The SHAPENET_LOCAL_DIR environment variable is set by pressing the windows command key and typing env, and then clicking on the Environment Variables… button at the bottom of the Advanced tab on the System Properties window. Once in the Environment Variables window, simple click on New… to create it for a single user or system wide.

User Interface

../_images/isaac_shapenet_ui.png

Add A Model Parameters

When you click on the Add A Model button, the parameters in the UI will be used to place the model.

  • Omniverse Server: This is the address of the Omniverse Nucleus server where you wish to store the converted USD versions of the shapenet models.

  • synsetId and modelId: The synsetId and modelId set exact ids used in the ShapeNet database, or set the string to “random”. If the synsetId is set to an exact id, the modelId may still be “random”, and that will produce a random model from within the set synset category.

  • X Y Z Position: The translational position of the model in the scene scale.

  • X Y Z Axis Angle: The rotation of the object in Axis Angle notation.

  • Scale of Add: All ShapeNet v2 model sizes are normalized to 1, so set this to the size you wish the model to scale to.

  • Automatically Add Physics: Check this box to add rigid body physics to the model.

  • Use Convex Decomposition: When this is checked in conjunction with phycis, the model will be automatically decomposed into parts and collision hulls created from each part instead of the whole model.

Tutorial & Examples

The ShapeNet Importer Extension has a python interface, and an HTTPS messaging interface that can be used in external python sessions and Jupyter notebooks. The following tutorial showcases how to use these features, and how to best use this extension in general: