Conversion results#

This page describes the native DGN converter Result API used by the extension. For the extension’s (output_url, ConverterStatus) return value and diagnostic message, see Conversion results in the extension. The service exposes the conversion status and formatted diagnostics rather than the native Result object. In particular, the extension supplies an incomplete-output message even though the native legacy tuple can contain an empty message.

Purpose#

Conversion functions return a Result object. The result reports the conversion outcome and the diagnostics recorded for that conversion.

Use the status and diagnostics to assess the output. Use Conversion issues to interpret each diagnostic code and subject.

Interpret the status#

Use getStatus() in C++ or Python to get the ResultStatus value. You can also use the direct status methods.

Status	Meaning	Diagnostic structure
`eSuccess`	The converter completed without a recorded error or failure.	The result has no errors or failure. It can have warnings.
`eIncomplete`	The converter produced usable output, but some requested content changed or is missing.	The result has errors but no failure. It can have warnings.
`eFailure`	The converter did not produce the requested usable output.	The result has a failure. It can also have warnings and errors.

Intentional omissions from conversion parameters do not make a result incomplete.

The status methods have these meanings:

isSuccess() returns true for eSuccess.
isIncomplete() returns true for eIncomplete.
isFailure() returns true for eFailure.

The three methods are mutually exclusive. Exactly one method returns true for each result.

Reporting coverage#

The result currently includes parameter diagnostics, input and output validation failures, and failures reported by conversion steps.

Some conditions appear only in the conversion log. For example, unsupported elements can be omitted without an error in the result. These omissions do not currently change a successful result to eIncomplete.

A successful result therefore does not guarantee complete or accurate output. Inspect the conversion log when you need to check output completeness. Inspect warnings for recovery that can affect the output, such as replacement units.

Diagnostic logging#

The converter logs issues when it records them in the result. Warnings use warning-level diagnostics. Errors and failures use error-level diagnostics. This reporting is independent of progressLogging and verboseLogging. Inspection of a result does not log its issues again.

Boolean value#

A Result converts to true only for eSuccess. Incomplete and failed results convert to false.

Use a direct status method when incomplete output needs different handling from failed output.

result = omni.converter.dgn.convert(parameters, input_path, output_path)

if result.isFailure():
    handle_failure(result.getFailure())
elif result.isIncomplete():
    inspect_output(result.getErrors())
else:
    use_output()

Output after failure#

A failed result does not establish whether an output file exists or belongs to this conversion attempt. For example, a validation or stage-creation failure leaves an existing destination file untouched. Do not delete an existing destination solely because the result indicates failure.

Conversion into a supplied layer can leave partial edits after failure. File conversion can leave copied textures or a text layer if a later export fails. The result does not guarantee rollback of these changes.

Warnings#

Use getWarnings() in C++ or Python to inspect warnings. A warning describes a condition or recovery that does not change the result status.

Every status can include warnings. For example, the converter can ignore a disabled parameter and still return eSuccess. Warnings can also identify uncertainty in the output. An eInvalidModelUnits warning means that conversion uses centimeters, but the content’s scale may be incorrect.

Errors#

Use getErrors() in C++ or Python to inspect errors. An error describes requested work that the converter omitted, changed, or could not complete.

One or more errors produce eIncomplete when the result has no failure. A failed result can also contain errors that provide details about the failure.

Failure#

Use getFailure() in C++ or Python to inspect the failure. The failure is the primary or aggregate reason that the conversion stopped.

Only a failed result has a failure issue. Otherwise, getFailure() returns an empty Issue whose hasIssue() method returns false. In Python, this value is an Issue object, not None. The failure message is the overall failure description. The converter stores the failure separately from the supporting errors.

Some failures summarize multiple errors. For example, an eInvalidParameters failure can summarize several eInvalidParameter errors.

Access diagnostics#

In C++, getWarnings() and getErrors() return const references to Issues, an alias for std::vector<Issue>. getFailure() returns a const reference to the stored failure. The result owns these diagnostics. Copy an issue if you need it after the result is destroyed or changed.

In Python, the getters return independent copies of the issues and lists. Changes to a returned list or an issue’s subject do not change the result. These copies remain valid after the result is destroyed.

Interpret an issue#

Warnings, errors, and failures are all Issue objects. Each issue provides a code, message, and subject.

Use the code for program logic. Use formatIssue(issue) for logs or user-facing diagnostic output that includes the object’s identity. Use the message when the subject is already displayed separately. Use the subject to identify the object associated with the issue.

Message text is not a stable identifier. Do not use message text for program logic.

See Conversion issues for each code and its subject contract.

C++ example#

const omni::converter::dgn::Result result = converter.convert(inputPath, outputPath);

for (const omni::converter::dgn::Issue& warning : result.getWarnings())
{
    handleWarning(warning.code, warning.subject, warning.message);
}

if (result.isFailure())
{
    const omni::converter::dgn::Issue& failure = result.getFailure();
    handleFailure(failure.code, failure.subject, failure.message);

    for (const omni::converter::dgn::Issue& error : result.getErrors())
    {
        handleError(error.code, error.subject, error.message);
    }
}
else if (result.isIncomplete())
{
    handleIncompleteOutput(result.getErrors());
}
else
{
    useOutput();
}

Python example#

result = omni.converter.dgn.convert(parameters, input_path, output_path)

for warning in result.getWarnings():
    handle_warning(warning.code, warning.subject, warning.message)

if result.isFailure():
    failure = result.getFailure()
    handle_failure(failure.code, failure.subject, failure.message)

    for error in result.getErrors():
        handle_error(error.code, error.subject, error.message)
elif result.isIncomplete():
    handle_incomplete_output(result.getErrors())
else:
    use_output()

Status labels#

getResultStatusLabel() returns a brief label for a ResultStatus value. The labels are Success, Incomplete, and Failure.

An unrecognized value uses the Unsupported label. Python also returns the label when code calls str() on a status.

Labels are for logs and diagnostic output. They are not stable API identifiers.

Stable numeric values#

The status numeric values are stable public API values. The numeric order does not define outcome severity.

Status	Value
`eSuccess`	0
`eFailure`	1
`eIncomplete`	2

Legacy Python tuple access#

Earlier Python releases returned each conversion result as a two-item tuple. The Python Result binding temporarily supports tuple unpacking and indexing.

status_value, failure_message = result
status_value = result[0]
failure_message = result[1]

The first item is the numeric ResultStatus: 0 for success, 1 for failure, or 2 for incomplete output. The second item contains formatIssue(result.getFailure()) for a failed result, including its subject when available. It is empty for successful and incomplete results.

This access style is deprecated and will be removed after the compatibility period. New Python code must use the Result methods.

The C++ Result class does not provide tuple access or structured binding.