`arcoreimg` is a command line tool that takes a set of reference images and generates
an image database file. This tool is available in the
[ARCore SDK for Android](https://github.com/google-ar/arcore-android-sdk/releases) (see **tools \> arecoreimg**),
and is for only Android and Android NDK developers.

The tool also lets you check the quality of your reference images.

## Check image quality

A good reference image is hard to spot with the human eye. Run `arcoreimg eval-img` to get a quality score between **0** and **100** for each image.

We recommend using images with a score of **at least 75**.

### macOS

<br />

```
./arcoreimg eval-img --input_image_path=dog.jpg
```

### Windows

<br />

```
arcoreimg.exe eval-img --input_image_path=dog.png
```

## Create an image database file

You can supply reference images in a **directory** or via an **image list file** (preferred).
Note that only PNG and JPEG images are supported, and only ASCII characters are
supported in image filenames.

### Create image database from a directory of images

Run `arcoreimg build-db` using `--input_images_directory` to specify a
directory that contains your images as shown below:

### macOS

<br />

```
./arcoreimg build-db --input_images_directory=/path/to/images \
                       --output_db_path=/path/to/myimages.imgdb
```

### Windows

<br />

```
arcoreimg.exe build-db --input_images_directory=/path/to/images --output_db_path=/path/to/myimages.imgdb
```

Each image is assigned a default name based on its path. For example, `dog.jpg`
is assigned `/path/to/images/dog.jpg` as its name.

Each image is also assigned a `0`-based integer index, based on the ASCII sort
order of the image filenames.

All images will be assumed to have an unknown physical width in meters.

### Create a database from an image list file (Preferred)

The format of the image list file is shown below:

```
mouse|path/to/mouse.png|0.1
little dog|/path/to/dog.jpg
```

Each line contains a **name** , the **image file path** , and the image's
**physical width in meters** (optional).

Run `arcoreimg build-db` using `--input_image_list_path` to specify an image
list file as shown below:

### macOS

<br />

```
./arcoreimg build-db --input_image_list_path=/path/to/image_list_file.txt \
                       --output_db_path=/path/to/myimages.imgdb
```

### Windows

<br />

```
arcoreimg.exe build-db --input_image_list_path=/path/to/image_list_file.txt --output_db_path=/path/to/myimages.imgdb
```

Each image is assigned a **name** and a `0`-based **index** based on its
position in the image list file.

### Identifying images at runtime

Use [`AugmentedImage.getIndex()`](https://developers.google.com/ar/reference/java/com/google/ar/core/AugmentedImage#getIndex())
and [`AugmentedImage.getName()`](https://developers.google.com/ar/reference/java/com/google/ar/core/AugmentedImage#getName())
to identify detected images.