# ArAugmentedImage

An image being detected and tracked by ARCore.

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimagetrackingmethod{ https://developers.google.com/ar/reference/c/group/ar-augmented-image#ar_augmented_image_tracking_method_not_tracking = 0, https://developers.google.com/ar/reference/c/group/ar-augmented-image#ar_augmented_image_tracking_method_full_tracking = 1, https://developers.google.com/ar/reference/c/group/ar-augmented-image#ar_augmented_image_tracking_method_last_known_pose = 2 }` | enumDefines the current tracking mode for an Augmented Image. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage` | typedef `struct ArAugmentedImage_` An image that has been detected and tracked ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_acquirename(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#araugmentedimage *augmented_image, char **out_augmented_image_name)` | `void` Returns the name of this image. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getcenterpose(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#araugmentedimage *augmented_image, https://developers.google.com/ar/reference/c/group/ar-pose#arpose *out_pose)` | `void` Returns the pose of the center of the Augmented Image, in world coordinates. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getextentx(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#araugmentedimage *augmented_image, float *out_extent_x)` | `void` Retrieves the estimated width, in metres, of the corresponding physical image, as measured along the local X-axis of the coordinate space with origin and axes as defined by `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getcenterpose`. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getextentz(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#araugmentedimage *augmented_image, float *out_extent_z)` | `void` Retrieves the estimated height, in metres, of the corresponding physical image, as measured along the local Z-axis of the coordinate space with origin and axes as defined by `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getcenterpose`. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getindex(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#araugmentedimage *augmented_image, int32_t *out_index)` | `void` Returns the zero-based positional index of this image from its originating image database. |
| `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_gettrackingmethod(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#araugmentedimage *image, https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimagetrackingmethod *out_tracking_method)` | `void` Returns the current method being used to track this Augmented Image. |

## Enumerations

### ArAugmentedImageTrackingMethod

```
 ArAugmentedImageTrackingMethod
```
Defines the current tracking mode for an Augmented Image.

To retrieve the tracking mode for an image use `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_gettrackingmethod`.

| Properties ||
|---|---|
| `AR_AUGMENTED_IMAGE_TRACKING_METHOD_FULL_TRACKING` | The Augmented Image is currently being tracked using the camera image. |
| `AR_AUGMENTED_IMAGE_TRACKING_METHOD_LAST_KNOWN_POSE` | The Augmented Image is currently being tracked based on its last known pose, because it can no longer be tracked using the camera image. |
| `AR_AUGMENTED_IMAGE_TRACKING_METHOD_NOT_TRACKING` | The Augmented Image is not currently being tracked. |

## Typedefs

### ArAugmentedImage

```
struct ArAugmentedImage_ ArAugmentedImage
```
An image that has been detected and tracked ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Trackable type: `https://developers.google.com/ar/reference/c/group/ar-trackable#ar_trackable_augmented_image`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-trackable#artrackable_release`

<br />

## Functions

### ArAugmentedImage_acquireName

```
void ArAugmentedImage_acquireName(
  const ArSession *session,
  const ArAugmentedImage *augmented_image,
  char **out_augmented_image_name
)
```
Returns the name of this image.

The image name is not guaranteed to be unique.

This function will allocate memory for the name string, and set \*out_augmented_image_name to point to that string. The caller must release the string using `https://developers.google.com/ar/reference/c/group/utility-functions#arstring_release` when the string is no longer needed.

### ArAugmentedImage_getCenterPose

```
void ArAugmentedImage_getCenterPose(
  const ArSession *session,
  const ArAugmentedImage *augmented_image,
  ArPose *out_pose
)
```
Returns the pose of the center of the Augmented Image, in world coordinates.

The pose's transformed +Y axis will be the normal out of the plane. The pose's transformed +X axis points from left to right on the image, and the transformed +Z axis points from top to bottom on the image.

If the tracking state is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused` or `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped`, this returns the pose when the image state was last `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`, or the identity pose if the image state has never been `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`.

### ArAugmentedImage_getExtentX

```
void ArAugmentedImage_getExtentX(
  const ArSession *session,
  const ArAugmentedImage *augmented_image,
  float *out_extent_x
)
```
Retrieves the estimated width, in metres, of the corresponding physical image, as measured along the local X-axis of the coordinate space with origin and axes as defined by `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getcenterpose`.

ARCore will attempt to estimate the physical image's width and continuously update this estimate based on its understanding of the world. If the optional physical size is specified in the image database, this estimation process will happen more quickly. However, the estimated size may be different from the originally specified size.

If the tracking state is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused` or `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped`, this returns the estimated width when the image state was last `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. If the image state has never been `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`, this returns 0, even the image has a specified physical size in the image database.

### ArAugmentedImage_getExtentZ

```
void ArAugmentedImage_getExtentZ(
  const ArSession *session,
  const ArAugmentedImage *augmented_image,
  float *out_extent_z
)
```
Retrieves the estimated height, in metres, of the corresponding physical image, as measured along the local Z-axis of the coordinate space with origin and axes as defined by `https://developers.google.com/ar/reference/c/group/ar-augmented-image#araugmentedimage_getcenterpose`.

ARCore will attempt to estimate the physical image's height and continuously update this estimate based on its understanding of the world. If an optional physical size is specified in the image database, this estimation process will happen more quickly. However, the estimated size may be different from the originally specified size.

If the tracking state is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused` or `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_stopped`, this returns the estimated height when the image state was last `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`. If the image state has never been `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking`, this returns 0, even the image has a specified physical size in the image database.

### ArAugmentedImage_getIndex

```
void ArAugmentedImage_getIndex(
  const ArSession *session,
  const ArAugmentedImage *augmented_image,
  int32_t *out_index
)
```
Returns the zero-based positional index of this image from its originating image database.

This index serves as the unique identifier for the image in the database.

### ArAugmentedImage_getTrackingMethod

```
void ArAugmentedImage_getTrackingMethod(
  const ArSession *session,
  const ArAugmentedImage *image,
  ArAugmentedImageTrackingMethod *out_tracking_method
)
```
Returns the current method being used to track this Augmented Image.