Overview#

omni.services.convert.cad is a Kit services extension that provides a service for batch conversion of CAD files to USD using various CAD converter extensions. This service extension leverages the underlying CAD converter capabilities to convert files such as SLDPRT, DGN, JT, and other supported CAD formats to USD format. Refer to omni.kit.converter.cad docs for list of all supported CAD files.

Upon loading, it registers with the CAD Converter service, allowing other extensions and external processes to utilize its conversion capabilities through a standardized API interface.

Known limitations#

JT conversions would go through omni.kit.converter.hoops_core instead of omni.kit.converter.jt_core extension on linux-aarch64 platform because JT Open Toolkit isn’t supported on Linux ARM.

About#

The CAD Converter Service Extension provides an easy-to-use API to call into the CAD conversion service for converting various CAD file formats to USD.

Usage#

The CAD Converter Service Extension can be used in several ways:

  1. Direct API Calls: Call the service directly from Python code or other extensions

  2. Batch Processing: Use for automated conversion of multiple CAD files

  3. Integration: Integrate with other Omniverse services and extensions

  4. Container Deployment: Deploy as a service in CAD containers for scalable processing

  5. Farm Setup: Use with Omniverse TAAS and Farm for distributed processing

The service provides a robust and flexible solution for converting various CAD file formats to USD, making it easier to work with different CAD types in the Omniverse ecosystem.

For detailed usage instructions, see the Usage Guide.

Supported File Formats#

The CAD Converter Service supports conversion from the following file formats to USD:

  • DGN (.dgn)

  • JT (.jt)

  • HOOPS Supported Formats: Various CAD formats supported by HOOPS Exchange

Note: For a complete list of supported CAD files, refer to omni.kit.converter.cad documentation.

CAD CONVERTER SERVICE REQUEST FORMAT#

The CAD Converter Service accepts requests in JSON format with the following structure:

Request Arguments:#

Required Arguments:#

import_path

  • Description: Full path to the source CAD file to convert

  • Data Format: string

  • Example: "/path/to/model.sldprt"

output_path

  • Description: Full path to the output USD file

  • Data Format: string

  • Example: "/path/to/output/model.usd"

Optional Arguments:#

converter_options

  • Description: JSON object containing conversion configuration options

  • Data Format: object

  • Default Value: {}

  • Example: { "instancingStyle": 1 }

  • Note: This option takes precedence over the config_path option

config_path

  • Description: Path to the JSON config file (Optional and deprecated)

  • Data Format: string

  • Default Value: ""

  • Example: "/path/to/config.json"

Sample Request Examples#

Minimal Conversion Request:#

{
  "import_path": "/ANCHOR.sldprt",
  "output_path": "/tmp/testing/ANCHOR.usd"
}

Basic Conversion Request:#

{
  "import_path": "/ANCHOR.sldprt",
  "output_path": "/tmp/testing/ANCHOR.usd",
  "converter_options": { "instancingStyle": 1 }
}

Conversion with Config File:#

{
  "import_path": "/tmp/input_file.dgn",
  "output_path": "/tmp/output_file.usd",
  "config_path": "/tmp/sample_config.json"
}

Advanced Conversion Request:#

{
  "import_path": "/path/to/complex_model.sldprt",
  "output_path": "/path/to/output/complex_model.usd",
  "converter_options": {
    "instancingStyle": 1,
    "sceneOpGenerateUVs": true,
    "convertHidden": false,
    "sceneOpMetersPerUnit": 1.0,
    "sceneOpUpAxis": 1
  }
}

CONVERTER-SPECIFIC OPTIONS AND CONFIGURATION#

Conversion options are configured by supplying a JSON object in the converter_options parameter. The available configuration options depend on the specific CAD converter being used.

Converter-Specific Configuration Options:#

HOOPS Core Converter: Refer to omni.kit.converter.hoops_core for configuration options.

JT Core Converter: Refer to omni.kit.converter.jt_core for configuration options.

DGN Core Converter: Refer to omni.kit.converter.dgn_core for configuration options.

HTTP ENDPOINTS#

The CAD Converter Service provides the following HTTP endpoints:

Health Check#

Endpoint: GET /convert/cad/health

Description: Check if the service is alive and responding.

Response Codes:

  • 200 OK: Service is running

Response JSON:

{
  "status": "OK"
}

Readiness Check#

Endpoint: GET /convert/cad/ready

Description: Check if the service is ready to accept new conversion requests. Used by Kubernetes readiness probes.

Response Codes:

  • 200 OK: Service is ready or not ready

Response JSON:

{
  "ready": true
}

Service Status#

Endpoint: GET /convert/cad/status

Description: Get the current state of the conversion service, including active jobs and available slots.

Response Codes:

  • 200 OK: Status retrieved successfully

Response JSON:

{
  "state": "IDLE",
  "active_jobs": 0,
  "max_job_count": 5,
  "available_slots": 5,
  "current_jobs": [
    {
      "job_id": "<job_id>",
      "file_path": "/path/to/file.sldprt",
      "progress": 0.45,
      "start_time": "<job_start_time>"
    }
  ]
}

Status Values:

  • IDLE: No jobs currently running

  • RUNNING: One or more jobs in progress

Job Status#

Endpoint: GET /convert/cad/status/{job_id}

Description: Get the status of a specific conversion job by job_id. Only active (currently running) jobs can be queried via this endpoint. For completed or failed jobs, use the /convert/cad/history endpoint.

Response Codes:

  • 200 OK: Job status retrieved successfully

  • 404 NOT FOUND: Job with the specified ID not found (job may have completed or never existed)

Response JSON:

{
  "job_id": "<job_id>",
  "file_path": "/path/to/file.sldprt",
  "state": "RUNNING",
  "progress": 0.45,
  "error_message": "",
  "start_time": "<job_start_time>"
}

Job State Values:

  • RUNNING: Job is currently in progress

  • COMPLETED: Job completed successfully, possibly with warnings

  • INCOMPLETE: DGN output is available, but some content could not be converted

  • ERROR: Job encountered an error

Job History#

Endpoint: GET /convert/cad/history

Description: Get the history of completed and failed conversion jobs from the current session.

Response Codes:

  • 200 OK: History retrieved successfully

Response JSON:

{
  "max_session_history_count": 5,
  "jobs": [
    {
      "job_id": "<job_1_id>",
      "file_path": "/path/to/file.sldprt",
      "output_path": "/path/to/output.usd",
      "state": "COMPLETED",
      "progress": 1.0,
      "error_message": "",
      "start_time": "<job_1_start_time>",
      "end_time": "<job_1_end_time>"
    }
  ]
}

Job State Values:

  • RUNNING: Job was running (should not appear in history)

  • COMPLETED: Job completed successfully, possibly with warnings

  • INCOMPLETE: DGN output is available, but some content could not be converted

  • ERROR: Job encountered an error

Convert CAD File#

Endpoint: POST /convert/cad/process

Description: Convert a CAD file to USD format.

Request Body: See CAD CONVERTER SERVICE REQUEST FORMAT section above.

Response Codes:

  • 200 OK: Conversion completed successfully or produced usable incomplete DGN output

  • 503 SERVICE UNAVAILABLE: All conversion slots are full

  • 422 UNPROCESSABLE ENTITY: Invalid file path or unsupported output format

  • 500 INTERNAL SERVER ERROR: Conversion failed with an error

Response JSON:

{
  "status": 200,
  "conversion_status": 0,
  "comment": "File /path/to/file.sldprt was successfully converted to /path/to/output.usd."
}

For DGN, conversion_status is 0 for success (possibly with warnings) or 2 for usable incomplete output. The comment includes formatted diagnostics with individual issue codes and subjects. Inspect incomplete output and its diagnostics before accepting it. History stores these details in error_message, including warnings on completed jobs.

Error Response JSON: Fatal conversion failures return HTTP 500 with a detail string in the form Error[<overall status>]: <diagnostics>. DGN backend failures use status 1; extension failures can use -1. Individual DGN issue codes inside the diagnostics identify the problem and are separate from the overall status. They are converter-owned codes, not raw ODA result numbers.

For read failures and practical checks, see the DGN Converter Core troubleshooting section. For invalid filter-pattern fallbacks and the response contract, see DGN results and diagnostics.

Job State Values (for jobs created by this endpoint):

  • RUNNING: Job is currently in progress

  • COMPLETED: Job completed successfully, possibly with warnings

  • INCOMPLETE: DGN output is available, but some content could not be converted

  • ERROR: Job encountered an error

Environment Variables#

The following environment variables can be used to override default service behavior:

  • CAD_SERVICE_MAX_JOB_COUNT: Maximum number of concurrent conversion jobs allowed (default: 5)

  • CAD_SERVICE_MAX_SESSION_HISTORY_COUNT: Maximum number of jobs kept in session history (default: 5)

Detailed Usage Instructions#

For comprehensive usage instructions, including:

Please refer to the Usage Guide.

Licensing Terms of Use and Third-Party Notices#

omni.services.convert.cad is governed by the NVIDIA Software License Agreement and the Product Specific Terms for NVIDIA AI Products. Customers may redistribute the Omniverse CAD Converter as permitted by those terms. By downloading or using NVIDIA Omniverse, you agree to the terms. See the Omniverse License Agreement.