User Manual

Install Instructions

The Unity connector, like other Unity packages, is installed on a project basis.

To install the Unity Connector into your Unity project:

1. Download the latest release from the provided download link

2. Open the Package Manager from the Unity Editor’s Window dropdown at the top.

3. Click the “+” at the top left corner of the package manager window and hit “Add From Disk”

4. Navigate to the package folder and find the package.json file within. Select it.

5. The connector should load and show NVIDIA Omniverse Connector and version number in the Unity Package Manager.

Update Instructions

1. Omniverse Launcher will occasionally have updates available for the connector. Currently updating the connector in the launcher will NOT update the package in Unity. Download the latest update from Launcher.

2. Open the Package Manager from the Unity Editor’s Window dropdown at the top.

3. Click the “+” at the top left corner of the package manager window and hit “Add From Disk”

4. Navigate to the package folder and find the package.json file within. Select it.

5. Recommended to close and re-open Unity when using a new connector Update

Uninstall Instructions

To uninstall the Unity Connector from your Unity project:

1. Open Package Manager (Window->Package Manager)

2. Select the Omniverse Unity Connector Package at top left, and then click Remove in the bottom right corner of the window.

3. To uninstall from launcher go to Library > Unity Connector’s Hamburger menu (see 2nd image) > settings > uninstall

Omniverse Menu

Export

• Launches the Nucleus file browser.

Export USDZ

• Select a path on local disk to export .usdz

Note

When a usdz is exported we still also export the .usd and Materials folder.

Live Sync

• Connect to an exported file in Nucleus to enable collaboration.

Settings

• Settings for the currently opened scene.

Help

1. Documentation

   • Links to Connector Docs and Release Notes

2. Get Support

   • Report Bugs, Provide Feedback, Developer Forums

3. About

   • Should have Connector, Client Library, and USD Library versions.

Export

Omniverse > Export

• Selection of Export will open a file picker window which allows the user to choose a location to save the USD. File picker has access to either local disks or + Nucleus. Can also choose location by typing in the URL. File type (usd, usda, usdc) can also be chosen.

Live Sync Panel

Omniverse > Live Sync

Live Sync enables users to collaborate in real-time on a USD in Omniverse, using Nucleus.

Note

Important: Unity is currently a Uni-directional connector meaning changes in Unity during a live sync session only update in the viewport of session participant’s apps and changes in other apps are not seen in the Unity viewport but they do update the Live session usd.

Note

You must first Export a .usd from Unity to a Nucleus server and then Create a Live Sync Session from the recent export of the open Unity scene. Share the Omniverse URL with those that want to join the session. When in Live Sync changes to a scene in Omniverse will not apply to Unity, but changes in Unity will apply to Omniverse.

Users have the ability to configure the following properties for live sync, using the Live Sync panel:

• Path

  • The path to the .usd file to live sync to. This file must be on Nucleus. This field is automatically populated from the last Export.

• Validate

  • Press to validate the path above and provide available sessions.

• Available Sessions

  • Live Sync sessions which have been created for the file at the path. Select a listed session to join it. For each new Export Create a new Live Session to ensure you have the correct state in the usd file.

• Name

  • The name of a new session. You cannot create a session which has the same name as an existing session and a session name must begin with an alphabetic letter.

• Create Session

  • Press “Create Session” to create a new session with the Name provided.

• Leave Session

  • Leaves the current session which is joined.

• End Session and Merge Changes

  • Merges changes to the USD stage and ends the live session for all participants.

Omniverse Settings Panel

Omniverse > Settings

Users have the ability to configure the following export properties for a given scene, using the Omniverse Settings panel:

• Scale Factor

  • The relative scale between your unity scene and the USD. This scale factor will be applied to the top level prim (named after your scene). The number is in Centimeters (cm). Default value is 100.

• Export Disabled Objects

  • If enabled, then disabled objects will be exported. Default is Off.

• Export Selection Only

  • If enabled, then only the objects selected in Unity will be exported. If disabled then the whole Unity Scene will be exported. Default is Off.

• Export Physics

  • If enabled, then physics component properties are exported as UsdPhysics properties on their respective objects.

• Show Info Logs

  • If enabled, the Unity Console Info logs will have verbose information of actions performed by the connector and debug log information. Default is On.

• Open in App

  • Can choose an omniverse app to automatically open your USD with after exporting.

Help Panel

Omniverse > Help

Help panel provides links to documentation, support, and information about the Unity Connector.

• Documentation

  • Link to Omniverse Unity connector Documentation.

• Get Support

  • Link to Omniverse Developer forums

  • Link to Community Service Desk for feature requests and bug reports.

• About

  • Information about the connector version, build, and client library version. Please provide this information when submitting bug reports.

Materials Handling

This section describes which of Unity’s material parameters are used when exporting USD.

Supported Materials by Render Pipeline

The following Shaders are supported by render pipeline.

Render Pipeline	Shader
Built-In	Standard
URP	Universal Render Pipeline/Lit
HDRP	HDRP/Lit

For each, the value is retrieved using the parameter name provided in the Shader.

Therefore, if you use parameter names commonly used in Unity (_MainTex, _MetallicGlossMap, etc.), you may be able to get material parameters with other Shaders than this.

Type of material to be exported to USD

Select Omniverse-Settings from the main menu to open the Omniverse Settings panel.

Select the material type in “Export Material Type”.

Material Type	Description
None	No material assignment
MDL	Assign OmniPBR or OmniGlass
UsdPreviewSurface	Assign UsdPreviewSurface

Built-In: Standard

In the Built-In Standard Shader, the following red parameters are the USD export targets.

• Albedo Color / Albedo Map

• Metallic

• Smoothness

• Metallic/Smoothness Map

• Normal Map

• Occlusion Map

• Emission Color / Emission Map

• Texture transform: Tiling, Offset

Render Mode supports: Opaque, Cutout, and Transparent

Render Mode: Opaque

Assign Opaque to an opaque shape.

Render Mode: Cutout

For shapes that involve trimming, such as tree leaves, assign Cutout.

In this case, the cutout is made according to the alpha value of the Albedo Map.

“Alpha Cutoff” is the threshold value.

Render Mode: Transparent

Translucency is represented by Transparent.

When passed to USD, Opacity is assigned.

Transparent uses the alpha channel of the Albedo Map and the alpha value of the Albedo color.

• If the Albedo Map does not exist, the alpha value of the Albedo Color is output as the Opacity value of the USD.

  • If an Albedo Map exists and the alpha value of the Albedo Color is 1.0, the Alpha channel of the Albedo Map is used as the Opacity Map for USD (Opacity Mono Source=“mono_alpha” in OmniPBR).

  • If an Albedo Map exists and the alpha value of the Albedo Color is not 1.0, the Alpha channel of the Albedo Map is multiplied by the alpha value of the Albedo Color and used as the Opacity Map for USD (Opacity Mono Source=“mono_average” in OmniPBR).

Albedo Maps

If both Albedo color and Albedo Map are present, they will appear multiplied in the USD export.

In USD, the Albedo map and Albedo Color each have their own parameters.

Metallic/Smoothness Map

In Unity, Metallic/Smoothness and Occlusion maps are packed into one texture.

Occlusion is often a separate texture.

Reference Unity Documentation

Channel	Property
Red	Metallic
Green	Occlusion
Blue	None
Alpha	Smoothness

Smoothness = 1.0 - Roughness

The Metallic/Smoothness map is decomposed into USD metallic map and roughness map.

If the Metallic/Smoothness Map is not specified, specify the Metallic and Smoothness values as numbers from 0.0-1.0.

Normal Map

When specifying a Normal Map, the strength of the Normal can also be specified.

When exporting USD, if the material type is MDL, both Normal Map and NormalMap strength will be output.

If the material type is usdPreviewSurface, the strength value is ignored because it does not have a Normal Map strength parameter.

Occlusion Map

Occlusion Map is output when using UsdPreviewSurface as the material type for USD export.

Note

Occlusion Map output is not supported when OmniPBR is used.

If an Occlusion value is specified(If not 1.0), the Occlusion Map and Occlusion value are baked into the texture and output.

Emission

When the Emission checkbox is checked, Emission Color and Emission Map can be specified.

If both are used, they are exported as a multiplied and baked texture.

It is also possible to specify a texture with HDRI (exr/hdr file) dynamic range as an Emission Map.

Texture transform : Tiling, Offset

If a texture is specified, the same values for “Tiling” and “Offset” are used for all textures.

Secondary Maps in Unity are not used in the USD export.

URP: Universal Render Pipeline/Lit

In the case of URP, the material is specified with parameters similar to those of the Built-In Standard. However there are a few differences as we will describe below.

In the URP Lit Shader, the following red parameters are the USD export targets.

• Base Color / Base Map

• Metallic

• Smoothness

• Metallic/Smoothness Map

• Normal Map

• Occlusion Map

• Emission Color / Emission Map

• Texture transform : Tiling, Offset

Surface Type can be Opaque or Transparent.

Check “Alpha Clipping” to represent Cutout.

Double Sided

If Render Face is set to Both, the double sided will be displayed in Unity.

However, when exporting USD, this information is not yet output.

Therefore, as a USD, it is always displayed on single sided.

In Omniverse, it is always displayed double sided.

HDRP : HDRP/Lit

In the case of HDRP, the material is specified with parameters similar to those of the Built-In Standard.

Since there are a few differences, we will explain only the differences.

In the HDRP Lit Shader, the following red parameters are the USD export targets.

• Base Color / Base Map

• Metallic

• Smoothness

• Mask Map (Metallic, Smoothness, Occlusion Map)

• Normal Map

• Emissive Color / Emissive Map

• Texture transform : Tiling, Offset

In HDRP, specify Metallic, Smoothness, and Occlusion Map in Mask Map.

“Surface Type” can be “Opaque” or “Transparent”.

Check “Alpha Clipping” to represent Cutout.

HDRP: Exporting OmniGlass

HDRP allows for glass representation using IOR with HDRP/Lit Shader.

When specifying some parameters, OmniGlass is used when the material is MDL in the USD export.

1. Use HDRP

2. SurfaceType = Transparent

3. BaseMap.alpha = 0.0

4. RefractionModel != None

In this case, OmniGlass is used in HDRP.

Parameters supported by HDRP’s Glass when exporting USD

The following parameters can be specified for Glass and are passed to OmniGlass in USD.

• Smoothness

• Index Of Refraction

• Thickness

• Transmittance Color (Color or Texture)

Below is the Transmittance Color and texture specified in Unity.

Exported to USD, imported into Omniverse Create and displayed inRTX-Real-Time as follows.

In Omniverse, the correct refraction is by ray tracing.

Color Management Gamma vs Linear Space in Unity and Omniverse Create

Gamma vs Linear Space

In Unity, Color is stored in sRGB and is reflected in rendering.

In USD (including MDL), colors are stored in Linear. Color includes DiffuseColor (BaseColor), Opacity, EmissiveColor, and Light color.

You may want to reference a Unity forums topic of Gamma verses Linear Color Space.

To match the color space of Unity and Create, switch Unity’s Project Settings to Linear.

To select the Color Space of your Unity project, go to Edit - Project Settings - Player - Other Settings - Rendering - Color Space”.

In Unity ensure you are using sRGB textures by selecting your texture, go to Inspector (import settings) and sRGB is checked On in Unity Inspector for the color texture.

In USD Composer (formerly Create) change the Rendering Settings -> Post Processing -> Change the Tone Mapping to Linear (Off).