Importing USD

Import Features

  • Import Mesh and Xform

  • Materials support: USDPreviewSurface, OmniPBR, OmniGlass

  • When importing a drop: If there are references, they will be imported into one Prefab

How to Import USD files

USD import can be done in three ways.

  • Drag-and-Drop USD file and folders in the Project window

  • Use Context Menu “Import From USD” in the pop-up menu of the Project window

  • Omniverse menu select Import

“Import From USD” will also load the textures assigned to the material.
”Import” in the Omniverse menu performs the same import process as “Import From USD”.

Drag-and-Drop Import USD file in the Project window

Import the usd file into Unity by dropping the usd file into the Project window.
If you are using textures in your USD files, drop them in as well, including the textures.

Supported USD File Import: usd, usdc, usda, usdz

Drop and import usd files.

If only USD files are imported, the textures in the folder will be referenced and if there is a texture file name that is the same as the one referenced in USD, it will be assigned.

Note

Import does not follow the parent from the folder where the target USD is located to search of textures in other folders. You should drag-and-drop all folders and files at the same time for the initial Import.

If NormalMap is assigned, the NormalMap settings dialog box appears.
Press the “Fix now” button.
NormalMap settings.

Context Menu Right-Click “Import From USD”

Right-click on the project window and select “Import From USD” from the pop-up menu to import USD file.
Choose "Export To USD" from Project window.
In this case, the textures referenced in the USD are also automatically loaded.
Importing USD files from this menu supports importing files on Nucleus as well as local files.
A file dialog box will appear, select the usd/usdc/usda/usdz file.
Import file picker.

Note

If the file path contains non-ASCII strings, the file may not be imported correctly. Best practice is for file and folders to usd ASCII characters and avoid special characters like # / ? | : $ @ in the file and folder names.

Texture files referenced by the material in the usd file are also imported.
Texture file when importing.
Texture files are imported into the “Textures” folder, which contains a folder for each material name.
Textures folder.
In the “Materials” folder, the materials to be referenced are created.

Import using the Omniverse menu

Import the USD file from the File dialog box in the same way, using “Import” from the Omniverse menu.
Import menu.
This is the same import flow as in “Import From USD”.
At this time, USD files and textures are imported for the active folder in the Project window and materials are generated.

USD Information

When an imported USD file is selected in the Project window, the Inspector window displays information about the USD file.
Placing assets in the scene.

The number of shapes, total triangles, materials, and references are displayed.

Placed in scene

Drop a USD file from the Project window into the Scene View to place it in the scene as a GameObject.

DisplayColor support

If DisplayColor is specified for USD, you can choose whether to use Unity’s Mesh vertex color or material on import in Settings.

DisplayColor Handling in Settings.

DisplayColor Handling : Vertex Color

If “Vertex Color” is selected for DisplayColor Handling, the DisplayColor in USD is assigned to the mesh vertex color.
In this case, the Shader of the material uses the Shader of usd-unity-sdk.
In this case, one material is used for DisplayColor assignments to all meshes.
At this time, the material for VertexColor is embedded within the asset.
Therefore, import speed is improved.

DisplayColor Handling : Material

When “Material” is selected for DisplayColor Handling, a material is created for each DisplayColor color.

In this case, the active folder in the Project window is the base path for storing DisplayColor materials.
In the following example, “Assets/Objects/ImportTest/KitchenSet” is the current asset path.
DisplayColor Handling : Material.
DisplayColor materials are created in the “Materials/DisplayColor” folder.
DisplayColor Handling : "Materials/DisplayColor" folder.
In the case of “displayColor_0B0C0C.mat”, the hexadecimal 0B0C0C of RGB is the same as the DisplayColor color.
In the case of “displayColor_0B0C0C_B2.mat”, the Opacity value is expressed in hexadecimal B2 in addition to the RGB hexadecimal 0B0C0C.

In this case, the mesh vertex color is not used, so the color cannot be changed for each vertex of the face.

Texture and material files are not overwritten

Texture files referenced in USD and material files generated by Unity will not be overwritten if the same path already exists as a Unity asset. If you want to replace materials and textures, be sure to delete the associated materials and textures once before reimporting the usd file in Unity.

Limitations

  • Currently only one usd is still to be imported. The usd specified in the usd Reference or Payload will not be imported.

Material: Clearcoat support

When using UsdPreviewSurface with USD materials, a clearcoat can be used.
The following two clearcoat parameters exist for UsdPreviewSurface.

Parameter

Description

Default

clearcoat

Clearcoat value (0.0-1.0)

0.0

clearcoatRoughness

Clearcoat roughness (0.0-1.0)

0.01

Clearcoat parameters can be either float values or textures.
Texture uses one of the r/g/b/a channels.
In Unity, Clearcoat parameters can be specified in URP and HDRP.
Clearcoat is not reflected in Built-in.

As an example, the material is specified in USD Composer as follows

Clearcoat in USD Composer.

URP - Clearcoat Mask Map

Importing this usd file into Unity’s URP will result in the following.
Clearcoat in Unity URP.
“Universal Render Pipeline/Complex Lit” is used for materials with Clearcoat parameters in URP.
Clearcoat Mask in Universal Render Pipeline/Complex Lit.
USD’s clearcoatRoughness is converted to Unity’s ClearCoat Smoothness.
Smoothness can be calculated using the following formula.
> ClearCoat Smoothness = 1.0 - clearcoatRoughness

The ClearCoat Mask Map in Unity has the following channel configuration.

[R] Mask
[G] Smoothness
[B] None
[A] None

If a clearcoat or clearcoatRoughness texture is specified in USD, it will be packed into this Unity texture.

HDRP - Coat Mask

Importing this usd file into Unity’s HDRP will result in the following.
Clearcoat Mask in Unity HDRP.
The only parameters for Clearcoat are the Coat Mask float value and the texture.
Clearcoat Mask in HDRP/Lit.

In the Clearcoat Mask texture, Clearcoat Mask was set on the R, G, and B channels.

[R] Mask
[G] Mask
[B] Mask
[A] None
In Unity’s HDRP, the ClearCoat Mask Map seemed to reference only the R channel.
In HDRP, ClearCoat Smoothness (Equivalent to “1.0 - Clearcoat Roughness” in USD) always seems to be 1.0.
Therefore, ClearcoatRoughness values in USD are ignored in the Unity Connector’s USD import.

Material Map Import Support

Compatible with USD’s UsdPreviewSurface, OmniPBR, and OmniGlass materials.
Materials are automatically converted using Unity’s standard Shaders (Built-in, URP, HDRP).
  • BaseColor, BaseColor Map

  • Emissive Color, Emissive Color Map

  • Normal Map

  • Occlusion Map

  • Metallic, Metallic Map

  • Roughness, Roughness Map

  • Opacity, Opacity Map

  • OpacityThreshold

  • Clearcoat (URP, HDRP)

  • Texture transform (scale, offset)

Note

The USD Metallic Map and Roughness Map will be converted to a MetallicSmoothness Map in Unity. And the Opacity Map is packed into the Alpha value of the BaseColor Map.

Material: OmniGlass support

When importing USD, OmniGlass will reflect the following parameters.

  • BaseColor(Albedo Color), BaseColor Map

  • Roughness, Roughness Map

  • Normal Map

  • Texture transform

  • IOR (HDRP only)

On USD Composer, the following is an example of using OmniGlass.
OmniGlass in USD Composer.

URP - Glass and Transparent Materials Import

Glass in Unity URP.
  • For Unity’s Built-in/URP, if the Alpha of BaseColor is set to 0 in Transparent, it will be hidden. In URP, set Blending Mode to Pre-multiply. BaseColor==RGB(1, 1, 1) and BaseColor Map texture not exists.

Blending Mode Premultiply.
  • In URP, if a BaseColor (BaseColor!=RGB(1, 1, 1)) or BaseMap texture exists, set Alpha=1.0 and Blending Mode to Multiply.

Blending Mode Multiply.

Built-in - Glass and Transparent Materials Import

Glass and Transparent in Built-in.
In Built-in, Render Mode is Transparent.
Alpha was set to 0.2 because setting Alpha=0.0 in Albedo would result in the disappearance of the color.
Rendering Mode Transparent.

HDRP - Glass and Transparent Materials Import

Glass and Transparent in HDRP.
For HDRP, specify Transparent in Surface Type.
Specify Alpha 0.0 for BaseMap, and do not give color and texture.
Specify Sphere in the Refraction Model of Transparency Inputs.
Specify the value of IOR in Index Of Refraction.
Thickness is specified as 1.0. This will reflect the Transmittance Color.
Specify a color or texture for Transmittance Color.
Surface Type and Transparency Inputs.

Camera support

Importing USD’s Camera supports the following parameters.

Parameter

Description

Focal Length

Focal length in millimeters

Projection

Perspective, Orthographic

Horizontal Aperture - Aperture

Sensor Size Horizontal

Vertical Aperture - Aperture

Sensor Size Vertical

Camera in USD Composer.
The sensor size is assigned to the USD aperture.
On the Unity Editor, turn on Physical Camera to find the sensor size option.
Sensor size in Unity.

Light support

USD import supports the following USD lights.

  • DistantLight

  • SphereLight

  • RectLight

Unity’s Built-in and URP do not have SphereLight.
It is replaced by a point light or spot light.
Unity’s HDRP has a radius with point lights and spot lights.

The Omniverse Unity Connector imports the parameters of the following lights of the USD into Unity.

Main Parameters

These are parameters common to all lights.

Parameter

Unity Target Render Pipeline

Description

Color

Built-in, URP, HDRP

Light color

Enable Color Temperature

URP, HDRP

Whether to use Color Temperature

Color Temperature

URP, HDRP

Color Temperature

Intensity

Built-in, URP, HDRP

Light intensity

Light main parameters.
Intensity has different units depending on the Unity render pipeline and the type of light.
For Built-in and URP, there is no clear unit of light intensity.
In Unity’s HDRP, the unit of intensity for Directional Light is Lux.
In Unity’s HDRP, the unit of intensity for Point Light, Spot Light, and Rectangle Light is Lumen.
When importing USD with the Omniverse Unity Connector, the Intensity of the light will be approximated if Unity is Built-in or URP.
The Intensity of the USD is then passed to the Intensity and Range of the light in Unity.
Note that not all brightnesses can be reproduced in Unity with an exact match when importing USD.

DistantLight

USD’s DistantLight imports as Directional Light in Unity.
The USD prim transform rotate determines the direction of the light.
Shadows cast by the light’s shadow map are disabled on import (Unity default).
For HDRP.
The default light intensity value for Distant Light in USD Composer is 3000.
The Omniverse Unity Connector importer recalculates this Distant Light as 100000 Lux (intensity of sunlight).

Unity Intensity = (USD Intensity / 3000.0) * 100000.0;

In the Omniverse Unity Connector’s USD importer, the intensity of lights in Unity’s HDRP is based on this conversion.
Other Unity Point Lights, SpotLights, and Rect Lights are also calculated to match USD in relative intensity.
This conversion process uses the general formula for lighting calculations for lights with units.

SphereLight

USD’s SphereLight imports as Point Light or Spot Light in Unity.
The Translate and Rotate of the light’s prim’s transform represent its position and orientation.

Parameter

Unity Target Render Pipeline

Description

Radius

HDRP

Radius of sphere light

Cone Angle

Built-in, URP, HDRP

If it is smaller than 180, it becomes a spotlight

Cone Softness

URP, HDRP

Softness value of the spotlight.
In Unity, it is used to calculate the interior and exterior angles of spotlights.
Sphere Light parameters.

Radius does not exist as a light parameter in Built-in or URP, but radius is used in the intensity calculation.

RectLight

USD’s RectLight imports as Area Light in Unity.

Parameter

Unity Target Render Pipeline

Description

Width

Built-in, URP, HDRP

Width of RectLight

Height

Built-in, URP, HDRP

Height of RectLight

Rect Light parameters.
Unity’s Area Light is reflected only by baking the light map.
Area Light on Unity is not reflected in real time.
To use Area Light, the mesh receiving the light must be Static and then the light map must be baked.

Please refer to the Unity documentation for details.

https://docs.unity3d.com/2022.3/Documentation/Manual/UsingPrecomputedLighting.html

Light transform scale

In Unity, the scale value of the light’s transform is not reflected in the light.

Light transform scale.

The scale of the light is always used as (1, 1, 1).

Light color temperature

In the case of Unity’s URP and HDRP, there is a color temperature parameter for the light.

Light color temperature.
In Unity, the default value for color temperature is 6570, while in USD this default value is 6500.
A color temperature of 6500 is often treated as white.
Both Unity and USD use Kelvin as the color temperature unit.
Therefore, the USD color temperature value is passed to Unity as is.
Unity’s built-in lights do not have a color temperature.
In built-ins, color temperature is converted to color and imported.

Scene Exposure in HDRP

In the case of HDRP, Auto Exposure is enabled by default immediately after creating a scene.
In this case, the intensity value of the light imported from USD will not be reflected in the rendering result as is.
In this case, Post Processing interpolation is applied.

In URP/HDRP, Post Processing parameters is specified for Volume.

Scene exposure in HDRP.
Exposure is disabled.
The default values at this time are the parameters assigned in Project Settings - Graphics - HDRP Global Settings.
HDRP Global Settings.

Exposure Mode is set to Automatic.

Exposure Mode Automatic.

In this case, Exposure is automatically adjusted according to the brightness of the entire scene.

When importing USD to Unity, the Intensity is adjusted based on the following parameter values in Exposure of the scene’s Volume.

HDRP Fixed exposure.
  • Mode : Fixed

  • Fixed Exposure : 13.11

  • Compensation : 0

This was adjusted so that the illuminance was close to (1.0, 1.0, 1.0) when the Directional Light was placed vertically downward.
The Intensity for Directional Light in this case was given as 100000 Lux.
This value is often used for Intensity to illuminate the ground from the sky on a sunny day.
Directional Light intensity criteria.

When importing USD, PointLight, SpotLight, and Area Light on Unity are adjusted to match relatively based on the Intensity of this Directional Light.

This implementation is only available for HDRP.
URP and Built-in perform lighting calculations differently than HDRP.

Skin and Skeleton support

Supports import of USD skins and skeleton structures.

The skeleton in USD is as follows.

Skeleton structure. Skeleton and Bones.
There is a Skeleton in the SkelRoot, and the joints are arranged in a hierarchical structure within the Skeleton.
This represents a skeleton.
The mesh to which the Skeleton is assigned exists within the SkelRoot.
It is also possible to reference the same skeleton from multiple meshes.
In the USD file, the joints that make up the skeleton are not assigned to Prim.
These are stored in an array in the joints parameter of the Skeleton prim.

It is preferable for the joints in a Skeleton to have a hierarchical structure starting from a single joint.

Import this skin+skeleton structure USD file into Unity.

Import skin and skeleton.
In Unity, a bone (joint in USD) hierarchy is represented by a regular GameObject.
The root joint in the USD Skeleton becomes the root bone in Unity.
If there are multiple root joints in one Skeleton in USD, the parent Prim (In this example Armature) becomes the root bone in Unity.
The import also passes per-vertex weight values and affected joints from USD to the Unity mesh.
This allows the skin + skeleton data to be brought from USD to Unity.