HOOPS Core Converter#

The HOOPS core converter is a Kit extension that converts many CAD and interchange formats to USD. It is the GUI-less backend for omni.kit.converter.hoops.

Quick Start#

Use this recipe when running inside Kit with omni.kit.converter.hoops_core enabled.

import omni.converter.hoops
from omni.kit.converter.hoops_core import HoopsOptions, get_instance

converter = get_instance()
if converter is None:
    raise RuntimeError("omni.kit.converter.hoops_core is not loaded")

options = HoopsOptions()
options.instancingStyle = omni.converter.hoops.InstancingStyle.eInstanceableReference
options.compositionStyle = omni.converter.hoops.CompositionStyle.eNone
options.filterStyle = omni.converter.hoops.FilterStyle.eOmit
options.tessLOD = 2
options.useMaterials = True

output_url, status = await converter.create_converter_task(
    "C:/data/assembly.sldasm",
    "C:/data/assembly.usd",
    options.toArgs(),
)

if status.error_code != 0 or not output_url:
    raise RuntimeError(status.error_msg)

Success means status.error_code == 0 and output_url is non-empty.

Prerequisites#

Run inside a Kit Python environment where omni.kit.converter.hoops_core and its native HOOPS Exchange libraries are loaded.
The input CAD file must exist locally or be resolvable through supported Omniverse/Nucleus URL handling.
The output folder must be writable locally or resolvable through supported Omniverse/Nucleus URL handling.
create_converter_task(...) is async; call it from an async context.

What This Converter Does#

Reads CAD and interchange files through the HOOPS Exchange SDK and writes USD output. It handles assemblies, optional USD composition arcs, instancing, tessellation level of detail, materials, normals, hidden entity filtering, PMI/metadata, curves, physics attributes, Creo view layers, and optional Scene Optimizer post-processing.

HOOPS also supports JT and DGN as fallback formats, but the dedicated jt_core and dgn_core converters have higher priority for their native formats.

Input and Output Formats#

Format family	Extensions
CATIA V5	`.CATPart`, `.CATProduct`, `.CGR`
IFC	`.ifc`, `.ifczip`
NX	`.prt`
Parasolid	`.xmt`, `.x_t`, `.x_b`, `.xmt_txt`
SolidWorks	`.sldprt`, `.sldasm`
STL	`.stl`
Autodesk Inventor	`.IPT`, `.IAM`
CATIA V6 / 3DExperience	`.3DXML`
AutoCAD 3D	`.DWG`, `.DXF`
Creo / Pro-E	`.ASM`, `.PRT`, including numbered suffixes
Revit	`.RVT`, `.RFA`
Solid Edge	`.ASM`, `.PAR`, `.PWD`, `.PSM`
STEP / IGES	`.STEP`, `.STP`, `.IGES`, `.IGS`
Rhino	`.3dm`
Collada	`.dae`
FBX	`.fbx`
OBJ	`.obj`
3DS	`.3ds`
3MF	`.3mf`
glTF / GLB	`.GLTF`, `.GLB`
ACIS	`.SAT`, `.SAB`
Fallback JT / DGN	`.jt`, `.DGN`

Output	Notes
`.usd`, `.usda`, `.usdc`	USD output path supplied by the caller.

Conversion APIs#

Use these APIs to perform conversions, in this order of preference:

API	When to use
`get_instance().create_converter_task(input_path, output_path, options.toArgs())`	Preferred core extension API when calling the loaded extension from Python. Returns `(output_url, ConverterStatus)` and handles local and Nucleus paths.
`HoopsConverterHelper.create_import_task(input_path, output_path, file_format_args)`	Lower-level helper used by the extension implementation. Use only when bypassing extension registration intentionally.
`omni.converter.hoops.Converter(options).convert(...)`	Backend SDK wrapper for local conversion paths. Use only when you do not need the core extension’s Nucleus handling, output copying, logging, and Scene Optimizer post-processing.
`is_format_supported(input_file_path)`	Format support helper that checks a path against `HOOPS_CORE_FILTER_DATA`.

Minimal direct API call:

import omni.converter.hoops
from omni.kit.converter.hoops_core import HoopsOptions, get_instance

converter = get_instance()
options = HoopsOptions()
options.instancingStyle = omni.converter.hoops.InstancingStyle.eInstanceableReference
options.compositionStyle = omni.converter.hoops.CompositionStyle.eNone
options.filterStyle = omni.converter.hoops.FilterStyle.eOmit
options.tessLOD = 2
options.useMaterials = True

output_url, status = await converter.create_converter_task(
    "C:/data/assembly.sldasm",
    "C:/data/assembly.usd",
    options.toArgs(),
)

For direct backend conversion with local paths only, pass the options object itself:

import omni.converter.hoops
from omni.kit.converter.hoops_core import HoopsOptions

options = HoopsOptions()
options.instancingStyle = omni.converter.hoops.InstancingStyle.eInstanceableReference
options.compositionStyle = omni.converter.hoops.CompositionStyle.eNone
options.filterStyle = omni.converter.hoops.FilterStyle.eOmit
options.tessLOD = 2
options.useMaterials = True

converter = omni.converter.hoops.Converter(options)
error_code, error_msg = converter.convert("C:/data/assembly.sldasm", "C:/data/assembly.usd", {})

Converter Options#

Configure these as properties on HoopsOptions. Pass options.toArgs() to create_converter_task(...); pass options directly only when calling omni.converter.hoops.Converter(options).

Enum-valued pybind property setters require enum objects, not raw integers. For example, set options.filterStyle = omni.converter.hoops.FilterStyle.eOmit and options.instancingStyle = omni.converter.hoops.InstancingStyle.eInstanceableReference. Numeric enum values are valid in JSON/dict config parsed by HoopsOptions.parse(...) and in the serialized dict returned by options.toArgs().

`HoopsOptions` Property	Default	Description
`instancing`	`true`	Enable USD references for instancing. Prefer `instancingStyle` when selecting an instancing mode.
`instancingStyle`	`2` in code, docs list `1`	Instancing mode: `0` none, `1` reference, `2` instanceable reference.
`compositionStyle`	`0`	Assembly composition: `0` monolithic, `1` USD references, `2` USD payloads.
`filterStyle`	`1`	Hidden/filtered entity handling: `0` none, `1` omit, `2` hide, `3` deactivate.
`globalXforms`	`false`	When instancing is disabled, choose global transforms instead of local transforms.
`tessLOD`	`2`	Tessellation LOD preset from `0` extra low to `4` extra high.
`accurateSurfaceCurvatures`	`true`	Respect surface curvature to control triangle elongation.
`accurateTessellation`	`false`	Tessellate for analysis when true; keep false unless the HOOPS invalid-index issue is resolved.
`dedup`	`true`	Weld mesh vertices with identical position and normal.
`useMaterials`	`true`	Create USD materials; false writes colors as `displayColor`.
`materialType`	`1`	Material output: `0` none, `1` USD Preview Surface, `2` OmniPBR plus USD Preview Surface.
`useNormals`	`true`	Write normals to USD.
`omitHiddenOnLoad`	`true`	Omit hidden elements at load time when they would be omitted during conversion.
`reportProgress`	`true`	Report import/export progress.
`reportProgressFreq`	`4.0`	Progress update frequency in Hz. Range `[1.0, 10.0]`.
`convertCurves`	`false`	Convert curve elements to USD BasisCurves.
`convertMetadata`	`false`	Import metadata, including PMI, as USD attributes.
`upAxis`	`0`	Override output up-axis: `0` file/converter default, `1` Y-up, `2` Z-up.
`convertPhysicsData`	`false`	Compute B-rep physical properties and author `omni:hoops:physics:*` attributes.
`physicsAccuracyLevel`	`0.99`	Physical property accuracy from `0.0` to `1.0`; only used when `convertPhysicsData` is true.
`physicsUseGeometryOnRiBRep`	`false`	Use exact B-rep geometry instead of tessellation for physical property computation.
`viewLayerName`	`""`	Creo simplified representation or view layer to extract for `.ASM` or `.PRT`.

Development Rules#

Keep HoopsOptions in python/impl/options.py as the single source for option parsing.
When adding or changing an option, update python/impl/options.py, docs/Overview.md, and tests together.
Treat HOOPS_CORE_FILTER_DATA as both user-facing extension manager data and core converter format support data.
Preserve JT and DGN fallback support while respecting higher-priority dedicated converters.
Keep platform-specific native library packaging intact, including A3DLIBS on Windows.
Keep creator metadata behavior unless replacing it with equivalent extension/backend version metadata.

Verification#

Build and run the repo test suite from the repository root:

./repo.bat build -xrd
./repo.bat test

For focused changes, run the generated omni.kit.converter.hoops_core extension tests after building, or cover the affected tests under source/extensions/omni.kit.converter.hoops_core/python/tests.

Codebase Map#

File	Role
`python/impl/extension.py`	`HoopsCoreConverter`, extension lifecycle, task creation, format support helper.
`python/impl/options.py`	`HoopsOptions`, option defaults, parsing, aliases.
`python/impl/filters.py`	Supported formats and display filters.
`python/tests/`	Conversion tests.
`docs/Overview.md`	User-facing behavior and converter option documentation.
`docs/Known_Issues.md`	HOOPS-specific known limitations.
`config/extension.toml`	Package metadata, native libraries, tests.