ArAugmentedImageDatabase

Database containing a list of images to be detected and tracked by ARCore.

Summary

Typedefs

ArAugmentedImageDatabase typedef
struct ArAugmentedImageDatabase_
A database of images to be detected and tracked by ARCore (value type).

Functions

ArAugmentedImageDatabase_addImage(const ArSession *session, ArAugmentedImageDatabase *augmented_image_database, const char *image_name, const uint8_t *image_grayscale_pixels, int32_t image_width_in_pixels, int32_t image_height_in_pixels, int32_t image_stride_in_pixels, int32_t *out_index)
Adds a single named image of unknown physical size to an image database, from an array of grayscale pixel values.
ArAugmentedImageDatabase_addImageWithPhysicalSize(const ArSession *session, ArAugmentedImageDatabase *augmented_image_database, const char *image_name, const uint8_t *image_grayscale_pixels, int32_t image_width_in_pixels, int32_t image_height_in_pixels, int32_t image_stride_in_pixels, float image_width_in_meters, int32_t *out_index)
Adds a single named image to an image database, from an array of grayscale pixel values, along with a positive physical width in meters for this image.
ArAugmentedImageDatabase_create(const ArSession *session, ArAugmentedImageDatabase **out_augmented_image_database)
void
Creates a new empty image database.
ArAugmentedImageDatabase_deserialize(const ArSession *session, const uint8_t *database_raw_bytes, int64_t database_raw_bytes_size, ArAugmentedImageDatabase **out_augmented_image_database)
Creates a new image database from a byte array.
ArAugmentedImageDatabase_destroy(ArAugmentedImageDatabase *augmented_image_database)
void
Releases memory used by an image database.
ArAugmentedImageDatabase_getNumImages(const ArSession *session, const ArAugmentedImageDatabase *augmented_image_database, int32_t *out_number_of_images)
void
Returns the number of images in the image database.
ArAugmentedImageDatabase_serialize(const ArSession *session, const ArAugmentedImageDatabase *augmented_image_database, uint8_t **out_image_database_raw_bytes, int64_t *out_image_database_raw_bytes_size)
void
Serializes an image database to a byte array.

Typedefs

ArAugmentedImageDatabase

struct ArAugmentedImageDatabase_ ArAugmentedImageDatabase

A database of images to be detected and tracked by ARCore (value type).

An image database supports up to 1000 images. A database can be generated by the arcoreimg command-line database generation tool provided in the SDK, or dynamically created at runtime by adding individual images.

Only one image database can be active in a session. Any images in the currently active image database that have a AR_TRACKING_STATE_TRACKING or AR_TRACKING_STATE_PAUSED state will immediately be set to the AR_TRACKING_STATE_STOPPED state if a different or NULL image database is made active in the current session Config.

Functions

ArAugmentedImageDatabase_addImage

ArStatus ArAugmentedImageDatabase_addImage(
  const ArSession *session,
  ArAugmentedImageDatabase *augmented_image_database,
  const char *image_name,
  const uint8_t *image_grayscale_pixels,
  int32_t image_width_in_pixels,
  int32_t image_height_in_pixels,
  int32_t image_stride_in_pixels,
  int32_t *out_index
)

Adds a single named image of unknown physical size to an image database, from an array of grayscale pixel values.

Returns the zero-based positional index of the image within the image database.

If the physical size of the image is known, use ArAugmentedImageDatabase_addImageWithPhysicalSize instead, to improve image detection time.

For images added via ArAugmentedImageDatabase_addImage, ARCore estimates the physical image's size and pose at runtime when the physical image is visible and is being tracked. This extra estimation step will require the user to move their device to view the physical image from different viewpoints before the size and pose of the physical image can be estimated.

This function takes time to perform non-trivial image processing (20-30ms), and should be run on a background thread.

The image name is expected to be a null-terminated string in UTF-8 format.

Currently, only images for which the stride is equal to the width are supported.

Details
Returns
AR_SUCCESS or any of:

ArAugmentedImageDatabase_addImageWithPhysicalSize

ArStatus ArAugmentedImageDatabase_addImageWithPhysicalSize(
  const ArSession *session,
  ArAugmentedImageDatabase *augmented_image_database,
  const char *image_name,
  const uint8_t *image_grayscale_pixels,
  int32_t image_width_in_pixels,
  int32_t image_height_in_pixels,
  int32_t image_stride_in_pixels,
  float image_width_in_meters,
  int32_t *out_index
)

Adds a single named image to an image database, from an array of grayscale pixel values, along with a positive physical width in meters for this image.

Returns the zero-based positional index of the image within the image database.

If the physical size of the image is not known, use ArAugmentedImageDatabase_addImage instead, at the expense of an increased image detection time.

For images added via ArAugmentedImageDatabase_addImageWithPhysicalSize, ARCore can estimate the pose of the physical image at runtime as soon as ARCore detects the physical image, without requiring the user to move the device to view the physical image from different viewpoints. Note that ARCore will refine the estimated size and pose of the physical image as it is viewed from different viewpoints.

This function takes time to perform non-trivial image processing (20-30ms), and should be run on a background thread.

The image name is expected to be a null-terminated string in UTF-8 format.

Currently, only images for which the stride is equal to the width are supported.

Details
Returns
AR_SUCCESS or any of:

ArAugmentedImageDatabase_create

void ArAugmentedImageDatabase_create(
  const ArSession *session,
  ArAugmentedImageDatabase **out_augmented_image_database
)

Creates a new empty image database.

ArAugmentedImageDatabase_deserialize

ArStatus ArAugmentedImageDatabase_deserialize(
  const ArSession *session,
  const uint8_t *database_raw_bytes,
  int64_t database_raw_bytes_size,
  ArAugmentedImageDatabase **out_augmented_image_database
)

Creates a new image database from a byte array.

The contents of the byte array must have been generated by the command-line database generation tool provided in the SDK, or at runtime from ArAugmentedImageDatabase_serialize.

Note: this function takes about 10-20ms for a 5MB byte array. Run this in a background thread if this affects your application.

Details
Returns
AR_SUCCESS or any of:

ArAugmentedImageDatabase_destroy

void ArAugmentedImageDatabase_destroy(
  ArAugmentedImageDatabase *augmented_image_database
)

Releases memory used by an image database.

ArAugmentedImageDatabase_getNumImages

void ArAugmentedImageDatabase_getNumImages(
  const ArSession *session,
  const ArAugmentedImageDatabase *augmented_image_database,
  int32_t *out_number_of_images
)

Returns the number of images in the image database.

ArAugmentedImageDatabase_serialize

void ArAugmentedImageDatabase_serialize(
  const ArSession *session,
  const ArAugmentedImageDatabase *augmented_image_database,
  uint8_t **out_image_database_raw_bytes,
  int64_t *out_image_database_raw_bytes_size
)

Serializes an image database to a byte array.

This function will allocate memory for the serialized raw byte array, and set *out_image_database_raw_bytes to point to that byte array. The caller is expected to release the byte array using ArByteArray_release when the byte array is no longer needed.