# Output Files

The outputFiles field (dictionary) specifies which results you are expecting from the Engine API, and how you will retrieve them. A fixed set of output files is supported (see below). Each output file is specified in the same way, always specifying the desired extension and optionally specifying the upload URL. Additional options may be present for specific output files.

# How to retrieve the data?

# A. Downloading from Relu-generated pre-signed download URLs

If you leave the uploadUrl field empty for any output file, the Engine will provide you with a pre-signed downloadUrl for that file. The URL is provided in the JSON response when fetching the job status (through polling or a webhook). This approach is followed in the quick start example.

# B. Providing pre-signed upload URLs

Alternatively, you can provide an uploadUrl for the output file. This URL should point to the location where the Engine can upload the file to and should be pre-signed (for a limited time). This approach is easy to set up if you already have the files stored in a cloud storage service like Amazon S3 or Azure Blob Storage.

We recommend this approach, as it avoids wasting resources and time on uploading the files.

# Supported Output Files

# 3D Models meshes

Mesh files are the most common output files, providing you with a 3D model of the segmented structure(s). You can specify a list of required mesh outputs, where each mesh is specified by its extension and a list of structures.

The following file extensions are supported.

Extension	Description
`.stl`	An STL mesh file.
`.ply`	A PLY mesh file.
`.obj`	An OBJ mesh file.
`.drc`	A Draco-compressed mesh file.

The following structures are supported. Note that you can either request a mesh for a single structure (e.g. structures: ["mandible"]) or combine multiple structures within the same mesh (e.g. structures: ["mandible", "skull", "tooth11"]). Sometimes, shorthands are available (e.g. all_nerves or all_permanent_teeth).

Structure	Description	Required Input
`mandible`	The mandibular bone.	CBCT
`maxillary` `skull`	The maxillary bone (see skull or maxillary-complex for the difference).	CBCT
`left_nerve` `right_nerve` `all_nerves`	The nerve canals in the mandibular bone.	CBCT
`left_maxillary_sinus` `right_maxillary_sinus` `all_maxillary_sinuses`	The maxillary sinuses.	CBCT
`airway`	The pharynx (airway).	CBCT
`soft_tissue`	The soft tissue.	CBCT
`tooth11` ... `tooth48` `permanent_upper_teeth` `permanent_lower_teeth` `all_permanent_teeth`	Permanent teeth.	CBCT
`tooth51` ... `tooth85` `deciduous_upper_teeth` `deciduous_lower_teeth` `all_deciduous_teeth`	Deciduous teeth.	CBCT
`upper_teeth` `lower_teeth` `all_teeth`	Shorthands for all teeth (permanent and deciduous).	CBCT
`upper_gingiva` `lower_gingiva`	The gingiva (gum).	IOS
`crown11` ... `crown48` `upper_crowns` `lower_crowns` `all_crowns`	Crowns.	IOS
`closed_crown11` ... `closed_crown48` `upper_closed_crowns` `lower_closed_crowns` `all_closed_crowns`	Crowns which are automatically closed at the root, resulting in a better-looking, closed mesh.	IOS
`fused_tooth11` ... `fused_tooth48` `upper_fused_teeth` `lower_fused_teeth` `all_fused_teeth`	Fused IOS crowns with CBCT roots.	CBCT + IOS

For CBCT meshes, it is possible to exclude (i.e., boolean subtract) certain structures from the mesh. This can be useful to for instance generate a mesh of the mandible with the teeth sockets visible as holes (intruded). For a list of structures that can be excluded, refer to the API spec (under excludedStructures).

It is possible to change certain properties of mesh files, e.g. by setting smoothing and decimation options (explained in the job options section).

# Registration

IOS Registration matrix registration_matrix_upper registration_matrix_lower

Automatic registration (matching) of the Intra-oral scan to the Cone-Beam CT-scan. Returns the transformation matrix that should be applied to the IOS to align it with the CBCT scan. The inverse matrix can be used to move any CBCT mesh (e.g., mandible segmentation) to align with the IOS.

The result is a 4x4 matrix representation in JSON format.

Registered IOS scans registered_ios_upper registered_ios_lower

Automatic registration (matching) of the Intra-oral scan to the Cone-Beam CT-scan. Returns the original IOS scan transformed into a new position and orientation, such that it is aligned with the CBCT scan.

The following file extensions are supported.

Extension	Description
`.stl`	An STL mesh file.
`.ply`	A PLY mesh file.
`.obj`	An OBJ mesh file.
`.drc`	A Draco-compressed mesh file.

We suggest to rather use the IOS Registration Matrix output, as it allows you to not store the Intra-oral scan twice, and gives you more flexibility to move objects to align them to the CBCT or IOS.

Facial Scan Registration registration_facial

Automatic registration (matching) of the facial scan to the Cone-Beam CT-scan. Returns the transformation matrix that should be applied to the facial scan to align it with the CBCT scan.

The result is a 4x4 matrix representation in JSON format.

# Nerve Tracing point_path_left_nerve point_path_right_nerve

Automatic computation of the nerve canal paths in the mandibular bone. Returns a list of points and radiuses, representing the nerve canal path.

The result is a list of points with radiuses in JSON format.

# Panoramic arch panoramic_arch

This feature enables the automatic computation of panoramic arches based on DICOM data. The output includes six distinct arches located at the following anatomical positions:

Zygomatic bone
Roots of the upper teeth
Crowns of the upper teeth
Crowns of the lower teeth
Roots of the lower teeth
Lower half of the mandibular nerve

The output is provided as a JSON file containing six lists, with each list corresponding to one arch. Each arch list contains a series of points representing that arch. If a particular arch is not detected, an empty list will be returned for that arch.

If you do not require all six arches, you can specify which arches to compute using the requestedArches parameter. By default, all six arches are calculated. The default value for this parameter is:

[
    "zygomatic_arch",
    "upper_teeth_roots_arch",
    "upper_teeth_crowns_arch",
    "lower_teeth_crowns_arch",
    "lower_teeth_roots_arch",
    "mandibular_canal_arch"
]

The number of points returned for each arch can be customized using the nbOfPoints parameter. By default, 11 points are returned per arch. If you require the maximum number of points (with no simplification), set this parameter to None.

If the angulate parameter is set to True (default is False), the first three arches (zygomatic arch, upper teeth roots, and upper teeth crowns) will be aligned to a plane parallel to the plane of the upper teeth crowns. Similarly, the last three arches (lower teeth crowns, lower teeth roots, and mandibular canal) will be aligned to the plane of the lower teeth crowns. All six planes will be parallel if the angle between the top three and bottom three arches is less than the angleThreshold.

forceCenterPoint: By default, this is set to False. If set to True, the middle point of each arch will be forced to the highest central point. In this case, the number of points returned will always be odd.
inWorldCoordinates: By default, this is set to True, meaning the arch points are returned in world space coordinates. If you prefer to receive the points in voxel coordinates, set this parameter to False.

# IOS Teeth landmarks ios_landmarks_upper ios_landmarks_lower

Automatic computation of key landmarks of each tooth on the intra-oral scan.

The result is a JSON file containing the following landmarks for each segmented tooth:

origin (center)
tooth axis (long axis)
mesial-point
distal-point

This output is only available in version 24.06 and higher of the Engine API.

# IOS with base (cleaned) cleaned_ios_upper cleaned_ios_lower

Automatic base adding to the raw IOS.

The following file extensions are supported.

Extension	Description
`.stl`	An STL mesh file.
`.ply`	A PLY mesh file.
`.obj`	An OBJ mesh file.
`.drc`	A Draco-compressed mesh file.

This output is only available in version 24.06 and higher of the Engine API.

# Intra-oral scan orientation ios_local_orientation_upper ios_local_orientation_lower

Automatic computation of the orientation of the intra-oral scan. This allows you to automatically rotate the IOS such that it always faces the user.

The result is a JSON file containing the local orientation of the IOS as a transformation matrix. The rotation component of this matrix contains the following orientation column vectors:

The first column is the left-pointing axis of the scan
The second column is the front-pointing axis of the scan
The third column is the up-pointing axis of the scan

# Teeth bounding boxes teeth_localisation

Automatic computation of the bounding box around each tooth in the CBCT scan.

The result is a JSON file containing for each tooth:

an origin [X, Y, Z] representing the center of the bounding box
a size [X, Y, Z] representing the dimensions of the bounding box
x: the coordinates [X, Y, Z] representing the unit vector (direction) of the local x-axis of the tooth
y: the coordinates [X, Y, Z] representing the unit vector (direction) of the local y-axis of the tooth
z: the coordinates [X, Y, Z] representing the unit vector (direction) of the local z-axis of the tooth

# Cleaned DICOM dicom

A "cleaned" and standardized version of the input DICOM, which is in single-file format (rather than folder of slices), has been made isotropic, rotated to the natural head position, etc. We support cleaning DICOMs coming from various manufacturers and exported from many softwares, which each have their own conventions for DICOM tags, making it often complicated for our clients to properly interpret these scans.

The following file extensions are supported.

Extension	Description
`.dcm`	A single DICOM file with all slices inside.
`.nii`	A single NIfTI file.
`.vti`	A single VTI file.

Additionally, all formats can be compressed with GZIP, indicated by adding .gz to the extension. Refer to the API spec for an overview of the supported combinations.

# 2D Projections ceph pa_ceph pano

Automatic computation of the CEPH, Posteroanterior (PA) CEPH, and Panoramic projections based on the DICOM.

The result is a PNG image of the projection.

# Combining all outputs in a single ZIP zipped

Combines all output files into a single ZIP archive. This is useful when you want to have all results from the Engine in one place. The file name of each output can be controlled through the name field in each output file. If no name is provided, an auto-generated name is used, based on the type of output.

The result is a ZIP archive containing all output files. All other requested output files will be included in the ZIP archive.

You can have sub-folders in this ZIP archive, in order to group certain outputs together. To achieve this, simply specify the desired path of each output in its name field. For example, if you want the mandible mesh to be stored at <ZIP archive>/upperSegmentations/mandible.stl, then set the name field of the mandible mesh to "upperSegmentations/mandible.stl".

A few other output files exist, but these are more advanced and tailored to specific workflows. If you want to know more about these, or if the outputs above don't satisfy your needs, please reach out to us.