CANDELOR SDK  13.2.131
A computer vision library for 3D scene interpretation.
 All Data Structures Files Functions Typedefs Groups Pages
Support Functions and Data Structures

Contains support functions like loading point data or handling transformations. More...

Typedefs

typedef void(* ca_log_callback_t )(int severity, const char *message, void *user_info)
 Callback function prototype to receive logging information.
 

Functions

int ca_points_load (float **points, const char *points_file_name, int *num_points)
 Loads and allocates 3D point data.
 
int ca_points_save (const float *points, const char *points_file_name, int num_points)
 Saves the float array as a text file.
 
int ca_points_destroy (float **data)
 Destroys points or transforms previously created with ca_points_load.
 
int ca_transforms_destroy (float **data)
 Destroys transforms or transforms previously created with ca_points_load.
 
int ca_chars_destroy (char **data)
 Destroys character data allocated e.g. when retrieving field data.
 
int ca_build_version (const char **data)
 Reads the version of the CANDELOR SDK.
 
int ca_build_date (int *build_date)
 Gets timestamp of the build.
 

Detailed Description

Contains support functions like loading point data or handling transformations.

Data Structures

Points & Normals

The following layout is used for both points and normals. You need to make sure that normals actually have unit length by yourself.

The points are represented as an array of floats where each point consists of 4 coordinates

| Px Py Pz Pw Px Py Pz Pw ... |

The w component is always zero. The i-th point starts at index i * 4 of the array.

Transformation Matrix

Rigid transformations are represented using 4x4 floating point homogeneous matrices. The upper 3x3 part contains the rotation matrix. The last column contains the translation vector. The last row is constant.

| Rxx Rxy Rxz Tx |
| Ryx Ryy Ryz Ty |
| Rzx Rzy Rzz Tz |
|   0   0   0  1 |

The memory layout is row-major. Flattened to a one dimensional array the above matrix is transformed into

| Rxx Rxy Rxz Tx Ryx Ryy Ryz Ty Rzx Rzy Rzz Tz 0 0 0 1|

Coordinate systems are represented by 4x4 single precision floating point homogeneous matrices. The upper 3x3 part contains the basis vectors in columns, the last column contains the origin of the frame and the last row is constant.

File Formats

XYZ Point Clouds

Points are stored in XYZ files as plain text, separated by space, one point per line. Here is an example of a valid points file:

398.794189 357.600006 524.765015 
399.826996 358.200012 524.298584 
399.526611 358.5 524.765015 
399.892792 358.5 524.765015 
398.107513 358.799988 525.131226 

Such a file with the extension .xyz can be opened with e.g. Meshlab.

Exactly the same file format can be used to load normal vectors. It is your own responsibility to ensure that loaded normal vectors have the unit length.

The file format text file of 3 numbers per line representing one point, separated by one space. To create such a file, use e.g. the print format

%.20g %.20g %.20g\n

Typedef Documentation

typedef void(* ca_log_callback_t)(int severity, const char *message, void *user_info)

Callback function prototype to receive logging information.

Receives logging information consisting of severity level and message. Use e.g. ca_rango_log_callback() to register a callback.

It allows passing of an optional void pointer to user specified data.

Parameters
[in]severitySeverity level. 1: debug, 2: info, 3: warn, 4: error.
[in]messageThe log message
[in]user_infoOptional pointer as specified by ca_rango_log_callback()

Function Documentation

int ca_points_load ( float **  points,
const char *  points_file_name,
int *  num_points 
)

Loads and allocates 3D point data.

The loaded points are actually 4 dimensional, with the 4th dimension always being zero. Use ca_points_destroy(float** data) to free the allocated data. See Points & Normals for details on the points format, and XYZ Point Clouds for the file format.

Parameters
[out]pointsThe points data, will be allocated.
[in]points_file_nameThe file name to load.
[out]num_pointsWill contain the number of points. 4 times that will be allocated.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_points_save ( const float *  points,
const char *  points_file_name,
int  num_points 
)

Saves the float array as a text file.

This is just a helper method for convenience.

Parameters
[in]pointsThe points to save.
[in]points_file_nameThe filename, e.g. "points.xyz".
[in]num_pointsNumber of points to save.
Returns
Error code, zero on success.
int ca_points_destroy ( float **  data)

Destroys points or transforms previously created with ca_points_load.

Parameters
[in,out]dataPoints will be deleted and set to 0.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_transforms_destroy ( float **  data)

Destroys transforms or transforms previously created with ca_points_load.

Parameters
[in,out]dataPoints will be deleted and set to 0.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_chars_destroy ( char **  data)

Destroys character data allocated e.g. when retrieving field data.

Parameters
[in,out]dataCharacter data to be destroyed.
Returns
Error code, zero on success.
Examples:
example_configuration_visualization.cpp.
int ca_build_version ( const char **  data)

Reads the version of the CANDELOR SDK.

The format is YY.MM.X, where YY is the year of the build, MM the month, and X is an ever increasing build number. No memory is allocated, so don't use ca_chars_destroy().

Parameters
[out]dataNull terminated character data for version number, e.g. "13.04-17"
Returns
Error code, zero on success.
int ca_build_date ( int *  build_date)

Gets timestamp of the build.

The format is in YYYYMMDD, returned as a number.

Parameters
[out]build_dateThe build date.
Returns
Error code, zero on success.