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 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. They can be included in a Vuforia Engine project, and built into your app, or loaded and activated at runtime. 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 unitypackage file will automatically import the database files into the Streaming Assets / QCAR folder of your project.

Android , iOS & UWP

Download your Device Database as a *.zip archive. Copy the two target asset files of the downloaded database file in the assets directory of your project.

example:

To replace the targets used in on of the Vuforia Engine native sample projects you will have to copy these files into the appropriate directory:

ANDROID & UWP:

<DEVELOPMENT_ROOT>\vuforia-sdk-android-xx-yy-zz\samples\[sample name]\assets

iOS:

<DEVELOPMENT_ROOT>/vuforia-sdk-ios-xx-yy-zz/samples/[sample name]/media

 

Android Projects

It is important that you do a clean build in Eclipse after you have modified the assets in the directory; otherwise the packager will not include the new assets in your app installer APK package. To rebuild your project and initiate the packaging process, select your project and then go to Project->Clean...->Clean selected project below.

This examples uses an ObjectTracker instance to create and load a dataset named myDataset1.xml that is placed in the assets/ folder.

Vuforia::DataSet* myDataset            = 0; 
myDataset = objectTracker->createDataSet();
if (myDataset == 0)
{
     LOG("Failed to create a new tracking data.");
      return 0;
}
if (!myDataset->load("myDataset1.xml", Vuforia::DataSet::STORAGE_APPRESOURCE))
{
     LOG("Failed to load data set.");
     return 0;
}

 

iOS XCode Projects

Datasets placed in the assets folder are packaged by the sample Xcode projects into the root of the app bundle. This example uses an ObjectTracker to create and load a dataset named myDataset1.xml which is present in the root of the bundle.

(Vuforia:DataSet *)loadDataSet:(NSString *)dataSetPath
{
    Vuforia::DataSet *theDataSet = nil;
         
    const char* msg;
    const char* msgNotInit = "Failed to load tracking data set because the
 ObjectTracker has not been initialized.";
    const char* msgFailedToCreate = "Failed to create a new tracking data.";
    const char* msgFailedToLoad = "Failed to load data set.";
     
    // Get the image tracker:
    Vuforia::TrackerManager& trackerManager = Vuforia::TrackerManager::getInstance();
    Vuforia::ObjectTracker* objectTracker =
 static_cast<Vuforia::ObjectTracker*>(trackerManager.getTracker(Vuforia::Tracker::OBJECT_TRACKER));
     
    if (objectTracker == NULL)
    {
        msg = msgNotInit;
        errorCode = QCAR_ERRCODE_INIT_TRACKER;
    }
    else
    {
        // Create the data sets:
        theDataSet = objectTracker->createDataSet();
        if (theDataSet == nil)
        {
            msg = msgFailedToCreate;
            errorCode = QCAR_ERRCODE_CREATE_DATASET;            
        }
        else
        {
            // Load the data set from the App Bundle
            // If the DataSet were in the Documents folder we'd use
 STORAGE_ABSOLUTE and the full path
            if (!theDataSet->load([dataSetPath
 cStringUsingEncoding:NSASCIIStringEncoding],
 Vuforia::DataSet::STORAGE_APPRESOURCE))
            {
                msg = msgFailedToLoad;
                errorCode = QCAR_ERRCODE_LOAD_DATASET;            
                objectTracker->destroyDataSet(theDataSet);
                theDataSet = nil;
            }
            else
            {
                NSLog(@"Successfully loaded data set.");
            }
        }
    }
     
 return theDataSet;

Can this page be better?
Share your feedback on our community forum