Exporting USD Files#

There are multiple ways to export USD files using the Omniverse Unity Connector.

File output is done via the File Picker provided by Omniverse.

The Omniverse File Picker can be used to output USD files onto Nucleus in addition to local disk or a network volume output.

Supported USD file types#

USD File Type	Description
usd	usd file (binary)
usdc	usd file (binary)
usda	usd file (text)
usdz	usdz file (Uncompressed zipped file of textures and usd files)

Exporting USD#

Select [Omniverse]-[Export] from the main menu to display the file picker.

This will export the entire current scene.

Select the GameObject in the Hierarchy window and choose “Export To USD” from the pop-up menu that appears by right-clicking, and a File Picker will appear.

Choose "Export To USD" from Hierarchy window.

This will export only the selected GameObjects.

Select the GameObject asset in the Project window and choose “Export To USD” from the pop-up menu that appears by right-clicking, and a file picker will appear.

Choose "Export To USD" from Project window.

In this case, assets that are not present in the scene can also be exported.

Render Pipeline Support#

The Unity Omniverse Connector supports Built-In, URP, and HDRP.

Shaders that can be used as materials include.

Render Pipeline	Available Shader
Built-in	Standard
URP	Universal Render Pipeline/LitUniversal Render Pipeline/Complex Lit (When using Clearcoat)
HDRP	HDRP/Lit

Path hierarchy for USD export#

When USD is exported, the Prim path hierarchy will look like this.

The current scene name in the Unity Editor is assigned to the Prim name when exported to USD.

Opening the exported USD in USD Composer resulted in the following.

The root (defaultPrim) of the Prim path is “World”.
Next, the Prim given the scene name is placed as an Xform.
Next, a Prim in “Geometry” is placed.

World (defaultPrim)
  Scene name
    Geometry

Within the “Geometry”, the Prim hierarchy is placed, identical to the Unity Editor hierarchy.

Transform elements#

Prim’s Transform with a scene name contains the following elements.

Rotation to replace Up Axis (Y-Up to Z-Up)
metersPerUnit scale conversion (meters to centimeters)

Exporting Environments as Dome Lights#

Skyboxes in Unity allow the user to specify HDR or EXR files as background, light-casting images. For skyboxes to export through the Unity Connector, they must be applied as the Skybox Materials under Lighting -> Environment settings.

Supported shaders are Skybox/Panoramic, Skybox/Cubemap, and Skybox/Procedural. If the latter type is chosen, the Directional Light chosen will act as the Sun Source.

Skyboxes assigned to Scenes are converted to DomeLights when exporting to the USD. At this time, the Scene’s Skybox is baked, written as an equirectangular EXR file.

> Note: DomeLights are not exported when exporting from the “Export To USD” menu.

Before export, set the resolution of the HDRI to be used for the DomeLight. This is found in the Omniverse Settings under Export DomeLight. The default is None, which means no DomeLight will be exported. Choosing a resolution will enable DomeLight creation at export time.

Limitations due to USD specifications#

If the GameObject name is not ASCII alphanumeric or ‘_’, the Prim name characters will be replaced with ‘_’ during export.
In the exported Prim name, numbers cannot be used as the first character. In this case, ‘_’ is added to the beginning of the Prim name.
If the GameObject name is not an ASCII string, the prim name is replaced with something like “GameObject_1”. At this time, the same name as the GameObject is stored in DisplayName.

Export Targets#

You can export an entire scene or selected GameObjects as USD files.

You can also export assets in the Project window as USD files.

The following is a list of export targets.

Scene hierarchy
Mesh
Material and Textures
Lights
Camera
Physics (RigidBody, Collider, Physics Joint, Articulation)
Display Color / Display Opacity
Mesh vertex colors
Skin and Skeleton
Animation
DomeLight

If you are using prefabs, there is also an option to export the prefabs into separate usd files.

Please refer to Prefab as Payload support for details.

Parameters passed to USD#

GameObjects without mesh are exported as Xforms with transforms.
Mesh exports vertices, normal vectors, UVs, and triangle vertex indices.
Lights export Directional Light, Point Light, Spot Light, and Area Light.
Camera can export either Perspective or Orthographic.
DisplayColor and DisplayOpacity are output if the mesh has a vertex color and is assigned a material that uses a VertexColor shader.

Render Pipeline	Description
Built-in	StandardVertexColor.shader
URP	SrpVertexColor.shadergraph
HDRP	SrpVertexColor_HDRP.shadergraph

Parameters not supported when exporting USD#

Kind
Purpose
Multiple UVs in Mesh

USD Export: Prefab as Payload support#

Unity’s Prefab packages 3D model as an asset. By placing this Prefab in the scene and performing a USD export, one Prefab is output to one USD file.

In the case of this billiard table, the 3D model with the blue icon in the Hierarchy is the Prefab.

Instructions for exporting Unity Prefab as a USD Payload#

In the main menu, select [Omniverse]-[Settings] and turn on the “Prefab to Payload” checkbox before exporting the USD.

Prefab assets are output to the “payloads” folder.

In the case of a nested Prefab, a folder corresponding to the Prefab hierarchy is created.

In the following case, the “Props” asset is exported as ”Props.usd”, which has a structure with several prefabs.

USD files exported to USD are assigned an external reference as Payload.

Also, materials are held separately for each USD exported as a Prefab.

In the “Materials” folder, a folder is created with the name of the material in which the texture files are stored.

Outputting textures for use in materials.

Override in Prefab#

This “billiard_table” prefab has no material assigned to it.

After placing the “billiard_table” in the scene, we assigned a material to Prefab.

This operation is called an “override”.

The structure of this Prefab override is the same role as the USD Reference/Payload override.

In the following case, the material is overridden and assigned to the mesh of the Payload prim.

The following elements can be overridden.

Transform of GameObject
Visibility of GameObject
Binding of GameObject materials
Physics parameters of GameObject

Note

The following are NOT available in a Prefab: Moving between hierarchies within a Prefab and Delete GameObject in Prefab.

Unity’s Prefab allows you to rename child GameObjects placed in the scene.

However, the USD file does not allow renaming of Prims that are children of Reference/Payload.

USD Stage Hierarchy output from a Prefab#

The USD output of a Prefab will have the following USD Stage Prim structure.

The prim path starts with “/World/[Prefab name]/Geometry”.

[Prefab name] is the prefab name in Unity and is the same string as the USD file name.

Note

This is the current specification and is subject to change in the future.

Live Sync#

Live Sync exports all of the scene’s USD files once before use.
By checking the “Prefab as Payload” checkbox in Settings, the prefab will be exported as a separate USD file.
The root USD file will be externally referenced as Payload.

During Live Sync, the Payload meshes will update the operation as an override.

Also, if you add a new asset to the scene, this will be added to the root USD.

Note

The new asset Prefab is not output to another USD file.

Prim Name / Display Name for Non-ASCII#

Rules for USD Prim name#

The following rules apply to USD Prim names.

ASCII alphanumeric characters and ’_’ are allowed as prim names.
The first character of the Prim name cannot be a number.

For example, the following Prim names can be used.

Sphere
_Sphere
Sphere_1

The following cannot be used as Prim names.

Object : -10
球
2_sphere

Prim name conversion in USD export#

The USD export uses the GameObject name as the Prim name.

If the string cannot be used as a Prim name, it will be replaced.

For non-ASCII strings#

For non-ASCII strings, such as UTF-8 strings, the string will be replaced with something like “GameObject_1”.

The numbers at the end are sequential numbers.

The GameObject name “球” is replaced with “GameObject_1” because it is UTF-8.

For ASCII strings#

If the GameObject name is an ASCII string and there are characters that do not match the USD Prim name rules, they will be replaced with ’_’.

For example: “Object : -10” is replaced by “Object____10”.

Since “2_sphere” starts with a number, a ’_’ is inserted as the first character.

The conversion is “_2_sphere”.

Display Name#

In USD, a DisplayName can be specified separately for Prim.

The DisplayName can also be UTF-8, and it does not matter if it overlaps with other DisplayName.

In the Omniverse Unity Connector’s USD export, if the GameObject name is not allowed as the USD Prim name, the original GameObject name is stored in the DisplayName.

In USD Composer, select “Show Display Names” from the options menu in the upper right corner of the Stage window. This will show the Display Name, if one exists.

If you are using a UTF-8 DisplayName, you must specify the font for that language at the startup of USD Composer.