C Reference

Enumerations

enum frc_status

Status of the API call

Values:

enumerator FRC_STATUS_OK

enumerator FRC_STATUS_ERROR

enumerator FRC_STATUS_INVALID_ARGUMENT

enumerator FRC_STATUS_UNINITIALIZED

enumerator FRC_STATUS_ERROR_LICENSE_ACTIVATION_FAILURE

enumerator FRC_STATUS_ERROR_INVALID_LICENSE

enumerator FRC_STATUS_ERROR_INIT_SDK

enumerator FRC_STATUS_ERROR_RECON_NO_LICENSED

enumerator FRC_STATUS_ERROR_RECON_CONFIG

enumerator FRC_STATUS_ERROR_SCANNING_NO_LICENSED

enumerator FRC_STATUS_ERROR_SCANNING_CONFIG

enumerator FRC_STATUS_ERROR_SCANNING_INVALID_CAPTURE

enumerator FRC_STATUS_ERROR_SYSTEM

enum frc_image_format_t

Image format type.

Remark

The image format indicates how the frc_image_t buffer data is interpreted.

Values:

enumerator FRC_IMAGE_FORMAT_COLOR_RGB24

Color image type RGB24.

Each pixel of RGB24 data is thredd bytes. The first three bytes represent Red, Green, and Blue data.

Stride indicates the length of each line in bytes and should be used to determine the start location of each line of the image in memory.

enumerator FRC_IMAGE_FORMAT_DEPTH16

Depth image type DEPTH16.

Each pixel of DEPTH16 data is two bytes of little endian unsigned depth data. The unit of the data is in millimeters from the origin of the camera.

Stride indicates the length of each line in bytes and should be used to determine the start location of each line of the image in memory.

enumerator FRC_IMAGE_FORMAT_IR16

Image type IR16.

Each pixel of IR16 data is two bytes of little endian unsigned depth data. The value of the data represents brightness.

This format represents infrared light and is captured by the depth camera.

Stride indicates the length of each line in bytes and should be used to determine the start location of each line of the image in memory.

enumerator FRC_IMAGE_FORMAT_MAX

Image type Unsupported.

enum frc_depth_unit_t

Accuracy of camera depth values

Values:

enumerator FRC_DEPTH_1_MM

The unit is 1mm

enumerator FRC_DEPTH_100_UM

The unit is 100um

enum frc_scan_flag_t

Switch of start collecting keyframe

Values:

enumerator FRC_SCAN_FLAG_INIT

collecting is not started

enumerator FRC_SCAN_FLAG_START

collecting is started

enum frc_rect_flag_t

Switch of output face rect of each frame

Values:

enumerator FRC_RECT_FLAG_OFF

do not output face detection rect

enumerator FRC_RECT_FLAG_ON

output face detection rect

enum frc_frame_status_t

Status of the input stream after processing

Values:

enumerator FRC_FRAME_STATUS_NO_FACE_DETECTED

The face is not detected

enumerator FRC_FRAME_STATUS_TOO_ClOSE

The face is too close

enumerator FRC_FRAME_STATUS_TOO_FAR

The face is too far

enumerator FRC_FRAME_STATUS_NOT_FRONT

The face is not front face

enumerator FRC_FRAME_STATUS_DEPTH_QUALITY_POOR

The depth quality of face is poor

enumerator FRC_FRAME_STATUS_FRONT_FACE_KEYFRAME

The face is front face and the frame is frontface-keyframe

enumerator FRC_FRAME_STATUS_OTHER_FACE_KEYFRAME

The frame is other keyframe not front face

enumerator FRC_FRAME_STATUS_NOT_FACE_KEYFRAME

The frame is not keyframe

enumerator FRC_FRAME_STATUS_TRICKING_FAIL

The frame is tracking failed

enumerator FRC_FRAME_STATUS_UNKNOWN

The init status of frame

Structures

struct frc_version_t

Version information.

Public Members

int major

Major version number, incremented for major API restructuring.

int minor

Minor version number, incremented when significant new features added.

int patch

Maintenance build number, incremented for new releases that primarily provide minor bug fixes.

struct frc_calibration_t

Calibration type representing sensor calibration.

Public Members

float fx

Focal length x

float fy

Focal length y

float cx

Principal point in image, x

float cy

Principal point in image, y

int color_width

Resolution width of the color sensor.

int color_height

Resolution height of the color sensor.

int depth_width

Resolution width of the depth sensor.

int depth_height

Resolution height of the depth sensor.

frc_depth_unit_t depth_unit

Unit of the depth sensor.

struct frc_rect_t

Structure to define a rect of face detection.

Public Members

int x

The point on the top left of the rect, x

int y

The point on the top left of the rect, y

int width

The width of the rect.

int height

The height of the rect.

struct frc_keyframe_t

Structure to define a keyframe

Public Members

int id

The id of each keyframe (1~11)

frc_rect_t rect

The face rect of each keyframe

float transform[4][4]

The pose of each keyframe

float landmark[68 * 3]

The 68 face keypoints of each keyframe

frc_frame_status_t status

The status of each keyframe

struct frc_scanner_configuration_t

Structure to define a config

Public Members

float frontface_config

The id of each keyframe (1~11)

frc_rect_flag_t rect_config

Switch of output face rect of each frame

struct frc_build_result_t

Structure to define a model result

Public Members

unsigned char *texture

The model texture image pointer of result

unsigned char *semantic

The model semantic image pointer of result

int *faces

The model face pointer of result

float *vertices

The model vertices of result

float *uv

The model uv index of result

int num_of_verts

The number of vertices

int num_of_faces

The number of faces

int texture_height

The model texture image height

int texture_width

The model texture image width

std::vector<std::vector<float>> landmarks3D

The model landmark of result

Handles

class frc_image_t

Handle to an image.

Remark

A frc_image_t manages an image buffer and associated metadata.

Remark

Images may be of one of the standard frc_image_format_t formats, The format defines how the underlying image buffer should be interpreted.

Remark

Images stored in a frc_capture_t are referenced by the frc_capture_t until they are replaced or the frc_capture_t is destroyed.

Remark

The caller must call frc_image_release() to release its reference

Remark

Additional references to the image may be obtained with frc_image_reference().

Remark

An invalid frc_image_t will be set to 0.

class frc_capture_t

Handle to an capture.

Remark

A capture represents a set of images that were captured by a device at approximately the same time. A capture may have a color, IR, and depth image. A capture may have no image for a given type as well.

Remark

The capture will add a reference on any frc_image_t that is added to it with one of the setters like frc_capture_set_color_image(). If an existing image is being replaced, the previous image will have the reference released.

Remark

Once all references to the frc_capture_t are released, the capture will release the references it holds on any frc_image_t that are associated with it.

Remark

When a capture returns an image to the caller with an accessor like frc_capture_get_color_image(), a new reference is added to the frc_image_t and the caller is responsible for releasing that reference with frc_image_release().

Remark

Empty captures are created with frc_capture_create().

Remark

Captures can be obtained from scanner using frc_frame_get_capture().

Remark

The caller must call frc_capture_release() to release its reference.

Remark

Additional references to the capture may be obtained with frc_capture_reference().

Remark

An invalid frc_capture_t will be set to 0.

class frc_frame_t

Handle to a frc face scanning frame.

Handles are created with frc_scanner_process() and closed with frc_frame_release(). Invalid handles are set to 0.

class frc_scanner_t

Handle to frc face scanning component.

Handles are created with frc_scaner_create() and destroyed with frc_scanner_destroy(). Invalid handles are set to 0.

class frc_builder_t

Handle to frc face building component.

Handles are created with frc_builder_create() and destroyed. Invalid handles are set to 0.

Functions

frc_status frc_set_license(const char *app_key, const char *app_secret, const char *auth_code)

Set the license authentication information.

Remark

In general, when frc_initialize() is called, it read license information from configuration file(frc.properites). This function provides a means to override the default behavior. This function should be called before frc_initialize(), The SDK uses the information provided by this function to authenticate the license.

参数:

• app_key – The app key.

• app_secret – The app secret.

• auth_code – The auth code.

返回:

Status code indicating success or failure of this operation.

frc_status frc_initialize(const char *working_directory)

Initialize the library. It is forbidden to call any other method in SDK before calling frc_initialize().

参数:

working_directory – The SDK load resource such as license files and model files from working directory.

frc_status frc_terminate()

Stop using the library. Once frc_terminate was called, no other calls to SDK is allowed.

frc_status frc_get_version(frc_version_t *version)

Get the version numbers of the SDK.

返回:

A return of ::FRC_STATUS_OK means that the version structure has been filled in. All other failures return ::FRC_STATUS_ERROR.

frc_status frc_image_create(frc_image_format_t format, int width_pixels, int height_pixels, int stride_bytes, const uint8_t *data, frc_image_t *image_handle)

Create an image from a pre-allocated buffer.

Remark

This function is used to create images of formats that have consistent stride. The function is not suitable for compressed formats that may not be represented by the same number of bytes per line.

Remark

For most image formats, the function will allocate an image buffer of size height_pixels * stride_bytes.

Remark

When finished using the created image, release it with frc_image_release.

参数:

• format – The format of the image that will be stored in this image container.

• width_pixels – Width in pixels.

• height_pixels – Height in pixels.

• stride_bytes – The number of bytes per horizontal line of the image. If set to 0, the stride will be set to the minimum size given the format and width_pixels.

• data – Pointer to a pre-allocated image buffer which will be copied into an internal buffer that allocated by SDK.

• image_handle – Pointer to store image handle in.

返回:

Returns FRC_STATUS_OK on success. Errors are indicated with FRC_STATUS_ERROR.

frc_status frc_image_reference(frc_image_t image_handle)

Add a reference to the frc_image_t.

Remark

References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must not access the object after its reference is released.

参数:

image_handle – Handle of the image for which the get operation is performed on.

frc_status frc_image_release(frc_image_t image_handle)

Remove a reference from the frc_image_t.

Remark

References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must not access the object after its reference is released.

参数:

image_handle – Handle of the image for which the get operation is performed on.

uint8_t *frc_image_get_buffer(frc_image_t image_handle)

Get the image buffer.

Remark

Use this buffer to access the raw image data.

参数:

image_handle – Handle of the image for which the get operation is performed on.

返回:

The function will return NULL if there is an error, and will normally return a pointer to the image buffer. Since all frc_image_t instances are created with an image buffer, this function should only return NULL if the image_handle is invalid.

size_t frc_image_get_size(frc_image_t image_handle)

Get the image buffer size.

Remark

Use this function to know what the size of the image buffer is returned by frc_image_get_buffer().

参数:

image_handle – Handle of the image for which the get operation is performed on.

返回:

The function will return 0 if there is an error, and will normally return the image size. Since all frc_image_t instances are created with an image buffer, this function should only return 0 if the image_handle is invalid.

frc_image_format_t frc_image_get_format(frc_image_t image_handle)

Get the format of the image.

Remark

Use this function to determine the format of the image buffer.

参数:

image_handle – Handle of the image for which the get operation is performed on.

返回:

This function is not expected to fail, all frc_image_t’s are created with a known format. If the image_handle is invalid, the function will return FRC_IMAGE_FORMAT_MAX.

int frc_image_get_width(frc_image_t image_handle)

Get the image width in pixels.

参数:

image_handle – Handle of the image for which the get operation is performed on.

返回:

This function is not expected to fail, all frc_image_t’s are created with a known width. If the image_handle is invalid, the function will return 0.

int frc_image_get_height(frc_image_t image_handle)

Get the image height in pixels.

参数:

image_handle – Handle of the image for which the get operation is performed on.

返回:

This function is not expected to fail, all frc_image_t’s are created with a known height. If the image_handle is invalid, the function will return 0.

int frc_image_get_stride(frc_image_t image_handle)

Get the image stride in bytes.

参数:

image_handle – Handle of the image for which the get operation is performed on.

返回:

This function is not expected to fail, all frc_image_t’s are created with a known stride. If the image_handle is invalid, or the image’s format does not have a stride, the function will return 0.

frc_status frc_capture_create(frc_capture_t *capture_handle)

Create an empty capture object.

The new capture is created with a reference count of 1.

Remark

Call this function to create a frc_capture_t handle for a new capture. Release it with frc_capture_release().

参数:

capture_handle – Pointer to a location to store the handle.

返回:

Returns FRC_STATUS_OK on success. Errors are indicated with FRC_STATUS_ERROR and error specific data can be found in the log.

frc_status frc_capture_reference(frc_capture_t capture_handle)

Add a reference to a capture.

Remark

Call this function to add an additional reference to a capture. This reference must be removed with frc_capture_release().

参数:

capture_handle – Capture to add a reference to.

frc_status frc_capture_release(frc_capture_t capture_handle)

Release a capture.

Remark

Call this function when finished using the capture.

参数:

capture_handle – Capture to release.

frc_image_t frc_capture_get_color_image(frc_capture_t capture_handle)

Get the color image associated with the given capture.

Remark

Call this function to access the color image part of this capture. Release the frc_image_t with frc_image_release();

参数:

capture_handle – Capture handle containing the image.

frc_image_t frc_capture_get_depth_image(frc_capture_t capture_handle)

Get the depth image associated with the given capture.

Remark

Call this function to access the depth image part of this capture. Release the frc_image_t with frc_image_release();

参数:

capture_handle – Capture handle containing the image.

frc_image_t frc_capture_get_ir_image(frc_capture_t capture_handle)

Get the IR image associated with the given capture.

Remark

Call this function to access the IR image part of this capture. Release the frc_image_t with frc_image_release();

参数:

capture_handle – Capture handle containing the image.

frc_status frc_capture_set_color_image(frc_capture_t capture_handle, frc_image_t image_handle)

Set or add a color image to the associated capture.

Remark

When a frc_image_t is added to a frc_capture_t, the frc_capture_t will automatically add a reference to the frc_image_t.

Remark

If there is already a color image contained in the capture, the existing image will be dereferenced and replaced with the new image.

Remark

To remove a color image to the capture without adding a new image, this function can be called with a NULL image_handle.

Remark

Any frc_image_t contained in this frc_capture_t will automatically be dereferenced when all references to the frc_capture_t are released with frc_capture_release().

参数:

• capture_handle – Capture handle to hold the image.

• image_handle – Image handle containing the image.

frc_status frc_capture_set_depth_image(frc_capture_t capture_handle, frc_image_t image_handle)

Set or add a depth image to the associated capture.

Remark

When a frc_image_t is added to a frc_capture_t, the frc_capture_t will automatically add a reference to the frc_image_t.

Remark

If there is already an image depth image contained in the capture, the existing image will be dereferenced and replaced with the new image.

Remark

To remove a depth image to the capture without adding a new image, this function can be called with a NULL image_handle.

Remark

Any frc_image_t contained in this frc_capture_t will automatically be dereferenced when all references to the frc_capture_t are released with frc_capture_release().

参数:

• capture_handle – Capture handle to hold the image.

• image_handle – Image handle containing the image.

frc_status frc_capture_set_ir_image(frc_capture_t capture_handle, frc_image_t image_handle)

Set or add an IR image to the associated capture.

Remark

When a frc_image_t is added to a frc_capture_t, the frc_capture_t will automatically add a reference to the frc_image_t.

Remark

If there is already an IR image contained in the capture, the existing image will be dereferenced and replaced with the new image.

Remark

To remove a IR image to the capture without adding a new image, this function can be called with a NULL image_handle.

Remark

Any frc_image_t contained in this frc_capture_t will automatically be dereferenced when all references to the frc_capture_t are released with frc_capture_release().

参数:

• capture_handle – Capture handle to hold the image.

• image_handle – Image handle containing the image.

frc_status frc_frame_create(frc_frame_t *frame_handle)

Create an empty frame object.

The new frame is created with a reference count of 1.

Remark

Call this function to create a frc_frame_t handle for a new frame. Release it with frc_frame_release().

参数:

frame_handle – Pointer to a location to store the handle.

返回:

Returns #FRC_STATUS_OK on success. Errors are indicated with #FRC_STATUS_ERROR and error specific data can be found in the log.

frc_status frc_frame_reference(frc_frame_t frame_handle)

Add a reference to a face frame.

Remark

Call this function to add an additional reference to a face frame. This reference must be removed with frc_frame_release().

Remark

This function is not thread-safe.

参数:

frame_handle – face frame to add a reference to.

frc_status frc_frame_release(frc_frame_t frame_handle)

Release a face frame

Remark

Called when the user is finished using the face frame.

参数:

frame_handle – Handle to a face frame object.

frc_capture_t frc_frame_get_capture(frc_frame_t frame_handle)

Get the original capture that is used to calculate the frc_frame_t

Remark

Called when the user has received a face frame handle and wants to access the data contained in it.

参数:

frame_handle – Handle to a face frame object returned by frc_scanner_process function.

返回:

Call this function to access the original frc_capture_t. Release this capture with frc_capture_release().

frc_keyframe_t frc_frame_get_keyframe(frc_frame_t frame_handle)

Get the keyframe data that is used to check and save frame

Remark

Called when the user has received a face frame handle and wants to access the data contained in it.

参数:

frame_handle – Handle to a face frame object returned by frc_scanner_process function.

返回:

Call this function to access the original frc_keyframe_t. Release this capture with frc_capture_release().

frc_status frc_frame_set_capture(frc_frame_t frame_handle, frc_capture_t capture_handle)

Set or add a capture to the frame.

参数:

• frame_handle – Handle to a face frame object returned by frc_frame_create function.

• capture_handle – Capture handle containing the capture.

frc_status frc_frame_set_keyframe(frc_frame_t frame_handle, frc_keyframe_t *keyframe)

Set or add a keyframe data to the frame.

参数:

• frame_handle – Handle to a face frame object returned by frc_frame_create function.

• keyframe – keyframe containing the keyframe data.

frc_status frc_scanner_create(frc_scanner_configuration_t config, frc_calibration_t calibration, frc_scanner_t *scanner_handle)

Create a face scanner handle.

Remark

If successful, frc_scanner_create() will return a face scanner handle in the scaner parameter.

Remark

When done with face scanning, close the handle with frc_scanner_destroy().

参数:

• calibration – The sensor calibration that will be used for capture processing.

• scanner_handle – Output parameter which on success will return a handle to the face scanner.

返回:

FRC_STATUS_OK if the face scanner handle was created successfully.

frc_status frc_scanner_destroy(frc_scanner_t scanner_handle)

Releases a face scanner handle.

Remark

Once released, the scanner_handle is no longer valid.

参数:

scanner_handle – Handle obtained by frc_scanner_create().

frc_status frc_scanner_process(frc_scanner_t scanner_handle, frc_capture_t capture_handle, frc_scan_flag_t scan_flag, frc_frame_t *frame_handle)

Add a sensor capture to the scanner to generate its face scanning result synchronously.

参数:

• scanner_handle – Handle obtained by frc_scanner_create().

• capture_handle – Handle to a sensor capture returned by frc_capture_create(). It should contain the color data and/or depth data for this function to work. Otherwise the function will return failure.

• frame_handle – If successful this contains a handle to a face frame object. Caller must call frc_release_frame() when its done using this frame.

• scan_flag – If scan_flag is FRC_SCAN_FLAG_INIT,scanning is not started. If scan_flag is FRC_SCAN_FLAG_START,scanning is started using this frame.

返回:

Returns #FRC_STATUS_OK on success. Errors are indicated with #FRC_STATUS_ERROR and error specific data can be found in the log.

frc_status frc_builder_create(frc_calibration_t calibration, frc_builder_t *builder_handle)

Create a face builder handle.

Remark

If successful, frc_builder_create() will return a face builder handle in the builder parameter.

Remark

When done with face building, close the handle with frc_builder_destroy().

参数:

• calibration – The sensor calibration that will be used for builder processing.

• builder_handle – Output parameter which on success will return a handle to the face builder.

返回:

FRC_STATUS_OK if the face builder handle was created successfully.

frc_status frc_builder_destroy(frc_builder_t builder_handle)

Releases a face builder handle.

Remark

Once released, the builder_handle is no longer valid.

参数:

builder_handle – Handle obtained by frc_builder_create().

frc_status frc_builder_addframe(frc_builder_t builder_handle, frc_frame_t key_frame)

Releases a face builder handle.

Remark

Once released, the builder_handle is no longer valid.

参数:

• builder_handle – Handle obtained by frc_builder_create().

• frame_handle – It should contain the color data,depth data and keyframe data for this function to work. Otherwise the function will return failure.

frc_status frc_builder_process(frc_builder_t builder_handle, frc_build_result_t *build_result)

Add a sensor capture to the builder to generate its face building result synchronously.

参数:

• builder_handle – Handle obtained by frc_builder_create().

• frc_build_result_t – pointer If successful this contains a handle to a model result object.

返回:

Returns FRC_STATUS_OK on success. Errors are indicated with FRC_STATUS_ERROR and error specific data can be found in the log.

frc_status frc_builder_set_multi_thread(frc_builder_t builder_handle, bool is_multi_thread)

Set multi thread while reconstructing, but it will cost more cpu resource

参数:

• builder_handle – Handle obtained by frc_builder_create().

• is_multi_thread – Tt should be set as true or false. if it’s true, fully multi thread speed up will be opened.

frc_status frc_build_result_release(frc_build_result_t *build_result)

Releases a build result pointer.

Remark

Once released, the frc_build_result_t is no longer valid.

参数:

frc_build_result_t –