Overview#
omni.kit.converter.dgn_core converts DGN files to USD using the ODA Kernel and Drawings SDKs. This is a core extension without a GUI that provides the fundamental DGN conversion functionality. It can be used directly through its Python API, or accessed through the GUI extension omni.kit.converter.dgn which provides a user interface for the conversion process.
Upon loading, it registers with the CAD Converter service (omni.services.convert.cad) if available, allowing other extensions to utilize its conversion capabilities.
The resulting USD file from the DGN Converter prepends names of DGN levels to prims. This allows for quick search by users to find geometry belonging to desired converted levels.
Importer UI text fields#
The omni.kit.converter.dgn importer Advanced Parameters panel exposes some options as single-line text. How you type them differs by field:
Level Includes, Hidden Levels, Level Excludes, and Model Name Patterns are lists of string patterns. You may enter comma-separated plain text (for example
Default, layer_*) or paste a JSON array of strings in the same shape as in a converter config file (for example["Default", "layer_*"]). Only JSON string elements are split into separate patterns; arrays that contain numbers, booleans, or nested objects are not interpreted as multiple patterns (the pasted text is kept as a single entry).Attributes must be valid JSON: a JSON array of objects with
name,converted_name, and optionalprefix, as documented under Converter Option: Attributes below. Comma-separated plain text is not supported for this field.
Supported DGN Element Types#
Container Types#
The element types below are converted to UsdGeomXform prims.
Cell Header (3D) - OdDgCellHeader3d
Cell Header (2D) - OdDgCellHeader2d
Shared Cell Reference - OdDgSharedCellReference
Shared Cell Definition - OdDgSharedCellDefinition
2D cell headers apply their origin and transformation so nested 2D layout geometry keeps its placement in the converted USD stage.
Mesh Types#
The element types below are converted to UsdGeomMesh prims.
Complex Shape (3D) - OdDgComplexShape
Shape (3D) - OdDgShape3d
Solid - OdDgSolid
Surface - OdDgSurface
Mesh - OdDgMesh
Cone - OdDgCone
BSpline Surface - OdDgBSplineSurface
Curve Types#
The element types below are converted to UsdGeomBasisCurves prims when Curve Conversion Style is set to Renderable (2).
Line - OdDgLine3d
Line String - OdDgLineString3d
Ellipse - OdDgEllipse3d
Arc - OdDgArc3d
BSpline Curve - OdDgBSplineCurve3d
Shape (2D) - OdDgShape2d
Complex Shape (2D) - OdDgComplexShape
2D layout curve output#
Set curveConversionStyle to Renderable (2) to author supported DGN 2D curve data as UsdGeomBasisCurves. Supported 2D data includes lines, line strings, shapes, complex shapes, B-spline curves, generic sampled curve elements, and exploded text outlines.
OdDgComplexShape elements keep their existing mesh-first behavior when curveConversionStyle is None (0, the default): they are authored as meshes whenever meshConversionStyle is enabled. When curveConversionStyle is Renderable, the converter instead authors their ODA complex-curve boundary as USD curve data so 2D layout drawings do not disappear when tessellation produces no mesh faces.
DGN CONVERTER CONFIG FILE INPUTS:#
Conversion options are configured by supplying a JSON file. Below are the available configuration options.
NOTE: instancing, useMaterials, hideLevelsByList, and importAttributesByList are deprecated in release 514.0.0. They remain supported during this deprecation period and produce migration warnings. Use instancingStyle, materialType, hiddenLevels, and attributes instead.
JSON Converter Settings:#
Format: Each option is specified as a JSON key-value pair, e.g. "option_name": default_value
Converter Option: Max Grid Lines#
Description: The maximum number of grid lines.
Default Value: 10000
Data Format: integer
Config File Example:
"maxNumGridLines" : 10000
Converter Option: Max Facet Edge Length#
Description: The maximum facet edge length.
Default Value: 0.0
Data Format: double
Config File Example:
"maxFacetEdgeLength" : 0.0
Converter Option: Normal To Tolerance#
Description: NormalTolerance allows to specify the tessellation quality of circular surfaces (such as Cone, Torus, Sphere or Cylinder). It is measured in degrees. The value of this parameter determines the quantity of mesh cells (triangles) used to represent a circular surface (360/NormalTolerance). Default value is 15. It means, for an example, that surface will be tessellated with 24 mesh cells (triangles) in circular direction.
Default Value: 15.0
Data Format: double
Config File Example:
"normalTolerance" : 15.0
Converter Option: Grid Aspect Ratio#
Description: Grid aspect ratio.
Default Value: 0.0
Data Format: double
Config File Example:
"gridAspectRatio" : 0.0
Converter Option: Between Knots#
Description: Distance between knots. This parameter contains the number of additional points between knots; for NURB surfaces it contains number of additional isolines between knots.
Default Value: 2
Data Format: integer
Config File Example:
"betweenKnots" : 2
Converter Option: Points Per Edge#
Description: Points quantity per edge.
Default Value: 0
Data Format: integer
Config File Example:
"pointsPerEdge" : 0
Converter Option: Surface Tolerance#
Description: Sets the maximum distance (surface tolerance) between the tessellated mesh and the source surface. The smaller the value the more precise the tessellated mesh. Positive values are physical distances interpreted using surfaceToleranceUnit. For a negative value, ODA multiplies the object’s extents diagonal by the value’s absolute magnitude; for example, -0.01 uses 1% of the diagonal. A value of 0.0 uses 2.5% of the diagonal. The legacy key for this option is dSurfaceTolerance.
Default Value: 0.02 scene units (with the default surfaceToleranceUnit of 0.0)
Value Ranges: Any double. Zero and negative values select bounds-relative tolerance.
Data Format: double
Config File Example:
"surfaceTolerance" : 0.02
NOTE: Removed internal limits on the surfaceTolerance option, allowing users to specify the full range supported by ODA. The iTessLOD converter option was deprecated to avoid conflicts and enable unlimited tolerance values.
Converter Option: Surface Tolerance Unit#
Description: Sets the unit used to interpret a positive surfaceTolerance, expressed as meters per unit. Use 0.0 to interpret the tolerance directly in scene units, 1.0 for meters, or 0.001 for millimeters. This option is ignored when surfaceTolerance is zero or negative.
Default Value: 0.0 (scene units)
Value Ranges: Greater or equal to 0.0
Data Format: double
Config File Example:
"surfaceToleranceUnit" : 0.0
Converter Option: Use Materials (Deprecated)#
Description: Controls whether the converter creates explicit materials. Use materialType instead. Set materialType to 0 to disable explicit materials.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"useMaterials" : true
Converter Option: Material Select#
Description: Sets the material type for the target renderer. The eNone value disables explicit materials, authors display-color primvars, and binds a root DefaultDisplayColorMaterial.
Default Value: 1
Value Ranges: [0, 3]
0: Does not create explicit materials. Authors display-color and opacity primvars and binds a root
DefaultDisplayColorMaterial.1: USD Preview Surface; default and compatible with Universal renderers
2: OmniPBR + USD Preview Surface; compatible with RTX and Universal renderers
3: OpenPBR MaterialX + USD Preview Surface fallback; compatible with MaterialX-aware renderers.
Data Format: integer
Config File Example:
"materialType" : 1
Converter Option: Geometry Attribute Style#
Description: The style in how the DGN geometry attributes get authoered to USD
Default Value: 1
Value Ranges: [0, 2]
0: None; Don’t author attributes
1: Attribute; Default option, author as a custom attribute
2: Primvar; Author as a constant primvar
Data Format: integer
Config File Example:
"geometryAttributeStyle": 1
Converter Option: Generate UVs#
Description: If true, calls Scene Optimizer Service Kit extension to generate UVs if missing in source data. The legacy key for this option is bOptimize.
Behaviour change: Previously this option defaulted to true (as bOptimize). It now defaults to false to avoid USD scene bloat from unused UVs, so new conversions with default parameters do not run UV generation. Set sceneOpGenerateUVs to true when UVs are required.
See Scene Optimizer Service documentation for details.
Default Value: false
Value Ranges: true, false
Data Format: bool
Config File Example:
"sceneOpGenerateUVs" : false
Converter Option: Instancing (Deprecated)#
Description: Controls USD Reference instancing. Use instancingStyle instead. instancingStyle takes precedence when both options are supplied.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"instancing" : true
Converter Option: Instancing Style#
Description: Style of instancing to use in USD when handling Shared Cell References. Creates references to a prototype prim, allowing multiple instances to share geometry and materials. This reduces memory usage and improves performance compared to duplicating geometry. See Scenegraph Instancing documentation for more details.
Default Value: 1
Value Ranges: [0, 1] 0: No instancing 1: Scenegraph Instancing is enabled
Data Format: integer
Config File Example:
"instancingStyle" : 1
Converter Option: Mesh Conversion Style#
Description: Style for converting mesh elements: None (0) – skip mesh conversion; Attributes (1) – metadata only (Xform with transform); Renderable (2) – full geometry conversion.
Default Value: 2 (Renderable)
Value Ranges: 0 (None), 1 (Attributes), 2 (Renderable)
Data Format: integer (enum)
Config File Example:
"meshConversionStyle" : 2
Converter Option: Curve Conversion Style#
Description: Style for converting non-text curve elements (Lines, Linestrings, Arcs, Ellipses, 2D Shapes, 2D Complex Shapes, etc.): None (0) – skip curve conversion; Attributes (1) – metadata only (Xform with transform); Renderable (2) – convert to Basis Curves and attributes. The legacy key convertCurves (bool) is still accepted for backward compatibility and maps true to eRenderable and false to eNone.
Default Value: 0 (None)
Value Ranges: 0 (None), 1 (Attributes), 2 (Renderable)
Data Format: integer (enum)
Config File Example:
"curveConversionStyle" : 2
See 2D layout curve output for how 2D Shape and ComplexShape boundaries are authored when this option is enabled.
Converter Option: Text 3D Conversion Style#
Description: Style for converting 3D text elements (OdDgText3d and OdDgTextNode3d): None (0) – do not convert; Attributes (1) – store as attributes only; Renderable (2) – convert to Basis Curves and attributes in a separate layer.
Default Value: 0 (None)
Value Ranges: 0 (None), 1 (Attributes), 2 (Renderable)
Data Format: integer (enum)
Config File Example:
"text3dConversionStyle" : 0
Converter Option: Text 3D Width#
Description: Set the width for Basis Curves converted from OdDgText3d and OdDgTextNode3d elements.
Default Value: 0.05
Value Ranges: Positive numbers
Data Format: float
Config File Example:
"text3dWidth" : 0.05
Converter Option: Curve Sample Points#
Description: Number of sample points to use when approximating curve shapes, including OdDgText3d and OdDgTextNode3d objects.
Default Value: 8
Value Ranges: Positive integers greater or equal to 2
Data Format: integer
Config File Example:
"curveSamplePoints" : 8
Converter Option: Fallback Curve Width#
Description: Default curve width to use when a curve element does not specify a width in the source file. Set to -1 to use the source file’s default.
Default Value: -1.0
Value Ranges: -1.0 or positive numbers
Data Format: double
Config File Example:
"fallbackCurveWidth" : -1.0
Converter Option: Apply Global Origin#
Description: This flag controls whether the global origin of Models are applied as transforms. If false the value is stored as an attribute but the Model has no transform applied.
Default Value: false
Value Ranges: true, false
Data Format: bool
"applyGlobalOrigin" : false
Converter Option: Hide Levels by List (Deprecated)#
Description: Controls whether hiddenLevels hides matching levels. Use an empty hiddenLevels list to disable level hiding.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"hideLevelsByList" : true
Converter Option: Convert Levels#
Description: If true, only convert DGN elements belonging to the levels matching the entries under levelNamePatterns; else, ignore DGN elements belonging to the matching levels. Geometry on the DGN Default level is always converted when level filtering is applied through these legacy options (see Level Filter Style).
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"bConvertLevels" : true
Converter Option: Level Name Patterns#
Description: String array of level names patterns for resolving DGN levels to convert; level names can include wildcard characters (“*”) to complete the rest of the level name during conversion wildcard characters can be placed at the beginning (“*ault”), ending (“Def*”), or both (“*fau*”). If the user provides “*”, then all non-Default levels matching the pattern are converted. If patterns do not match any non-Default levels, conversion still proceeds when Default-level geometry is present; otherwise there may be no filtered levels to convert. Geometry on the DGN Default level is always converted when these legacy options enable filtering (see Level Filter Style). Searches are case sensitive (i.e., if a level is named “Structural” but a pattern “structural” is provided, then there is no match for that named pattern).
Default Value: [] (empty array)
Value Ranges: empty or populated array of strings
Data Format: array of strings
Config File Example:
"levelNamePatterns" : [
"Default",
"*vertedLevel",
"ConvertedLev*",
"*vertedLev*",
"ConvertedLevel_X"
]
NOTE: Level Filter Style, Level Includes, and Level Excludes options are meant to replace bConvertLevels and levelNamePatterns. You must switch to these Converter Options to handle filtered levels.
Converter Option: Level Filter Style#
Description: Styles used to handle filtered levels. Note that levelIncludes, levelExcludes, and levelExcludeHidden will be ignored if levelFilterStyle is set to FilterStyle::eNone. When level filtering is enabled (levelFilterStyle is not eNone), geometry on the DGN Default level is always converted. Include and exclude patterns apply to other levels only.
Default value: 0
Value Ranges: [0, 3]
0:
eNone— Apply no filtering1:
eOmit— Do not convert the filtered element or its descendants2:
eDeactivate— Convert all elements and deactivate the ones that were filtered3:
eHide— Convert all elements and hide the ones that were filtered
Data Format: integer
Config File Example:
"levelFilterStyle" : 0
Converter Option: Level Includes#
Description: List of level names to include during filtering. Level names can include wildcard characters (“*”) to complete the rest of the level name during conversion wildcard characters can be placed at the beginning (“*ault”), ending (“Def*”), or both (“*fau*”). If the user provides “*”, then all non-Default levels are included. If patterns do not match any non-Default levels, conversion still proceeds when Default-level geometry is present; otherwise there may be no filtered levels to convert. Geometry on the DGN Default level is always converted when level filtering is enabled (see Level Filter Style). Searches are case sensitive (i.e., if a level is named “Structural” but a pattern “structural” is provided, then there is no match for that named pattern).
Default Value: [] (empty array)
Value Ranges: empty or populated array of strings
Data Format: array of strings
Config File Example:
"levelIncludes" : [
"Default",
"3D*"
]
Converter Option: Level Excludes#
Description: List of level name patterns to exclude during filtering. Level names can include wildcard characters (“*”) to complete the rest of the level name: at the beginning (“*ault”), at the end (“Def*”), or both (“*fau*”). If no patterns are provided, no levels are excluded. If “*” is provided, all non-Default levels are excluded. Geometry on the DGN Default level is always converted when level filtering is enabled and is not removed by exclude patterns (see Level Filter Style). Searches are case sensitive (i.e., if a level is named “Structural” but a pattern “structural” is provided, then there is no match for that named pattern).
Default Value: [] (empty array)
Value Ranges: empty or populated array of strings
Data Format: array of strings
Config File Example:
"levelExcludes" : [
"Default",
"3D*"
]
Converter Option: Merge Meshes#
Description: If true, meshes that share the same level, color, and element type are merged for optimization; else, mesh merging is skipped. The legacy key for this option is bMergeMeshes.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"mergeMeshes" : true
Converter Option: Merge Curves#
Description: If true, curves that share the same level, color, and element type are merged for optimization; else, curve merging is skipped.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"mergeCurves" : true
Converter Option: Triangulate#
Description: If true, all polygons are triangulated during conversion; else, polygons are kept as-is.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"triangulate" : true
Converter Option: Convert Element ID#
Description: If true, element IDs are converted to USD attributes; else, conversion of element ID is skipped.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"convertElementId" : true
Converter Option: Model Name Patterns#
Description: String array of model name patterns controlling which DGN models are converted. Model names can include wildcard characters (“*”) to match the rest of the name: at the beginning (“*aultModel”), at the end (“DefaultM*”), or both (“*faultMo*”). If no patterns are provided (empty array), all models are converted. If patterns are provided but none match any models in the DGN file, the file is not converted. If “*” is provided, all models are converted. Searches are case sensitive (i.e., if a model is named “DesignModel” but a pattern “designmodel” is provided, then there is no match.).
Default Value: [] (empty array)
Value Ranges: empty or populated array of strings
Data Format: array of strings
Config File Example:
"modelNamePatterns": ["Default", "model_foo", "*del_foo", "model_ba*", "*del_ba*"]
Converter Option: Import Attributes by List (Deprecated)#
Description: Controls whether attributes imports matching DGN custom properties. Use an empty attributes list to disable custom-property import.
Default Value: true
Value Ranges: true, false
Data Format: bool
Config File Example:
"importAttributesByList" : true
Converter Option: Attributes#
Description: Array of DGN custom-property mappings to import as USD attributes. An empty array disables custom-property import. Each object contains the source name, optional prefix, and target converted_name.
Default Value: [] (empty array)
Value Ranges: empty or populated array of JSON objects containing strings
Data Format: array of JSON objects containing strings
Importer UI: JSON only—a JSON array of objects; comma-separated plain text is not supported (Importer UI text fields).
Config File Example:
"attributes": [
{
"name": "myAttribute1",
"prefix": "myPrefix",
"converted_name": "myAttribute1_foobar"
},
{
"name": "myAttribute2",
"prefix": "",
"converted_name": "myAttribute2_foobar"
},
{
"name": "myAttribute3",
"converted_name": "myAttribute3_foobar"
}
]
Converter Option: Merged Attributes#
Description: The style in which the values of attributes that differ between merged elements are stored.
Default Value: 2
Value Ranges: [0, 2] 0 : eNone - Discard the attributes 1 : ePrimvar - Store them as a face varying primvar (not implemented) 2 : eSubset - Store them on metadata subset Prims
Data Format: integer
Config File Example:
"mergedAttributeStyle": 2
Converter Option: Progress Logging#
Description: If true, then conversion progress will be reported. The legacy key for this option is bProgressLogging.
Default Value: false
Value Ranges: true, false
Data Format: bool
Config File Example:
"progressLogging" : false
Converter Option: Verbose Logging#
Description: If true, then verbose logging will be reported to omni logs and the console during the conversion. This is particularly useful for debugging conversion issues or when detailed conversion reports are required.
Default Value: false
Value Ranges: true, false
Data Format: bool
Config File Example:
"verboseLogging" : false
Converter Option: Override Up-Axis#
Description: Override the up-axis of the converted USD’s stage to Y-up, Z-up, or default to the converter’s up-axis setting. The legacy key for this option is iUpAxis.
Default Value: 0
Value Ranges: [0, 2]
0 to default to converter’s up-axis
1 to override to Y-up
2 to override to Z-up
Data Format: integer
Config File Example:
"sceneOpUpAxis" : 0
Converter Option: Meters Per Unit#
Description: Set the meters per unit converted USD’s stage metric. If set to 0.0, the converted USD will retain the meters per unit from conversion. The legacy key for this option is dMetersPerUnit.
Default Value: 1.0
Value Ranges: Positive numbers
Data Format: double
Config File Example:
"sceneOpMetersPerUnit" : 1.0
Converter Option: Scene Optimizer Config#
Description: (Experimental feature) Provide a path to a saved Scene Optimizer JSON configuration file or a JSON formatted string for executing a predefined optimization process stack. The legacy key for this option is sOptimizeConfig.
See Scene Optimizer Service documentation for details.
Default Value: “”
Data Format: string
Config File Example:
"sceneOpConfig" : "converter_config_example.json"
Troubleshooting DGN Read Errors#
If conversion fails before USD output is written, the DGN reader may return an ODA error in the form OD_ERROR_DEF: Error code = <code>, Description = <message>. These errors come from the Open Design Alliance SDK while it is opening or reading the source DGN file.
For a broader list of ODA result values, see the public Open Design Alliance OdResult enum reference. The numeric value in the converter error corresponds to one of these ODA result values. The Description text is the message returned by the ODA SDK at runtime and may vary by SDK version or failure context.
Common examples:
Error code = 46, Description = Unexpected end of file.The DGN file ended before ODA finished reading it. This usually means the file is truncated, incomplete, or corrupt. Re-export or recopy the source file and confirm it opens in the original CAD application.Error code = 431, Description = Error encrypting data.ODA reported an encryption-related read failure. This can happen when the file is protected, encrypted, or otherwise unreadable by the converter. Confirm whether the file requires credentials, is export-protected, or can be opened and resaved without protection.
These messages describe why the source DGN could not be read; they do not mean USD export started and failed. To collect more conversion detail, enable verboseLogging. When using the CAD Converter service, the same message is returned in the HTTP error response detail field.
Complete Example converter_config_example.json:#
{
"applyGlobalOrigin": false,
"attributes": [
{
"name": "foo1",
"prefix": "prefix",
"converted_name": "foobar1"
},
{
"name": "foo2",
"prefix": "",
"converted_name": "foobar2"
},
{
"name": "foo3",
"converted_name": "foobar3"
}
],
"betweenKnots": 2,
"meshConversionStyle": 2,
"curveConversionStyle": 0,
"text3dConversionStyle": 0,
"text3dWidth": 0.05,
"curveSamplePoints": 8,
"convertElementId": true,
"convertHidden": false,
"fallbackCurveWidth": -1,
"geometryAttributeStyle": 1,
"gridAspectRatio": 0,
"hiddenLevels": [
"level_foo",
"*vel_foo",
"level_bar*",
"*vel_bar*"
],
"instancingStyle": 1,
"levelExcludeHidden": false,
"levelExcludes": [],
"levelFilterStyle": 0,
"levelIncludes": [
"Default",
"level_foo",
"*vel_foo",
"level_ba*",
"*vel_ba*"
],
"materialType": 1,
"maxFacetEdgeLength": 0,
"maxNumGridLines": 10000,
"mergeCurves": true,
"mergeMeshes": true,
"mergedAttributeStyle": 0,
"modelNamePatterns": [
"Default",
"model_foo",
"*del_foo",
"model_ba*",
"*del_ba*"
],
"normalTolerance": 15,
"pointsPerEdge": 0,
"progressLogging": true,
"surfaceTolerance": 0.02,
"surfaceToleranceUnit": 0.0,
"triangulate": true,
"verboseLogging": false,
"sceneOpConfig": "",
"sceneOpGenerateUVs": false,
"sceneOpUpAxis": 0,
"sceneOpMetersPerUnit": 0.0
}