AugmentedImageDatabase

public class AugmentedImageDatabase

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

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 to an AugmentedImageDatabase.

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.

Public Constructors

AugmentedImageDatabase(Session session)
Creates a new empty image database.

Public Methods

int
addImage(String name, Bitmap bitmap)
Adds a single named image of unknown physical size to the augmented image database from an Android bitmap.
int
addImage(String name, Bitmap bitmap, float widthInMeters)
Adds a single named image with known physical size to the augmented image database from an Android bitmap, with a specified physical width in meters.
static AugmentedImageDatabase
deserialize(Session session, InputStream inputStream)
Creates a new image database from an input stream.
int
getNumImages()
Returns the number of images in the database.
void
serialize(OutputStream outputStream)
Serializes the database to an OutputStream.

Inherited Methods

Public Constructors

AugmentedImageDatabase

public AugmentedImageDatabase(
  Session session
)

Creates a new empty image database.

Details
Parameters
session

Public Methods

addImage

public int addImage(
  String name,
  Bitmap bitmap
)

Adds a single named image of unknown physical size to the augmented image database from an Android bitmap. Returns the zero-based positional index of the image within the database.

If the physical size of the image is known, use addImage(String, Bitmap, float) instead, to improve image detection time.

For images added via this method, 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 method takes time to perform non-trivial image processing (20ms - 30ms), and should be run on a background thread to avoid blocking the UI thread.

Details
Parameters
name Name metadata for this image, does not have to be unique.
bitmap Bitmap containing the image in ARGB_8888 format. The alpha channel is ignored in this bitmap, as only non-transparent images are currently supported.
Throws
ImageInsufficientQualityException if the image quality is image is insufficient, e.g. if the image has not enough features.
IllegalArgumentException if the bitmap is not in ARGB_888 format.

addImage

public int addImage(
  String name,
  Bitmap bitmap,
  float widthInMeters
)

Adds a single named image with known physical size to the augmented image database from an Android bitmap, with a specified physical width in meters. Returns the zero-based positional index of the image within the database.

If the physical size of the image is not known, use addImage(String, Bitmap) instead, at the expense of an increased image detection time.

For images added via this method, 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 method takes time to perform non-trivial image processing (20ms - 30ms), and should be run on a background thread to avoid blocking the UI thread.

Details
Parameters
name Name metadata for this image, does not have to be unique.
bitmap Bitmap containing the image in ARGB_8888 format. The alpha channel is ignored in this bitmap, as only non-transparent images are currently supported.
widthInMeters Width in meters for this image, must be strictly greater than zero.
Throws
ImageInsufficientQualityException if the image quality is image is insufficient, e.g. if the image has not enough features.
IllegalArgumentException if the bitmap is not in ARGB_888 format or the width in meters is less than or equal to zero.

deserialize

public static AugmentedImageDatabase deserialize(
  Session session,
  InputStream inputStream
)

Creates a new image database from an input stream. The stream contents must have been generated by the command-line database generation tool provided in the SDK, or at runtime from serialize(OutputStream).

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

Details
Parameters
session
inputStream
Throws
DataInvalidFormatException if the input stream is not formatted properly as an image database.
DataUnsupportedVersionException if the database is incompatible with the current SDK.
IOException

getNumImages

public int getNumImages()

Returns the number of images in the database.

serialize

public void serialize(
  OutputStream outputStream
)

Serializes the database to an OutputStream.

Details
Parameters
outputStream
Throws
IOException