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:

Direct API Calls: Call the service directly from Python code or other extensions
Batch Processing: Use for automated conversion of multiple CAD files
Integration: Integrate with other Omniverse services and extensions
Container Deployment: Deploy as a service in CAD containers for scalable processing
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: { "instancing": true }
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": { "instancing": true }
}

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": {
    "instancing": true,
    "bOptimize": true,
    "convertHidden": false,
    "dMetersPerUnit": 1.0,
    "iUpAxis": 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
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
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
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,
  "comment": "File /path/to/file.sldprt was successfully converted to /path/to/output.usd."
}

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

RUNNING: Job is currently in progress
COMPLETED: Job completed successfully
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#

The omni.services.convert.cad and related CAD converter Extensions are Omniverse Core Extensions. Do not redistribute or sublicense without express permission or agreement. Please read the Omniverse License Agreements for detailed license information.