# ArAugmentedImageDatabase

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

## Summary

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase` | typedef `struct ArAugmentedImageDatabase_` A database of images to be detected and tracked by ARCore ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_addimage(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#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)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Adds a single named image of unknown physical size to an image database, from an array of grayscale pixel values. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_addimagewithphysicalsize(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#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)` | `https://developers.google.com/ar/reference/c/group/shared-types#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. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_create(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase **out_augmented_image_database)` | `void` Creates a new empty image database. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_deserialize(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const uint8_t *database_raw_bytes, int64_t database_raw_bytes_size, https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase **out_augmented_image_database)` | `https://developers.google.com/ar/reference/c/group/shared-types#arstatus` Creates a new image database from a byte array. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_destroy(https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase *augmented_image_database)` | `void` Releases memory used by an image database. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_getnumimages(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase *augmented_image_database, int32_t *out_number_of_images)` | `void` Returns the number of images in the image database. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_serialize(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#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](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).

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 `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking` or `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused` state will immediately be set to the `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped` state if a different or `NULL` image database is made active in the current session Config.


- Create with: `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_create` or `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_deserialize`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_destroy`

<br />

## 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 `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_addimagewithphysicalsize` instead, to improve image detection time.

For images added via `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#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** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_image_insufficient_quality` - image quality is insufficient, e.g. because of lack of features in the image. - `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#araugmentedimagedatabase_addimage` instead, at the expense of an increased image detection time.

For images added via `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#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** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_image_insufficient_quality` - image quality is insufficient, e.g. because of lack of features in the image. - `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/ar-augmented-image-database#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** | `https://developers.google.com/ar/reference/c/group/shared-types#ar_success` or any of: - `https://developers.google.com/ar/reference/c/group/shared-types#ar_error_data_invalid_format` - the bytes are in an invalid format. - `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/utility-functions#arbytearray_release` when the byte array is no longer needed.