Onshape importer


The Onshape importer Extension is used to load Assemblies from Onshape Documents into Omniverse Isaac Sim. Onshape is a web-based CAD platform that combines CAD, built-in data management, real-time collaboration tools, and business analytics.

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

To open the importer, go to the top menu bar and click File > Import from Onshape. Once you are authenticated with the Onshape application, It will bring up a list of your personal documents, sorted by the last time they were modified.

Onshape Authentication

There are two possible ways to authenticate with the Onshape Service, OAuth and by API Keys.


This is the default authentication Method. To use Oauth, on the first time the importer is used, it will open a browser with the Onshape Login, and request permission to access your account information. This permission needs to be granted only on first use.


Once the user is authenticated, the system will not prompt for password again until Isaac Sim is restarted.

API Keys

The API Keys authentication is an alternative method to authenticate the user account. This method needs to be used when running Isaac Sim in a container or headless, as those cannot open a browser to authenticate using OAuth.

First, you need to create an API Key at https://dev-portal.onshape.com/keys. Select the options that allow Read/Write permissions to documents, and to read profile information.


Once the key is created, copy the access and secret key, then, open the script editor in Window->Script Editor and paste the following script, replacing the key values with yours:

from omni.isaac.onshape.client import set_api_keys
access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"

Now restart Isaac Sim, and when using the Onshape Importer again, it will use the stored Access and Secret keys.

User Interface

Search Window


Ref #





Search Bar. Type your document name or URL for search.


Search Results

Panel with search results. Each row is a document. If the document contains a single assembly, double-clicking the row will start importing the Assembly.


Document Assemblies List

When the document contains multiple assemblies, the button shows a list with all assemblies that can be imported.


Assembly Card

Double clicking the assembly card begins importing the assembly


Sort by

field to use when sorting search results


Sort order

Sort by Ascending/Descending on the sort field


Search Filter

Filters the search results based on the selected option


Import Options

Options used when Importing the document


If you don’t have access to the document in the URL, it may freeze load until an error appears.

Assembly View


Ref #




Reference Assembly

Displays the Name of the selected assembly and the number of parts being imported


Loading Bar

Shows the status of the import


Status Column

Shows the load status of the part


Parts List

Shows the list of parts loaded with the assembly. Can be sorted by Name, Material and Mass.


Material Column

Shows the material part and allows editing it when the user is authorized to do so in the document.


Mass Column

Shows the Part Mass property. Onshape Requires a Material to be assigned for mass properties to be computed. The tooltip includes center of mass and inertia properties.


Tessellation Column

Shows the summarized tessellation properties for the part. Clicking it enables editing its values and reimports the given part.


Assembly Options

Options Used when generating the Assembly USD.


Finish Import Button

Finishes the import, providing a window to select the save destination.

Import Onshape Assemblies

Searching for the assembly

Once the assembly search window is open, you can type in the name of the assembly you want to locate. It loads the results in batches of 20 items. Scrolling down the search results will automatically load further results that match the search criteria. You can change the search to public documents and other criteria by filter Icon, and select the filter type. You can change the sort direction by clicking the Up/Down arrow buttons.

Once the desired document is located, if it’s an assembly type, double-click it and it will load the assembly. If it’s a document that contains multiple assemblies inside, click on the title card, and it will show a list of the available assemblies. Double-click the desired assembly, and it will start loading it.

Assembly Import options

To select options when importing the assembly, click the Options button, and select the desired option. These settings are persistent across system restart.

Filter Unsupported Document Types: When enabled, it hides form the search documents that are not currently supported to be imported.

Configure Physics: When Enabled, it reorganizes the assembly following the Mates properties configured in the assembly, and sets up rigid bodies and joints for the assembly.

Part properties


Part properties can be changed for single elements, or for multiple elements when selecting them on the list. You can also use a property from a given item and apply it to selected by right-clicking the property and select Apply this <property> to selected parts.


The physical material the part is made of. This property is used to compute the mass properties for the part and is required for accurate physics simulation. If none is selected the part will load, but will be displayed in Yellow on the parts list. If the material or mass properties failed to load for some reason. the warning icon will display the error message, wich can also be collected in the runtime logs.

To change the material, click on the drop down menu, which will use the Onshape Material Libraries to select which material to be used. This is a interface for basic material changes, but custom mass properties can also be defined directly in your Onshape document.



The quality used to convert the solid surfaces in triangle meshes can be tweaked by the following parameters:

Chord Tolerance: Chord tolerance (in meters). This specifies the limit on the maximum deviation of a tessellation chord from the true surface/edge.

Angle Tolerance: This specifies the limit on the sum of the angular deviations of a tessellation chord from the tangent vectors at two chord endpoints. The specified value must be less than 90 degrees.

Max Chord: Max facet width. This specifies the limit on the size of any side of a tessellation facet.

To change the parameters, click on the tessellation properties dropdown menu, and drag the sliders or double click them to type in the value.



If a part fails to be imported, it will be displayed in Red on the parts list, and the error message can be collected from the error Icon or in the runtime logs.

Configuring Mates for Physics

The Onshape Importer Uses the Assembly mates to set up joints in the assembly. For convenience, every mate scans up the assembly tree and stops at the top-most assembly that does not contain some joint mate, and uses it as a reference instead of the mated part.

The following Mates are supported:

Fixed Mates

Group Mates: Group multiple parts that are fixed together at the top-most sub-assembly level

Fastened Mates: link two parts that are fixed together. It moves the child assembly as a sub-assembly from the parent.

Joint Mates

For all Joint Mates, the importer collects the joint position and joint limits.

Revolute Joint Mate: Mates two bodies that rotate along a bound rotation axis

Slider Joint Mate: Mates two bodies that move linearly along a bound axis.

Cylindrical Joint Mate: A combination of a revolute and a slider joint mate. It is converted as such, with a proxy rigid body with negligible mass, no visual and no collision between the two joints.

Spherical Joint Mate: A combination of a two revolute mates with no limit, and a third revolute joint bounded from zero to up to 180 degrees that we call the spherical cone. It is converted as revolute, cone, revolute, with two proxy rigid bodies with negligible mass, no visual and no collision between the joints.

Preparing the Assembly for Physics Import

To have the Assembly physics properly imported, there are a few guidelines to follow:

  1. Group all Sub-Assemblies with no internal moving parts together: Groups are a convenient way to have all fixed body parts to be treated as a single rigid body. Use that to simplify the process of creating mates instead of using fastened mates.

  2. Sub-Assemblies with internal joints must be fastened: Sub-Assemblies that contain internal Joint Mates must have the part that is bound to the main assembly body mated with a fastened mate.

  3. Mates must follow Assembly hierarchy: Fastened Mates and Joint Mates must follow the assembly hierarchy. e.g. A sub-assembly part that is fastened to the main body in the assembly must be second in order on the Mate.

  4. Assembly Must be at Zero Pose: The assembly will be treated as if it were in the zero position. Failure to put the assembly in the zero pose will not break the import, but the initial pose will be treated as zero for all purposes (e.g. the joint limits will be offset by the mate value).


It is preferrable to use assemblies, opposed to group mates for fixed parts. Any assembly that does not contain Joint mates and are fixed to a parent assembly part will be treated as a single body.


  1. Add Joint Drives: Since the joint drive information is unavailable from Onshape Models, this needs to be added to all driven joints post-importing. Select the desired joint, and on the Properties panel click in Add->Physics->Joint Drive.

  1. (Optional) Modify Collision Shapes: By default, every part imported with physics is given a Convex Hull Approximation. This can be changed depending on the application (e.g. Wheels need to be a cylinder primitive instead of a mesh approximation to ensure smooth rolling simulation)

  2. (Optional) Fix Assembly Base: By default, no part is fixed after imported. You can select the assembly base prim, and add a Fixed joint to the world space by right-clicking it on the stage menu, then Create->Physics->Join->Fixed Joint.

  3. (Optional) Simplify Assembly Tree: You can simplify the assembly tree by using the Mesh Merge Tool. This operation does not create the physics collision and mass properties on the merged mesh, needing to be added later to the mesh once the original tree is removed from the rigid body.

Tutorials & Examples

The following tutorials and examples showcase how to best use this extension:

Preparing your Onshape Document

Importing your Onshape Document