Thanks for tuning in to Google I/O! Watch AR content on-demand.

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)`	`ArStatus` 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)`	`ArStatus` 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)`	`ArStatus` 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.

Create with: ArAugmentedImageDatabase_create or ArAugmentedImageDatabase_deserialize
Release with: ArAugmentedImageDatabase_destroy

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: `AR_ERROR_IMAGE_INSUFFICIENT_QUALITY` - image quality is insufficient, e.g. because of lack of features in the image. `AR_ERROR_INVALID_ARGUMENT` - if `image_stride_in_pixels` is not equal to `image_width_in_pixels`.

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: `AR_ERROR_IMAGE_INSUFFICIENT_QUALITY` - image quality is insufficient, e.g. because of lack of features in the image. `AR_ERROR_INVALID_ARGUMENT` - `image_width_in_meters` is <= 0 or if image_stride_in_pixels is not equal to `image_width_in_pixels`.

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: `AR_ERROR_DATA_INVALID_FORMAT` - the bytes are in an invalid format. `AR_ERROR_DATA_UNSUPPORTED_VERSION` - the database is not supported by this version of the SDK.

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.