Import API

Functions for importing data into Umbra and starting computations.

Classes

struct UmbraSceneId
Opaque scene identifier struct.
struct UmbraMeshHandle
Opaque handle identifying an UmbraMesh.
struct UmbraTextureHandle
Opaque handle identifiying an UmbraTexture.
struct UmbraMesh
3D triangle mesh.
struct UmbraTexture
2D texture data.
struct UmbraTextureDescriptor
Texture sampling parameters.
struct UmbraPointAttribute
Point cloud attribute descriptor.
struct UmbraPointCloud
Point cloud data.
struct UmbraGeoJSON
A GeoJSON string.
struct UmbraMaterial
A material.
struct UmbraObject
A renderable object.
struct UmbraImportSettings
Per-import settings.
struct UmbraSceneProperties
Scene properties to guide the computation.
struct UmbraFileImportParams
File import parameters.

Enums

enum UmbraTriangleFlagBits { UmbraTriangleFlags_MirroredNormalMap = 1 << 0 }
Optional per-triangle flags.
enum UmbraCoordinateSystem { UmbraCoordinateSystem_LocalMeter = 0, UmbraCoordinateSystem_WGS84AngularDegree, UmbraCoordinateSystem_Undefined }
The input coordinate system.
enum UmbraTriangleWinding { UmbraTriangleWinding_CCW = 0, UmbraTriangleWinding_CW, UmbraTriangleWinding_TwoSided }
Triangle winding order.
enum UmbraTextureWrapMode { UmbraTextureWrapMode_Repeat = 0, UmbraTextureWrapMode_Clamp }
Texture wrap mode.
enum UmbraTextureFilterMode { UmbraTextureFilterMode_Point = 0, UmbraTextureFilterMode_Bilinear }
Texture filter mode.
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 deprecated, UmbraPointAttributeNameCount }
Point cloud point attributes.
enum UmbraContentProfile { UmbraContentProfile_Unknown = 0, UmbraContentProfile_DCC, UmbraContentProfile_Scanned }
Input data category.
enum UmbraImportStatus { UmbraImportStatus_Done = 0, UmbraImportStatus_Running, UmbraImportStatus_OutOfMemoryError, UmbraImportStatus_WriteError, UmbraImportStatus_PermissionError, UmbraImportStatus_LaunchFailed, UmbraImportStatus_LaunchAborted, UmbraImportStatus_UnrecoverableError, UmbraImportStatus_InputReadError, UmbraImportStatus_ComputationParameterError }
Importer status codes.
enum UmbraInputSceneState { UmbraInputSceneState_Ok = 0, UmbraInputSceneState_Blocked, UmbraInputSceneState_Error }
Scene importer status.
enum UmbraInputFileType { UmbraInputFileType_Automatic = 0, UmbraInputFileType_UmbraRepository, UmbraInputFileType_OBJ, UmbraInputFileType_LAS, UmbraInputFileType_XYZ }
Supported standard 3D file formats.

Typedefs

typedef struct UmbraImporter UmbraImporter
Opaque Umbra import context struct.
typedef struct UmbraInputScene UmbraInputScene
Opaque input scene struct.
typedef struct UmbraImporterQuery UmbraImporterQuery
Opaque importer query struct.

Functions

UmbraBool UmbraSceneIdIsValid(UmbraSceneId id)
Check if a scene identifier is valid.
void UmbraSceneIdToString(UmbraSceneId id, char str[41])
Convert a scene identifier to a string.
UmbraSceneId UmbraSceneIdFromString(const char str[41])
Convert a string to a scene identifier.
UmbraSceneId UmbraSceneIdInvalid(void)
Create an invalid scene identifier.
UmbraMeshHandle UmbraMeshHandleInvalid(void)
Create an invalid mesh handle.
UmbraTextureHandle UmbraTextureHandleInvalid(void)
Create an invalid texture handle.
void UmbraMeshInit(UmbraMesh* mesh)
Initialize an empty mesh.
UmbraMeshHandle UmbraInsertMesh(UmbraInputScene* scene, const UmbraMesh* mesh)
Add a mesh to a scene.
void UmbraTextureInit(UmbraTexture* texture)
Initialize an empty texture.
void UmbraTextureDescriptorInit(UmbraTextureDescriptor* descriptor)
Initialize a default texture descriptor.
UmbraTextureHandle UmbraInsertTexture(UmbraInputScene* scene, const UmbraTexture* texture)
Add a texture to a scene.
void UmbraPointAttributeInit(UmbraPointAttribute* attribute)
Initialize a default point attribute.
void UmbraPointCloudInit(UmbraPointCloud* pc)
Initialize an empty point cloud.
void UmbraInsertPointCloud(UmbraInputScene* scene, const UmbraPointCloud* pc)
Add a point cloud to a scene.
void UmbraGeoJSONInit(UmbraGeoJSON* geojson)
Initialize an empty GeoJSON string.
void UmbraInsertGeoJSON(UmbraInputScene* scene, const UmbraGeoJSON* geojson)
Add a GeoJSON string to a scene.
void UmbraMaterialInit(UmbraMaterial* material)
Initialize an empty material.
void UmbraObjectInit(UmbraObject*)
Initialize an empty object.
void UmbraInsertObject(UmbraInputScene* scene, const UmbraObject* obj)
Add an object to a scene.
void UmbraInsertScene(UmbraInputScene* scene, UmbraSceneId id)
Add a previously imported scene to a scene.
void UmbraImportSettingsInit(UmbraImportSettings* settings)
Initialize default import settings.
void UmbraScenePropertiesInit(UmbraSceneProperties* properties)
Initialize default scene properties.
UmbraImporter* UmbraCloudImporterCreate(UmbraClient* client, const char* apiKey, const char* name, const UmbraImportSettings* importSettings)
Create an importer context for importing to the Umbra cloud.
void UmbraDestroyImporter(UmbraImporter* importer)
Destroy an import context.
UmbraInputScene* UmbraGetInputScene(UmbraImporter* importer)
Get the import context's input scene.
UmbraInputSceneState UmbraGetInputSceneState(const UmbraInputScene* scene)
Get the input scene's status.
void UmbraImportFromFile(UmbraImporter* importer, UmbraInputFileType type, const char* path, const UmbraFileImportParams* fileImportParams)
Import assets from a file.
void UmbraSetSceneProperties(UmbraImporter* importer, const UmbraSceneProperties* properties)
Set the scene's properties.
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 a text computation parameter.
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 many parameters from a JSON string.
UmbraImportStatus UmbraImportFinish(UmbraImporter* importer, UmbraBool block)
Wait for the import to complete.
const char* UmbraImportGetError(const UmbraImporter*)
Get an explanation of the last error returned by UmbraGetInputSceneState.
UmbraSceneId UmbraImportGetSceneId(const UmbraImporter*)
Get the scene's ID.
const char* UmbraImportGetLocator(const UmbraImporter*)
Get the scene's locator.
void toString(char s[41])
Convert a scene identifier to a string.

Enum details

enum UmbraTriangleFlagBits

Optional per-triangle flags.

Enumerators
UmbraTriangleFlags_MirroredNormalMap

Negate the bitangent when shading this triangle.

This flag exists to support Unity. Specifically, Unity tangents are four dimensional, where the last component is used to denote whether the bitangent should be flipped. See here for more information.

enum UmbraCoordinateSystem

The input coordinate system.

In general, Umbra preserves coordinate system between inputs and outputs.

Enumerators
UmbraCoordinateSystem_LocalMeter

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

UmbraCoordinateSystem_WGS84AngularDegree

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

UmbraCoordinateSystem_Undefined

Coordinate system is undefined.

Umbra treats this as equivalent to a local meter system.

enum UmbraTriangleWinding

Triangle winding order.

Enumerators
UmbraTriangleWinding_CCW

Counterclockwise.

UmbraTriangleWinding_CW

Clockwise.

UmbraTriangleWinding_TwoSided

Double-sided triangles.

enum UmbraTextureWrapMode

Texture wrap mode.

Enumerators
UmbraTextureWrapMode_Repeat

Tiles the texture, i.e.

texture coordinates are intepreted as modulo one of the input.

UmbraTextureWrapMode_Clamp

Repeat edge texels when sampling outside the texture boundaries, i.e.

clamp texture coordinates to the range [0, 1].

enum UmbraTextureFilterMode

Texture filter mode.

Enumerators
UmbraTextureFilterMode_Point

Snap texture coordinates to whole texels.

Also known as nearest neighbour interpolation.

UmbraTextureFilterMode_Bilinear

Interpolate between the four nearest texels.

enum UmbraPointAttributeName

Point cloud point attributes.

Enumerators
UmbraPointAttributeName_X

The X coordinate, or longitude when the point cloud is in WGS84.

UmbraPointAttributeName_Y

The Y coordinate, or latitude when the point cloud is in WGS84.

UmbraPointAttributeName_Z

The Z coordinate, or elevation when the point cloud is in WGS84.

UmbraPointAttributeName_Intensity

Ignored if you have red/green/blue attributes, otherwise intensity gets mapped to some arbitrary color ramp.

UmbraPointAttributeName_Red

The red color channel.

UmbraPointAttributeName_Green

The green color channel.

UmbraPointAttributeName_Blue

The blue color channel.

UmbraPointAttributeName_NormalX

The x component of the normal vector.

UmbraPointAttributeName_NormalY

The y component of the normal vector.

UmbraPointAttributeName_NormalZ

The z component of the normal vector.

UmbraPointAttributeName_Alpha

Never used.

UmbraPointAttributeNameCount

enum UmbraContentProfile

Input data category.

These are used to pick default computation parameters.

Enumerators
UmbraContentProfile_Unknown

If you don't know what your data is, 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, e.g.

point clouds and meshes reconstructed from point clouds.

enum UmbraImportStatus

Importer status codes.

Enumerators
UmbraImportStatus_Done

The import completed successfully.

UmbraImportStatus_Running

The import or optimization are still running, and has neither succeeded nor failed.

UmbraImportStatus_OutOfMemoryError

The importer ran out of memory.

UmbraImportStatus_WriteError

There was an error on the server.

UmbraImportStatus_PermissionError

Invalid sdk-concept-api-key.

UmbraImportStatus_LaunchFailed

Couldn't start the optimization.

UmbraImportStatus_LaunchAborted

The optimization was cancelled.

UmbraImportStatus_UnrecoverableError

Unrecoverable error.

UmbraImportStatus_InputReadError

Couldn't read the file when using UmbraImportFromFile.

UmbraImportStatus_ComputationParameterError

Invalid computation parameters.

enum UmbraInputSceneState

Scene importer status.

Enumerators
UmbraInputSceneState_Ok

No errors have occured and the importer is ready to accept new data.

UmbraInputSceneState_Blocked

No errors have occured but the importer is not ready to accept new data.

Inserting assets will block until the importer is ready again.

UmbraInputSceneState_Error

An error has occured.

Call UmbraImportGetError for details.

enum UmbraInputFileType

Supported standard 3D file formats.

Enumerators
UmbraInputFileType_Automatic

Guess the file type from its extension.

UmbraInputFileType_UmbraRepository

Umbra proprietary format.

UmbraInputFileType_OBJ

Wavefront OBJ containing meshes and referencing external materials.

UmbraInputFileType_LAS

LAS point cloud.

UmbraInputFileType_XYZ

XYZ point cloud.

Function details

UmbraBool UmbraSceneIdIsValid(UmbraSceneId id)

Check if a scene identifier is valid.

Parameters
id in The identifer to check.

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

Convert a scene identifier to a string.

Parameters
id in The identifer.
str out The output string.

The output buffer should be at least 41 bytes long. The identifier is 40 characters long, plus one for the null terminator.

UmbraSceneId UmbraSceneIdFromString(const char str[41])

Convert a string to a scene identifier.

Parameters
str in The string to parse.
Returns The parsed scene identifier, or an invalid identifier if the input was invalid.

UmbraSceneId UmbraSceneIdInvalid(void)

Create an invalid scene identifier.

Returns An invalid scene identifier

UmbraMeshHandle UmbraMeshHandleInvalid(void)

Create an invalid mesh handle.

Returns An invalid mesh handle

UmbraTextureHandle UmbraTextureHandleInvalid(void)

Create an invalid texture handle.

Returns An invalid texture handle

void UmbraMeshInit(UmbraMesh* mesh)

Initialize an empty mesh.

Parameters
mesh out The mesh.

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

Add a mesh to a scene.

Parameters
scene in/out The scene.
mesh in The mesh.
Returns An opaque handle identifying the mesh on success, or an invalid handle on failure.

void UmbraTextureInit(UmbraTexture* texture)

Initialize an empty texture.

Parameters
texture out The texture.

void UmbraTextureDescriptorInit(UmbraTextureDescriptor* descriptor)

Initialize a default texture descriptor.

Parameters
descriptor out The texture descriptor.

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

Add a texture to a scene.

Parameters
scene in/out The scene.
texture in The texture.
Returns A handle to the texture data on success, or an invalid handle on failure.

void UmbraPointAttributeInit(UmbraPointAttribute* attribute)

Initialize a default point attribute.

Parameters
attribute out The point attribute.

void UmbraPointCloudInit(UmbraPointCloud* pc)

Initialize an empty point cloud.

Parameters
pc out The point cloud.

void UmbraInsertPointCloud(UmbraInputScene* scene, const UmbraPointCloud* pc)

Add a point cloud to a scene.

Parameters
scene in/out The scene.
pc in The point cloud.

void UmbraGeoJSONInit(UmbraGeoJSON* geojson)

Initialize an empty GeoJSON string.

Parameters
geojson out The GeoJSON string.

void UmbraInsertGeoJSON(UmbraInputScene* scene, const UmbraGeoJSON* geojson)

Add a GeoJSON string to a scene.

Parameters
scene in/out The scene.
geojson in The GeoJSON string.

void UmbraMaterialInit(UmbraMaterial* material)

Initialize an empty material.

Parameters
material out The material.

void UmbraInsertObject(UmbraInputScene* scene, const UmbraObject* obj)

Add an object to a scene.

Parameters
scene in/out The scene.
obj in The object.

void UmbraInsertScene(UmbraInputScene* scene, UmbraSceneId id)

Add a previously imported scene to a scene.

Parameters
scene in/out The container scene.
id in The child scene's ID.

You can use this function to combine multiple input scenes into a single larger scene.

void UmbraImportSettingsInit(UmbraImportSettings* settings)

Initialize default import settings.

Parameters
settings out The import settings.

void UmbraScenePropertiesInit(UmbraSceneProperties* properties)

Initialize default scene properties.

Parameters
properties out The scene properties.

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

Create an importer context for importing to the Umbra cloud.

Parameters
client in An Umbra client object.
apiKey in Your sdk-concept-api-key.
name in The name of the scene which gets displayed to users.
importSettings in Configuration for the import operation.
Returns A new importer context.

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

void UmbraDestroyImporter(UmbraImporter* importer)

Destroy an import context.

Parameters
importer in The import context.

UmbraInputScene* UmbraGetInputScene(UmbraImporter* importer)

Get the import context's input scene.

Parameters
importer in The import context.
Returns The input scene.

The input scene is used to group the results of multiple insertions. It is owned by the import context.

UmbraInputSceneState UmbraGetInputSceneState(const UmbraInputScene* scene)

Get the input scene's status.

Parameters
scene in The scene.
Returns The input scene's status.

You can use this function check if a call to an UmbraInsert* function will block. It's useful for writing asynchronous importers, e.g. an importer running in a GUI application where the GUI should remain responsive.

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

Import assets from a file.

Parameters
importer in/out The import context.
type in The file type.
path in The path to the file.
fileImportParams in Extra parameters. May be NULL, in which case all options are set to zero.

Umbra can directly load some file formats so you don't need to write your own parsers. See UmbraInputFileType for a list of supported formats.

void UmbraSetSceneProperties(UmbraImporter* importer, const UmbraSceneProperties* properties)

Set the scene's properties.

Parameters
importer in/out The import context.
properties in The scene properties.

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

Set a floating point computation parameter.

Parameters
importer in The import context.
name in The name of the parameter. This is called parameter in the documentation.
value in The new value.

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 The import context.
name in The name of the parameter. This is called parameter in the documentation.
value in The new value.

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 The import context.
name in The name of the parameter. This is called parameter in the documentation.
value in The new value.

See Parameters for a list of available parameters and their types.

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

Set a text computation parameter.

Parameters
importer in The import context.
name in The name of the parameter. This is called parameter in the documentation.
value in The new value.

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 The import context.
name in The name of the parameter. This is called parameter in the documentation.
values in An array of values.
len in Length of values. This must match the documentation.

See Parameters for a list of available parameters and their types.

void UmbraSetComputationParametersJson(UmbraImporter*, const char* json)

Set many parameters from a JSON string.

The JSON should be a single object, with keys and values for each computation parameter. For example: {"feature-size" : 0.1, "ao" : false}.

UmbraImportStatus UmbraImportFinish(UmbraImporter* importer, UmbraBool block)

Wait for the import to complete.

Parameters
importer in The import contaxt.
block in Whether this call should block until the import finishes, or immediately return the input status.
Returns Import status.

If UmbraImportSettings::importOnly has not been set, this function also starts a computation.

const char* UmbraImportGetError(const UmbraImporter*)

Get an explanation of the last error returned by UmbraGetInputSceneState.

Returns An ASCII encoded error message. It is statically allocated and doesn't need to be deallocated.

UmbraSceneId UmbraImportGetSceneId(const UmbraImporter*)

Get the scene's ID.

Returns The scene ID.

const char* UmbraImportGetLocator(const UmbraImporter*)

Get the scene's locator.

Returns The scene locator.

void toString(char s[41])

Convert a scene identifier to a string.

Parameters
out The output string.

The output buffer should be at least 41 bytes long. The identifier is 40 characters long, plus one for the null terminator.