How To Work with Device Databases

The purpose of a Device Database – also referred to as datasets in the SDK – is to provide the AR application with a locally accessible database of targets. You may download multiple device databases to include with your Vuforia Engine application. Each device database can contain a maximum of 20 Object Targets in combination with other target types. We recommend that you do not include more than 1000 targets (not including Object Targets) in a database.

The Vuforia Target Manager allows you to create and manage Device Database s and the targets within them before they are downloaded. For more information, see Getting Started with the Vuforia Target Manager .

How To Create a New Device Database

Device databases provide your AR application with a locally accessible database of targets. You can include multiple device databases in your AR application. The Target Manager allows you to create and manage those databases online, and provides download options for both Unity and native projects.

This article will show you how to create Device databases in the Target Manager.

  1. Go to the Target Manager in the Vuforia Engine Developer Portal.
  2. Press Add Database. The Create Database dialog opens.
  3. Name the database and select the Device database option. The database name should be unique for the developer account you are using.

  1. Press Create. You'll be taken back to the Target Manager database list.

How To Add Targets to a Device Database

Object Targets, Image Targets, Multi Targets and Cylinder Targets are created and managed using the Target Manager. The recommended maximum size for a Device Database is 1000 image-based targets (max 20 Object Targets), though it is possible to support a larger number of image-based targets depending on the images used. You'll need to test your datasets to confirm whether they'll work with more than 1000 targets.

Adding Targets to a Device Database

1. Go to the Target Manager Home Page. You will see a list of existing device databases.

2. In the list of databases, find and click the name of the device database in which you want to add a new target.

The parameters that you'll need to define for a target differ by target type as does the workflow for assigning and configuring target assets, such as images and object data files.

The steps for adding each type are documented below in the following order:

  1. Object Targets
  2. Image Targets
  3. Multi Targets
  4. Cylinder Targets

Add an Object Target to a Database

1. Click Add Target. The Add New Target dialog opens.

User-added image

2. Select the Object Data ( *.od ) file that you want to use for this target.

3. Type a unique name for the target in the Name field.

  • The name must be unique within this device database.
  • The name should describe the object.
  • The name can be changed later.
  • The name can only include letters, numbers, and the underscore character _ .

4. Click Add. After a short processing the Target Detail page opens with the result of the upload.

Add an Image Target to a Database

1. Click Add Target. The Add New Target dialog opens.

User-added image

2. Type a unique name for the target in the Name field.

  • The name must be unique within this device target database.
  • The name should describe the image.
  • The name can be changed later.
  • The name can only include letters, numbers, and the underscore character _ .

3. Select Single Image as the Target Type.

4. Enter the Width of the target in scene units.

NOTE: The width parameter is very important, as the pose information returned during tracking will be in the same scale. For example, if your image target is 16 units wide, moving the camera from the left border of the target to the right border of the target will change the returned position by 16 units along the x-axis. Enter the dimension of your target in the same scene unit as your augmentation. The size of the target shall be relative to the size of the augmented virtual content.

5. Browse to and select the image file. The file must be 8 or 24-bit PNG or JPG. A JPG file must be RGB or greyscale. Maximum image file size is 2.25MB.

6. Click Add. After a short processing the Target Detail page opens with the result of the upload. The rating and, if required, improvement recommendations display along with the target image.

Add a Multi Target (Cuboid) to a Database

1. Click Add Target. The Add New Target dialog opens.

User-added image

2. Type a unique name for the target in the Target Name field.

  • The name must be unique within this device target database.
  • The name should describe the image.
  • The name can be changed later.
  • The name can only include letters, numbers, and the underscore character _ .

3. Select Cube as the Target Type.

4. Enter the Width of the cube target in scene units.

NOTE: The width parameter is very important, as the pose information returned during tracking will be in the same scale. For example, if your cube target is 16 units wide, moving the camera from the left border of the target to the right border of the target will change the returned position by 16 units along the given axis. Enter the dimension of your target in the same scene unit as your augmentation. The size of the target shall be relative to the size of the augmented virtual content.

5. Click Add. A new target container is shown on the list of targets.

6. Click the new target container. A window opens with an empty target container with the specified dimensions. There is a 3D representation on the left and a layout view on the right.

User-added image

7. In the 3D representation, click one of the links (e.g. Upload Front) on the layout view.

8. Browse to and select the image file that you want to place on that surface. The file must be 8 or 24-bit PNG or JPG. A JPG file must be RGB or greyscale. Maximum image file size is 2.25MB.

9. Click Open. A progress indicator will notify you when the upload is complete.

NOTE: The image file must be square. If the aspect ratio is not appropriate, a message indicates the expected aspect ratio of 1:1. Do not use the same image on multiple sides as it can create false information upon detection.

13. Repeat steps 9 -11 for each of the other surfaces of the cube target. Use the breadcrumbs on the page to return to the list of targets for this database.

NOTE: You do not have to upload all six parts, however there must be at least two surfaces associated with images before you can download a device target database that includes this multi-target.

Add a Cylinder Target to a Database

1. Click Add Target. The Add New Target dialog opens

2. Type a unique name for the target in the Target Name field.

  • The name must be unique within this database.
  • The name should describe the image.
  • The name can be changed later.
  • The name can only include letters, numbers, and the underscore character _ .

3. Select Cylinder as the Target Type.

Multi Target Slide selection

4. Enter the Top Diameter, Side Length, and Bottom Diameter of the cylinder target in scene units.

  • Enter the dimensions of your target in the same unit as your augmentation. The size of the target shall be relative to the size of the augmented virtual content.
  • If you enter 0 for the top diameter or the bottom diameter, that will make the target a cone shape.

5. Click Add. The cylinder container is added to the target list.

6. In the target list, click the cylinder container you just added. A window opens with an empty 3-D representation of the cylinder on the left and a layout view on the right.

Multi Target Slide selection

7. In the 3D representation, click Upload Side on the layout view.

  • You must upload the side image before uploading the top or bottom image.

8. Browse to and select the image file that you want to place on that surface. The file must be 8 or 24-bit PNG or JPG. A JPG file must be RGB or greyscale. Maximum image file size is 2.25MB.

  • The image file must have the appropriate aspect ratio for the dimensions you provided. If the aspect ratio is not appropriate, a message indicates the expected aspect ratio.

9. Click Open. A progress indicator will notify you when the upload is complete.

10. Repeat steps 7-9 for Upload Top and Upload Bottom. Use the breadcrumbs on the page to return to the list of targets for this database.

 

  • You do not have to upload all three parts; however, associating the Side surface with an image is required before you can download a device target database that includes this cylinder.

How To Remove Targets from a Device Database

You can remove targets from a Device Database within the Target Manager using these steps. Steps:

1. Go to the Target Manager Home Page, you will see a list of Device Databases

2. Click the name of the database containing the targets that you want to remove.

3. Click the check box next to the targets that you want to remove in the target list, or check the box next to Target Name to remove all targets.

4. Click the Delete link from the menu above the targets

remove targets

You will be presented with a confirmation dialog. If accepted, the target(s) will be deleted and the target list will be updated to reflect the remaining targets.


How To View the Details of a Device Database and its Targets

You can view your databases and the targets in each database within the Target Manager.



All existing databases appear on the page with the following information:

  • Database name
  • Database type
  • The number of targets in the database
  • The data that the database was last modified

View a List of the Targets in a Database

1. Go to the Target Manager page.
2. Click the Device Databases name containing the targets you want to view.


Target List


For each Image Target the following information is displayed next to the target name.

  • The target type.
  • The augmentable Rating for any Image targets.
  • The target status of Active, Inactive or Processing.
  • The date that the target was last modified

View the details of a target

1. Click the Target's name in the target list.



For Image Targets, the target's properties will be listed to the right of the target image.

  • The target type.
  • The target ID
  • The augmentable rating for any Image targets
  • The date that the target was added
  • The date that the target was last modified

The Show Features link under Image Targets will show you the contrast based features of the image that are used to detect and track the target.


For Multi Targets and Cylinder Targets, which are composed of multiple target images, you can view the details of the individual images by clicking on them in the target's 3D viewer.


Each image has it's own details page where you can view the image features and also edit the image.

How To Edit the Properties of a Device Database

You can change and rename the images used for targets within the Target Manager and also rename your databases.

Rename a Database

1. Go to the Target Manager Home Page.
2. Click the name of the database that you want to edit in the database list, this will take you to the database's details page.
3. Click the Edit Name link at the top of the page, under the database name.


database details

4. Define a new name for the database in the Edit Name dialog and click Save.

edit dialog

Change the Target Source File of an Existing Target

Use this procedure to change the source file associated with an existing target in a Device Database. For Image Targets, the source file must be a supported image file format. See Image Targets for more information. For Object Targets, the source file must be an Object Data file (*.od ) produced by the Vuforia Object Scanner. Changing the source file will have no effect on any target already downloaded as a Device Database.

  1. Please start by following the steps in the View Details of a Target section above.
  2. When you are in the detail page of the target you wish to exchange, click the Update Target/Change and select your locally stored source file.  

NOTE: Multi Targets and Cylinder Targets require that you first select which of the images of the composition you wish to change.

How To Download Targets in a Device Database

Use this procedure to download in a Device Database. You can choose to download the database as a *.zip archive or a *.unitypackage. Select the archive type appropriate to the development tool you are using.

Tool Archive
Unity *.unitypackage
Android Studio *.zip
Xcode *.zip
Visual Studio 2015 *.zip

1. Go to the Vuforia Target Manager Home Page.

2. In the list of databases, find and click the name of the database that you want to download.

3. Click the Download Database button. Select the format (SDK or Unity) of the database that you want to download.

Download Database Dialog

4. Click Download. After a short processing time, this action creates a download of the all of the targets. Save this file on your computer.

NOTE: For SDK projects, you need to extract the XML and the DAT files of the device database from the ZIP archive. When using the Unity format, simply import the downloaded package to the StreamingAssets folder of your project.

How To Add a Device Database to a Vuforia Engine Project

Device Databases are the containers for Vuforia Image Targets, Multi Targets, Cylinder Targets and Object Targets. Add one or multiple databases to your Vuforia Engine project and associate the targets with an Observer. The following instructions will show you how to add a Device Database to your project. To learn how to load Device Databases at runtime, See How To Load and Activate Multiple Device Databases

Unity

Download your Device Database as a .unitypackage, you can then double click on the package or import it from the Unity Editor using Import -> Custom Package. The Unity package will automatically import the database files into the Streaming Assets folder of your project.

Native

Download your Device Database as a .zip archive. Unpack the zip file and copy the two target asset files (.dat and .xml) to the Assets directory of your project.

To test your own Vuforia targets, you can replace the Image Target file set used in the Vuforia Engine native sample project by copying your database files into the appropriate directory depending on the platform used (Android, iOS, UWP).

Get a list of targets in a device database and create a new Observer with its target info:

VuDatabaseTargetInfoError databaseTargetInfoError;
if (vuEngineGetDatabaseTargetInfo(mEngine, mdatabasePath, targetInfos, &databaseTargetInfoError) == VU_SUCCESS)
{
    vuDatabaseTargetInfoListGetSize(targetInfos, &numTargetInfos);
    if (numTargetInfos > 0)
    {
        VuDatabaseTargetInfo databaseTargetInfo;
        for (int32_t i = 0; i < numTargetInfos; i++)
        {
            REQUIRE_SUCCESS(vuDatabaseTargetInfoListGetElement(targetInfos, i, &databaseTargetInfo));

            // Create target info for observer creation

        }
        // Create and add new observer with target info
    }
}

Learn More

Target Manager

Vuforia Target Manager

Vuforia Features from Device Databases

Image Targets

Multi Targets

Cylinder Targets

Object Targets

Other Vuforia Databases

VuMark Databases

Device vs Cloud Databases

Cloud Databases