JT Core Converter#

The JT core converter is a Kit extension that converts Siemens JT files to USD. It is the GUI-less backend for omni.kit.converter.jt.

Quick Start#

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

import omni.converter.jtk
from omni.kit.converter.jt_core import JTConverterOptions, get_instance

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

options = JTConverterOptions()
options.instancingStyle = omni.converter.jtk.InstancingStyle.eInstanceableReference
options.layerFilterStyle = omni.converter.jtk.LayerFilterStyle.eOmit
options.materialType = omni.converter.jtk.MaterialType.ePreviewSurface

output_url, status = await converter.create_converter_task(
    "C:/data/model.jt",
    "C:/data/model.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.jt_core and its native JTTK libraries are loaded.

  • The input .jt 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 .jt files through the Siemens JT Open Toolkit (JTTK) SDK and writes USD output. The converter handles JT hierarchy, parts, assemblies, tessellation data, materials, hidden-layer handling, instancing, up-axis and unit overrides, and optional Scene Optimizer post-processing.

JT-specific routing has priority over HOOPS for .jt files. On Linux ARM64, JTTK is not supported, so HOOPS is the fallback converter for JT.

Input and Output Formats#

Format

Notes

.jt

JT input handled by omni.converter.jtk; filter priority is higher than HOOPS for JT.

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.

JtConverterHelper.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.jtk.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.

Minimal direct API call:

import omni.converter.jtk
from omni.kit.converter.jt_core import JTConverterOptions, get_instance

converter = get_instance()
options = JTConverterOptions()
options.instancingStyle = omni.converter.jtk.InstancingStyle.eInstanceableReference
options.layerFilterStyle = omni.converter.jtk.LayerFilterStyle.eOmit
options.materialType = omni.converter.jtk.MaterialType.ePreviewSurface

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

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

import omni.converter.jtk
from omni.kit.converter.jt_core import JTConverterOptions

options = JTConverterOptions()
options.instancingStyle = omni.converter.jtk.InstancingStyle.eInstanceableReference
options.layerFilterStyle = omni.converter.jtk.LayerFilterStyle.eOmit
options.materialType = omni.converter.jtk.MaterialType.ePreviewSurface

converter = omni.converter.jtk.Converter(options)
error_code, error_msg = converter.convert("C:/data/model.jt", "C:/data/model.usd", {})

Converter Options#

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

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

JTConverterOptions Property

Default

Description

convertCurves

false

Convert JT curve elements to USD BasisCurves.

instancingStyle

2 in code, docs list 0

Instancing mode: 0 none, 1 reference, 2 instanceable reference.

materialType

1

Material output: 0 none, 1 USD Preview Surface, 2 OmniPBR plus USD Preview Surface.

overrideTessellationGeometry

false

Ignore embedded tessellation geometry and explicitly tessellate surface geometry.

overrideTessellationParameters

false

Ignore embedded tessellation parameters and use fallback tessellation parameters.

fallbackTessParamAngular

converter default

Maximum angle in degrees between adjacent tessellated curve segments. Range [0.0, 90.0].

fallbackTessParamChordal

converter default

Maximum deviation distance between tessellated segment and source curve. Range [0.0, 1.0].

fallbackTessParamHoleRemovalFraction

converter default

Fraction of part bounding-box diagonal used to suppress holes/arcs. 0.0 disables suppression.

fallbackTessParamLength

converter default

Maximum edge length for fallback tessellation. Non-negative.

fallbackTessParamMaxAspect

converter default

Maximum tessellated element aspect ratio. Non-negative.

fallbackTessParamMinAngle

converter default

Minimum allowable angle in radians. Non-negative.

fallbackTessParamMinEdgeLength

converter default

Minimum tessellation edge length. Non-negative.

fallbackTessParamTrimSuppress

false

Enable trim suppression during fallback tessellation.

flatten

false

Flatten converted USD hierarchy into a single level of geometry.

layerFilterStyle

1

Hidden/filtered layer handling: 0 none, 1 omit, 2 deactivate, 3 hide.

progressLogging

true

Emit progress logging during conversion.

Development Rules#

  • Keep JTConverterOptions 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.

  • Preserve .jt filter priority over HOOPS unless intentionally changing converter routing.

  • Treat native library entries in config/extension.template.toml as packaging-critical.

  • 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.jt_core extension tests after building, or cover the affected tests under source/extensions/omni.kit.converter.jt_core/python/tests.

The configured Python coverage threshold for this extension is 80%.

Codebase Map#

File

Role

python/impl/extension.py

JtCoreConverterExt, extension lifecycle, task creation.

python/impl/options.py

JTConverterOptions, option defaults, parsing, aliases.

python/impl/filters.py

JT file filter and routing priority.

python/tests/

Core converter, parameter, and memory leak tests.

docs/Overview.md

User-facing behavior and converter option documentation.

config/extension.template.toml

Package metadata, native libraries, tests, coverage settings.