include/umbra_import.h file

Interfaces for importing 3D scenes.

This is the low-level SDK interface for declaring inputs to the optimization process. Convenience wrappers around this interface are provided for supported programming languages.

The functionality of this interface includes:

  • serializing input data to Umbra's proprietary asset format
  • uploading input data to the Umbra Cloud service for processing
  • initiating the optimization process for exported data
  • converting assets from various supported standard 3D formats

Classes

struct UmbraSceneId
Opaque identifier for an UmbraInputScene.
struct UmbraMeshHandle
An opaque handle to an UmbraMesh.
struct UmbraTextureHandle
An opaque handle to an UmbraTexture.
struct UmbraMesh
3D triangle mesh
struct UmbraTexture
Texture map data.
struct UmbraTextureDescriptor
Texture usage description.
struct UmbraPointAttribute
Description of an attribute in the point cloud data.
struct UmbraPointCloud
Point cloud data.
struct UmbraGeoJSON
GeoJSON data.
struct UmbraMaterial
Description of a Material.
struct UmbraObject
Description of a scene object.
struct UmbraImportSettings
Per-import settings.
struct UmbraSceneProperties
Scene meta data for optimization.
struct UmbraFileImportParams
File import parameters.

Enums

enum UmbraTriangleFlagBits { UmbraTriangleFlags_MirroredNormalMap = 1 << 0 }
Optional per-triangle flags for UmbraMesh::triangleFlags.
enum UmbraCoordinateSystem { UmbraCoordinateSystem_LocalMeter = 0, UmbraCoordinateSystem_WGS84AngularDegree, UmbraCoordinateSystem_Undefined, UmbraCoordinateSystemCount, UmbraCoordinateSystemForce32 = 0x7FFFFFFF }
Input coordinate system.
enum UmbraTriangleWinding { UmbraTriangleWinding_CCW = 0, UmbraTriangleWinding_CW, UmbraTriangleWinding_TwoSided, UmbraTriangleWindingCount, UmbraTriangleWindingForce32 = 0x7FFFFFFF }
Winding of the triangles in a mesh for backface determination.
enum UmbraTextureWrapMode { UmbraTextureWrapMode_Repeat = 0, UmbraTextureWrapMode_Clamp, UmbraTextureWrapModeCount, UnbraTextureWrapModeForce32 = 0x7FFFFFFF }
Texture wrap modes.
enum UmbraTextureFilterMode { UmbraTextureFilterMode_Point = 0, UmbraTextureFilterMode_Bilinear, UmbraTextureFilterModeCount, UmbraTextureFilterModeForce32 = 0x7FFFFFFF }
Texture filter modes.
enum UmbraPointAttributeName { UmbraPointAttributeName_X = 0, UmbraPointAttributeName_Y, UmbraPointAttributeName_Z, UmbraPointAttributeName_Intensity, UmbraPointAttributeName_Red, UmbraPointAttributeName_Green, UmbraPointAttributeName_Blue, UmbraPointAttributeName_NormalX, UmbraPointAttributeName_NormalY, UmbraPointAttributeName_NormalZ, UmbraPointAttributeName_Alpha, UmbraPointAttributeName_Classification, UmbraPointAttributeName_Variation, UmbraPointAttributeNameCount, UmbraPointAttributeNameFirstUserData = 1 << 16, UmbraPointAttributeNameForce32 = 0x7FFFFFFF }
Types of attributes in point cloud inputs.
enum UmbraContentProfile { UmbraContentProfile_Unknown = 0, UmbraContentProfile_DCC, UmbraContentProfile_Scanned, UmbraContentProfileCount, UmbraContentProfileForce32 = 0x7FFFFFFF }
Content profile of the export data.
enum UmbraImportStatus { UmbraImportStatus_Done = 0, UmbraImportStatus_Running, UmbraImportStatus_OutOfMemoryError, UmbraImportStatus_WriteError, UmbraImportStatus_PermissionError, UmbraImportStatus_LaunchFailed, UmbraImportStatus_LaunchAborted, UmbraImportStatus_UnrecoverableError, UmbraImportStatus_InputReadError, UmbraImportStatus_ComputationParameterError, UmbraImportStatusCount, UmbraImportStatusForce32 = 0x7FFFFFFF }
Importer error codes.
enum UmbraInputSceneState { UmbraInputSceneState_Ok = 0, UmbraInputSceneState_Blocked, UmbraInputSceneState_Error, UmbraInputSceneStateCount, UmbraInputSceneStateForce32 = 0x7FFFFFFF }
Scene importer status.
enum UmbraInputFileType { UmbraInputFileType_Automatic = 0, UmbraInputFileType_UmbraRepository, UmbraInputFileType_OBJ, UmbraInputFileType_LAS, UmbraInputFileType_XYZ, UmbraInputFileTypeCount, UmbraInputFileTypeForce32 = 0x7FFFFFFF }
Supported standard 3D file formats.

Typedefs

typedef struct UmbraImporter UmbraImporter
Opaque object for importing data into Umbra.
typedef struct UmbraInputScene UmbraInputScene
Opaque object for creating a single scene from multiple meshes/point clouds.

Functions

UmbraBool UmbraSceneIdIsValid(UmbraSceneId id)
Checks if a scene identifier is valid.
void UmbraSceneIdToString(UmbraSceneId id, char str[41])
Converts a scene identifier to a string.
UmbraSceneId UmbraSceneIdFromString(const char str[41])
Parse a scene id from a string.
UmbraSceneId UmbraSceneIdInvalid(void)
Creates an invalid scene identifier.
UmbraMeshHandle UmbraMeshHandleInvalid(void)
Creates an invalid mesh handle.
UmbraTextureHandle UmbraTextureHandleInvalid(void)
Creates an invalid texture handle.
void UmbraMeshInit(UmbraMesh*)
Initialize mesh to an empty state.
UmbraMeshHandle UmbraInsertMesh(UmbraInputScene* scene, const UmbraMesh* mesh)
Insert a Mesh to the input scene.
void UmbraTextureInit(UmbraTexture*)
Initialize texture to an empty state.
void UmbraTextureDescriptorInit(UmbraTextureDescriptor*)
Initialize texture descriptor to an empty state.
UmbraTextureHandle UmbraInsertTexture(UmbraInputScene* scene, const UmbraTexture* texture)
Insert a Texture to an input scene.
void UmbraPointAttributeInit(UmbraPointAttribute*)
Initialize point attribute to an empty state.
void UmbraPointCloudInit(UmbraPointCloud*)
Initialize point cloud to an empty state.
void UmbraInsertPointCloud(UmbraInputScene*, const UmbraPointCloud*)
Insert a point cloud to an input scene.
void UmbraGeoJSONInit(UmbraGeoJSON*)
Initialize GeoJSON data to an empty state.
void UmbraInsertGeoJSON(UmbraInputScene*, const UmbraGeoJSON*)
Insert geo json to an input scene.
void UmbraMaterialInit(UmbraMaterial*)
Initialize material to an empty state.
void UmbraObjectInit(UmbraObject*)
Initialize object to an empty state.
void UmbraInsertObject(UmbraInputScene*, const UmbraObject*)
Insert an Object to an input scene.
void UmbraInsertScene(UmbraInputScene*, UmbraSceneId id)
Append a previously imported scene to this scene.
void UmbraImportSettingsInit(UmbraImportSettings*)
Initialize import settings to an empty state.
void UmbraScenePropertiesInit(UmbraSceneProperties*)
Initialize scene properties to a default state.
void UmbraFileImportParamsInit(UmbraFileImportParams*)
Initialize file import parameters to an empty state.
UmbraImporter* UmbraCloudImporterCreate(UmbraClient* client, const char* apiKey, const char* name, const UmbraImportSettings* params)
Create an importer context for importing to the Umbra cloud.
void UmbraDestroyImporter(UmbraImporter*)
Destroy an importer and release associated resources The import must be finished before being destroyed.
UmbraInputScene* UmbraGetInputScene(UmbraImporter*)
Get the input scene object from an importer.
UmbraInputSceneState UmbraGetInputSceneState(const UmbraInputScene*)
Update and query the state of scene import.
void UmbraImportFromFile(UmbraImporter* importer, UmbraInputFileType type, const char* path, const UmbraFileImportParams* params)
Import 3D assets from a file.
void UmbraSetSceneProperties(UmbraImporter*, const UmbraSceneProperties*)
Set computation parameters.
void UmbraSetComputationParameterFloat(UmbraImporter* importer, const char* name, double value)
Set a floating point computation parameter.
void UmbraSetComputationParameterBool(UmbraImporter* importer, const char* name, UmbraBool value)
Set a boolean computation parameter.
void UmbraSetComputationParameterInt(UmbraImporter* importer, const char* name, int value)
Set an integer computation parameter.
void UmbraSetComputationParameterString(UmbraImporter* importer, const char* name, const char* value)
Set computation parameter string.
void UmbraSetComputationParameterFloatArray(UmbraImporter* importer, const char* name, const double* values, int len)
Set a floating point array computation parameter.
void UmbraSetComputationParametersJson(UmbraImporter*, const char* json)
Set parameters from a JSON string.
UmbraImportStatus UmbraImportFinish(UmbraImporter* importer, UmbraBool waitForCompletion)
Signal that all data has been declared and block or poll for operation done.
const char* UmbraImportGetError(const UmbraImporter*)
Get a more detailed description of the error returned by UmbraGetInputSceneState.
UmbraSceneId UmbraImportGetSceneId(const UmbraImporter*)
Get the UmbraSceneId of the imported scene.
const char* UmbraImportGetLocator(const UmbraImporter*)
Get the Locator of the imported scene.
UmbraImporter* UmbraFileImporterCreate(UmbraClient* client, const char* outDir, const char* workDir, const UmbraLocalComputeParams* params)
Create an importer context for importing to local files.
void UmbraLocalComputeParamsInit(UmbraLocalComputeParams*)

Enum details

enum UmbraTriangleFlagBits

Optional per-triangle flags for UmbraMesh::triangleFlags.

Enumerators
UmbraTriangleFlags_MirroredNormalMap

Interpret normal map as mirror, flipping the bitangent direction when interpreting any normal map data.

enum UmbraCoordinateSystem

Input coordinate system.

In general the optimization process will produce output in the coordinate system of the input and therefore will not care what the interpretation of the coordinates in the input is.

When the input is in WGS84 georeferenced coordinates the optimization process will establish a local coordinate system for the produced output and communicate the transformation from the output coordinates to WGS84. This is currently only supported for point cloud inputs.

Enumerators
UmbraCoordinateSystem_LocalMeter

Coordinates define a local Carthesian system with meters as the unit.

UmbraCoordinateSystem_WGS84AngularDegree

Geodetic coordinates as specified by WGS revision 84 (Wikipedia).

UmbraCoordinateSystem_Undefined

Coordinates system is undefined.

Umbra treats this as equivalent to a local meter system.

UmbraCoordinateSystemCount
UmbraCoordinateSystemForce32

enum UmbraTriangleWinding

Winding of the triangles in a mesh for backface determination.

Enumerators
UmbraTriangleWinding_CCW

Counterclockwise.

UmbraTriangleWinding_CW

Clockwise.

UmbraTriangleWinding_TwoSided

Double-sided triangles.

UmbraTriangleWindingCount
UmbraTriangleWindingForce32

enum UmbraTextureWrapMode

Texture wrap modes.

Enumerators
UmbraTextureWrapMode_Repeat

Texture coordinates are computed as modulo one of the input value.

UmbraTextureWrapMode_Clamp

Texture coordinates are clamped to the range [0,1].

UmbraTextureWrapModeCount
UnbraTextureWrapModeForce32

enum UmbraTextureFilterMode

Texture filter modes.

Enumerators
UmbraTextureFilterMode_Point

Use nearest existing sample point.

Also commonly known as nearest neighbour interpolation.

UmbraTextureFilterMode_Bilinear

Bilinearly interpolate from the four nearest sample points.

UmbraTextureFilterModeCount
UmbraTextureFilterModeForce32

enum UmbraContentProfile

Content profile of the export data.

This is used solely for choosing appropriate default computation parameters based on the source of the data, computation parameters can still be individually overridden.

Enumerators
UmbraContentProfile_Unknown

If content type is unknown, Umbra will use general purpose parameters without content type specific optimizations.

UmbraContentProfile_DCC

Digital Content Creation.

This should be used for most manually authored content.

UmbraContentProfile_Scanned

Scanned content, most commonly point clouds or meshes created from point clouds.

UmbraContentProfileCount
UmbraContentProfileForce32

enum UmbraInputSceneState

Scene importer status.

Enumerators
UmbraInputSceneState_Ok

All good, can continue importing data without calls blocking.

UmbraInputSceneState_Blocked

Import is blocked.

Calling any insert functions after receiving this state may result in Umbra waiting on network or other slow resources before returning.

UmbraInputSceneState_Error

An error has occured.

Call UmbraImportGetError for details

UmbraInputSceneStateCount
UmbraInputSceneStateForce32

enum UmbraInputFileType

Supported standard 3D file formats.

Enumerators
UmbraInputFileType_Automatic

Guess file type from extension and/or header.

UmbraInputFileType_UmbraRepository

Umbra proprietary format.

UmbraInputFileType_OBJ

Wavefront OBJ format file containing meshes and referencing external materials.

UmbraInputFileType_LAS

LAS point cloud.

UmbraInputFileType_XYZ

XYZ point cloud.

UmbraInputFileTypeCount
UmbraInputFileTypeForce32

Function details

UmbraBool UmbraSceneIdIsValid(UmbraSceneId id)

Checks if a scene identifier is valid.

Parameters
id in The identifer to check.

Being valid does not guarantee that the scene exists.

void UmbraSceneIdToString(UmbraSceneId id, char str[41])

Converts a scene identifier to a string.

Parameters
id in The identifer to convert.
str out A pointer to an output buffer.

The output string consists of 40 characters + a null terminator.

UmbraSceneId UmbraSceneIdFromString(const char str[41])

Parse a scene id from a string.

Parameters
str in The string to parse. The string must have the format returned from UmbraSceneIdToString
Returns The parsed scene identifier, or an invalid identifier if the input was invalid.

UmbraSceneId UmbraSceneIdInvalid(void)

Creates an invalid scene identifier.

Returns An invalid scene identifier

UmbraMeshHandle UmbraMeshHandleInvalid(void)

Creates an invalid mesh handle.

Returns An invalid mesh handle

UmbraTextureHandle UmbraTextureHandleInvalid(void)

Creates an invalid texture handle.

Returns An invalid texture handle

void UmbraMeshInit(UmbraMesh*)

Initialize mesh to an empty state.

Provides a safe way to initialize that will work across API revisions and correctly handle any non-trivial or unexpected values

UmbraMeshHandle UmbraInsertMesh(UmbraInputScene* scene, const UmbraMesh* mesh)

Insert a Mesh to the input scene.

Parameters
scene out The scene to insert mesh into.
mesh in The mesh to insert.
Returns Handle for referring to the mesh

UmbraTextureHandle UmbraInsertTexture(UmbraInputScene* scene, const UmbraTexture* texture)

Insert a Texture to an input scene.

Parameters
scene in Scene to insert texture into
texture in Texture to insert
Returns Handle to the inserted texture

void UmbraInsertScene(UmbraInputScene*, UmbraSceneId id)

Append a previously imported scene to this scene.

This allows combining multiple input scenes into a single larger scene, or starting a new optimization process for a previously imported scene.

An input scene can consist of nothing but a reference to a previously imported scene.

UmbraImporter* UmbraCloudImporterCreate(UmbraClient* client, const char* apiKey, const char* name, const UmbraImportSettings* params)

Create an importer context for importing to the Umbra cloud.

Parameters
client in Platform integration and metadata for the importing client.
apiKey in sdk-concept-api-key to authenticate the import.
name in A user-visible name for the result of the import. places.
params in Configuration for the import operation.
Returns A new importer object that can be used to import data

Data must be imported to the cloud before it can be optimized.

UmbraInputScene* UmbraGetInputScene(UmbraImporter*)

Get the input scene object from an importer.

The input scene object collects data from multiple insertion functions into a single scene. The input scene object is owned by the importer.

UmbraInputSceneState UmbraGetInputSceneState(const UmbraInputScene*)

Update and query the state of scene import.

Required for asynchronous operation and error checks

void UmbraImportFromFile(UmbraImporter* importer, UmbraInputFileType type, const char* path, const UmbraFileImportParams* params)

Import 3D assets from a file.

This creates a new scene from the contents of the file

void UmbraSetSceneProperties(UmbraImporter*, const UmbraSceneProperties*)

Set computation parameters.

Set scene properties for an import.

Scene properties default to the values provided by UmbraScenePropertiesInit. Setting scene properties has no effect if done after finishing the import.

void UmbraSetComputationParameterFloat(UmbraImporter* importer, const char* name, double value)

Set a floating point computation parameter.

Parameters
importer in Target importer for the parameter change
name in Name of the parameter to change. This is the parameter column in the parameter documentation.
value in Value to set the parameter to

See Parameters for a list of available parameters and their types

void UmbraSetComputationParameterBool(UmbraImporter* importer, const char* name, UmbraBool value)

Set a boolean computation parameter.

Parameters
importer in Target importer for the parameter change
name in Name of the parameter to change. This is the parameter column in the parameter documentation.
value in Value to set the parameter to

See Parameters for a list of available parameters and their types

void UmbraSetComputationParameterInt(UmbraImporter* importer, const char* name, int value)

Set an integer computation parameter.

Parameters
importer in Target importer for the parameter change
name in Name of the parameter to change. This is the parameter column in the parameter documentation.
value in Value to set the parameter to

See Parameters for a list of available parameters and their types

void UmbraSetComputationParameterString(UmbraImporter* importer, const char* name, const char* value)

Set computation parameter string.

Parameters
importer in Target importer for the parameter change
name in Name of the parameter to change. This is the parameter column in the parameter documentation.
value in Value to set the parameter to

See Parameters for a list of available parameters and their types

void UmbraSetComputationParameterFloatArray(UmbraImporter* importer, const char* name, const double* values, int len)

Set a floating point array computation parameter.

Parameters
importer in Target importer for the parameter change.
name in Name of the parameter to change. This is the parameter column in the parameter documentation.
values in List of values to set the parameter to.
len in Length of the list of values. This should match any length listed in the parameter documentation.

See Parameters for a list of available parameters and their types

void UmbraSetComputationParametersJson(UmbraImporter*, const char* json)

Set parameters from a JSON string.

The JSON describes a single object with parameters as attributes. For example {"feature-size" : 0.1, "ao" : false}

UmbraImportStatus UmbraImportFinish(UmbraImporter* importer, UmbraBool waitForCompletion)

Signal that all data has been declared and block or poll for operation done.

Parameters
importer in Importer to mark as finished
waitForCompletion in When 'true' the function will block until the import operation has been fully carried out. The status will either be UmbraImportStatus_Done or one of the error codes, but never UmbraImportStatus_Running. Using a value of 'false' queries to current operation status and returns immediately. If the import operation is still being processed, a value of UmbraImportStatus_Running is returned and the function must be called again at a later time.
Returns The status of the import.

If UmbraImportSettings::importOnly has not been set, this function also starts the optimization process.

const char* UmbraImportGetError(const UmbraImporter*)

Get a more detailed description of the error returned by UmbraGetInputSceneState.

Returns Error message or an empty string.

Do not use this function for checking whether an error has occurred. Use UmbraGetInputSceneState instead.

UmbraSceneId UmbraImportGetSceneId(const UmbraImporter*)

Get the UmbraSceneId of the imported scene.

The import must be finished before an identifier can be created

const char* UmbraImportGetLocator(const UmbraImporter*)

Get the Locator of the imported scene.

The import must be finished before a locator can be created

UmbraImporter* UmbraFileImporterCreate(UmbraClient* client, const char* outDir, const char* workDir, const UmbraLocalComputeParams* params)

Create an importer context for importing to local files.

Parameters
client in Platform integration and metadata for the importing client.
outDir in Directory for the output. Using a dedicated directory for each import will reduce clutter.
workDir in Temporary working directory. This can be deleted after the import is complete.
params in Configuration for the import operation
Returns A new importer object that can be used to import data

This importer creates a number of files that can later be included in another import.