Usage#

The DGN importer imports usable incomplete output and displays its diagnostics in a warning notification. Successful conversions can also have warnings. Review the scene and conversion logs when either occurs. Malformed filter patterns are dropped with warnings and can broaden the selection; see the DGN core overview for the model and level fallback rules.

The user can then import the DGN file into Omniverse via two workflows: via File Menu Window or via the Content Window.

How to Import and Convert Files#

File -> Import#

To import a CAD file into Omniverse, choose Import in the File menu.
The user should now see a window similar to a file manager. The user needs to then select a DGN file for conversion from this window.
Refer to Converter Options section for more information on conversion settings.

CAD Converter File Import

Import through the Content Window#

By default the Content window is located at the bottom of the Omniverse App. To convert a CAD file to USD, select the file in the Content window and choose Convert to USD in the context menu with right mouse button.
Browse to the location of your file or files, select them, and right-click, and select Convert to USD in the Context menu.
The Converter Options dialog window will appear, modify any options as needed, and click Convert.

CAD Converter Convert to USD

Note: The Content Window tab provides a file browser interface for navigating and managing files. If it is not shown, go to the Menu toolbar, select “Window”, and then select “Content”.

Converter Options#

Convert Options

The DGN converter provides several options to control how files are converted:

Stage Metrics Options#

These options modify the stage’s metersPerUnit and upAxis settings, applying relevant transformations to maintain proper world space units.

Option	Description
Override Up-Axis	Override the stage’s up-axis to Y-up, Z-up, or use converter default
Meters Per Unit	Set the stage’s meters per unit metric (0.0 retains original conversion value)

One DGN file can contain models that use different units, such as millimeters and meters. The converter scales each selected model to preserve its physical size and placement. The first selected model determines the USD stage units.

Conversion Options#

Option	Description
Mesh Conversion Style	Controls how mesh elements are converted. Options: None (skip mesh conversion), Attributes (metadata only, authored as Xform with transform), Renderable (convert to both geometry and USD attributes).
Curve Conversion Style	Controls how non-text curve elements are converted, including 2D layout `Shape` and `ComplexShape` boundaries when set to Renderable. Options: None (skip curve conversion), Attributes (metadata only, authored as Xform with transform), Renderable (convert to both geometry and USD attributes). See 2D layout curve output in the DGN Core documentation.
Convert Visible Only	If enabled, skips hidden elements. If disabled, converts hidden elements but sets them to invisible.
Instancing Style	When instancing is enabled (Instancing Style set to “Scenegraph Instancing”), the DGN converter reuses geometry and materials for Shared Cell References. If one occurrence has a different material, the converter disables instancing only for that occurrence. This preserves its appearance and can increase memory use. See Instancing in USD for details.

Material Options#

Material Type	Description
None	Does not create explicit materials. Authors display-color and opacity primvars and binds a root `DefaultDisplayColorMaterial`.
Preview Surface	Default option, creates a simple preview surface material compatible with Universal renderer
OmniPBR	Creates a physically based material compatible for RTX and Universal renderers
MaterialX	Creates an OpenPBR MaterialX material (with a UsdPreviewSurface fallback network for the universal render context).

Supported DGN materials preserve base color, opacity, gloss, and supported file textures. The supported texture channels are color, normal, opacity, and emissive.

For file output, texture images are copied into a Textures directory beside the USD file.

Note: For more information about materials, see Materials Templates documentation

Advanced Options#

Option	Description
Generate Projection UVs	When UV texture coordinates are missing, uses Scene Optimizer Kit Extension to generate texture coordinates for meshes. Uses default values as described in the Generate Projection UVs documentation.
Convert Element ID	When enabled, DGN element IDs are converted to custom USD attributes or primvars
Convert Texture Coordinates	When enabled, predefined DGN mesh texture coordinates are converted to face-varying USD UV primvars. This option does not generate missing texture coordinates and does not control material conversion.
Merge Meshes	When enabled, meshes sharing the same level, color, and element type are merged for optimization. When disabled, mesh merging is skipped.
Merge Curves	When enabled, curves are merged for optimization
Triangulate	When enabled, all polygons are triangulated during conversion
Apply Global Origin	When enabled, applies the global origin transformation to the converted scene. When disabled, the value is stored as an attribute but the Model has no transform applied.
Fallback Curve Width	Default curve width when not specified in source. Set to -1 to use source default.
Geometry Attribute Style	Controls how DGN geometry attributes are authored to USD. Options: None (don’t author attributes), Attribute (default, author as a custom attribute), Primvar (author as a constant primvar)
Merged Attribute Style	Sets the attribute style for merged geometry. Options: None (no attributes on merged geometry), Primvar (store attributes as primvars), Subset (store attributes using geometry subsets)
Verbose Logging	When enabled, verbose logging will be reported to omni logs and the console during conversion. Useful for debugging conversion issues or when detailed conversion reports are required.

Level and Attribute Filtering#

These options control which content from the DGN file is imported. All list fields accept comma-separated values with wildcard support (* matches any sequence of characters). Type plain tokens separated by commas—do not wrap each token in JSON-style double quotes (unlike the quoted strings in a JSON config file).

When Level Filter Style is not None, geometry on the DGN Default level is always converted. Level Includes and Level Excludes apply to other levels only.

Option	Description
Level Filter Style	None, Omit, Deactivate (convert but deactivate filtered), Hide (convert but hide filtered). When filtering is enabled, Default-level geometry is always converted.
Level Includes	Comma-separated list of level name patterns to include. Defaults to `` (all non-Default levels; Default is always included when filtering is enabled). Example: `Default, arch_, *_structural`
Hidden Levels	Comma-separated list of level name patterns to hide. Leave the list empty to disable level hiding. Example: `2D, hidden, draft_*`
Level Exclude Hidden	When enabled, levels matching the Level Excludes list are excluded from conversion
Level Excludes	Comma-separated list of level name patterns to exclude. Only active when Level Exclude Hidden is enabled. Does not remove Default-level geometry when filtering is enabled. Example: `temp, *_old`
Model Name Patterns	Case-sensitive, comma-separated model name patterns to include. The first matching model determines the USD stage units. If no model matches, conversion succeeds without model prims and uses centimeters as the stage unit. Example: `Default, model_, _arch`
Attributes	JSON array of attribute mapping objects to import from the source file. Leave the array empty to disable custom-property import. Each entry must include `name` (source attribute name), `converted_name` (USD attribute name), and an optional `prefix` field. Example: `[{"name": "GUID", "prefix": "", "converted_name": "guid_usd"}]`

Note: If the Attributes field contains invalid JSON when you click Convert, the conversion will be cancelled and a warning notification will be shown. The field must be either empty or a valid JSON array.

Tessellation Control#

Tessellation options control mesh accuracy versus performance. These settings determine how surfaces are converted into triangular meshes.

Surface Tolerance#

The surface tolerance setting controls mesh accuracy versus performance:

Value	Mode	Result
Positive	Absolute tolerance	Uses the selected physical unit, or scene units when Native Units is selected
Zero	Automatic bounds-relative tolerance	Uses 2.5% of the object’s extents diagonal
Negative (for example, -0.01)	Custom bounds-relative tolerance	Uses the absolute value as a fraction of the object’s extents diagonal (1% in this example)

For positive values, a smaller effective distance produces a more detailed mesh with more triangles, while a larger distance produces a coarser mesh. The useful numeric range therefore depends on the selected unit and the scale of the source geometry.

The core API, configuration, and command-line default is 0.02 in scene units (surfaceToleranceUnit=0.0). The import dialog intentionally defaults the unit to meters, so its default is 0.02 meters.

The unit selector applies only to positive tolerances. It is hidden in the import dialog for zero and negative values because bounds-relative tolerances are dimensionless.

Note: For detailed information about tessellation, see Open Design Alliance’s blog post

Additional Tessellation Options#

Option	Description	Default
Normal Tolerance	Maximum angle (in degrees) between adjacent face normals. Smaller values produce smoother surfaces with more triangles. Controls tessellation quality of circular surfaces (Cone, Torus, Sphere, Cylinder). Measured in degrees, determines quantity of mesh cells (360/NormalTolerance).	15.0
Between Knots	Number of points to add between knots when tessellating curves. For NURB surfaces, contains number of additional isolines between knots.	2
Grid Aspect Ratio	Grid aspect ratio for tessellation. Set to 0 for automatic calculation.	0.0
Max Facet Edge Length	Maximum facet edge length for tessellation. Set to 0 for no limit.	0.0
Max Grid Lines	Maximum number of grid lines for tessellation.	10000
Points Per Edge	Points per edge for curve tessellation. Set to 0 for automatic calculation.	0

Text 3D Options#

Text conversion options control how 3D text elements such as OdDgTextNode3d and OdDgText3d from DGN files are converted to USD.

Option	Description	Default
Text 3D Conversion Style	Controls how 3D text elements (OdDgText3d and OdDgTextNode3d) are converted. None – skip 3D text conversion entirely; Attributes – author as USD attributes only (no geometry); Renderable – convert to Basis Curves and author attributes in a separate layer.	None
Curve Sample Points	Number of sample points to use when approximating curve for OdDgText3d and OdDgTextNode3d objects.	8
Text 3D Width	Sets the width for Basis Curves converted from OdDgText3d and OdDgTextNode3d elements.	0.05

Output Options#

Option	Description
Path	Destination folder for converted USD (defaults to source location)
Scene Optimizer Config	Path to Scene Optimizer JSON config file or JSON string for predefined optimization stack. See Scene Optimizer Service documentation.

Getting Help#

Omniverse Enterprise Customer Support Services.
The Developer Community can also ask questions or report issues on Omniverse Developer forums.