AugmentedImageDatabase

Typedefs
typedef struct ArAugmentedImageDatabase_	ArAugmentedImageDatabase

Functions
void	ArAugmentedImageDatabase_create (const ArSession *session, ArAugmentedImageDatabase **out_augmented_image_database)
	Creates a new empty image database.
ArStatus	ArAugmentedImageDatabase_deserialize (const ArSession *session, const uint8_t *database_raw_bytes, int64_t database_raw_bytes_size, ArAugmentedImageDatabase **out_augmented_image_database)
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)
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)
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)
void	ArAugmentedImageDatabase_getNumImages (const ArSession *session, const ArAugmentedImageDatabase *augmented_image_database, int32_t *out_num_images)
	Returns the number of images in the image database.
void	ArAugmentedImageDatabase_destroy (ArAugmentedImageDatabase *augmented_image_database)
	Releases memory used by an image database.

Detailed Description

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

Typedef Documentation

ArAugmentedImageDatabase

typedef 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 TRACKING/PAUSED state will immediately be set to the 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()

Definition at line 334 of file arcore_c_api.h.

Function Documentation

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 (20ms - 30ms), and should be run on a background thread.

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

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.

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 (20ms - 30ms), and should be run on a background thread.

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

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.

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.

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_num_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.