How To Modify the Dataset Configuration XML File

This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.

Targets in a device target database are created by uploading images to the Target Manager. After the targets are in the Target Manager database, you can manage and enhance those targets outside of the Target Manager using the Dataset Configuration XML and the APIs in the SDK.

The XML file contains the database for the target images that are uploaded to the Target Manager. Once the XML files are in your workspace, you can make modifications to the XML file before packaging it with the application.

1. Use the Target Manager to download selected targets to a device database.
   The archive that you download will contain these two files:
   • <database_name>.dat
   • <database_name>.xml

2. You can then modify the XML configuration file to change the size and composition of the target.

These sections provide instructions on how to revise the XML configuration file for the various target types:

• How To Modify the Scene Unit Scale of a Target
• How To Add a Virtual Button to an Image Target
• How To Modify the Side Length of a Cylinder Target
• How To Modify a Multi-Target Using its Config XML File

3. See Schema for QCAR Dataset Configuration XML to view the entire Dataset Configuration XML schema and attribute definitions.
4. After the XML file is modified, save the file to the appropriate directory before packaging the application.

• Save the modified XML file in the assets directory (Android) or the media directory (iOS) to ensure that the changes are included in the APK file.

See:

How To Access and Modify Targets at Run Time

How To Modify the Scene Unit Scale of a Target

This article describes a target management tasks you can perform by modifying the XML file.

You can modify the scene size of an existing image target by updating the size attribute in the ImageTarget element of the <database_name>.xml file.

Note: It is important that the aspect ratio of the actual ImageTarget is not changed.

If you use the following example and if you change the width of the stones target to 10 cm, equaling 0.1 value, you must set the height to be 0.173/0.247*0.10=0.07.

Note: This action helps you avoid using the Target Manager to repeat the upload of the target and the download of the device database.

XML Example

<?xml version="1.0"?>
<QCARConfig xsi:noNamespaceSchemaLocation="qcar_config.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Tracking>
        <ImageTarget name="stones" size="0.247 0.173"/>
        <ImageTarget name="chips" size="0.247 0.173"/>
    </Tracking>
</QCARConfig>

How To Add a Virtual Button to an Image Target

To add a virtual button to an image target, add the VirtualButton element and its attributes to the ImageTarget element in the <database_name>.xml file.

XML Attributes:

• Name - a unique name for the button
• Rectangle - defined by the four corners of the rectangle in the target's coordinate space
• Enabled - a boolean indicating whether the button should be enabled by default
• Sensitivity - HIGH, MEDIUM, LOW sensitivity to occlusion

Example

<?xml version="1.0" encoding="UTF-8"?>
<QCARConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="qcar_config.xsd">
  <Tracking>
       <ImageTarget size="0.247 0.173" name="wood">
     <VirtualButton name="red" rectangle="-0.10868 -0.05352 -0.07575 -0.06587" enabled="true" />
       <VirtualButton name="blue" rectangle="-0.04528 -0.05352 -0.01235 -0.06587" enabled="true" />
       <VirtualButton name="yellow" rectangle="0.01482 -0.05352 0.04775 -0.06587" enabled="true" />
      <VirtualButton name="green" rectangle="0.07657 -0.05352 0.10950 -0.06587" enabled="true" />
     </ImageTarget>
  </Tracking>
</QCARConfig>

Note: if the sensitivity attribute is not defined, the button will default to MEDIUM sensitivity.

See:
How To Create and Destroy Virtual Buttons at Runtime

How To Modify the Side Length of a Cylinder Target

You can change the side length that you'd defined for a Cylinder Target in the Target Manager by modifying the config.xml file that is included with the *.dat file of the Device Database that it belongs to within the database archive that you obtain from the Target Manager.

1. Download a Device Database containing the Cylinder Target
2. Unzip the database archive - this is accomplished by importing the archive for Unity projects
3. You'll find the database's config.xml file in the folder that the archive has been unpacked to

To modify the side length of a cylinder target, update the sideLength attribute in the CylinderTarget element of the <database_name>.xml file.

Note that changing the side length results in a proportional change of the bottom and top diameters. This result is equivalent to a uniform scaling of the object in 3D space.

Example

<CylinderTarget sideLength="0.15" name="bottle"/>

How To Modify a Multi-Target Using its Config XML File

A Multi Target is made up of multiple image targets. These image targets are included in the multi-targets dataset and configured using the target's config file. You can create a multi-target without the aid of the Target Manager. However, the image targets to be assigned to the parts must have already been added to the device database through the Target Manager.

1. To create a multi-target in the <database_name>.xml file, you must add the MultiTarget element and a Part element for each surface. For each Part element, define the following attributes:
   • Name
   • Translation
   • Rotation attributes
2. The name of each part must be the name of an existing ImageTarget.
3. In addition, a developer can use APIs to do the following:
   • Remove a part
   • Change the spatial configuration

Example

In the following sample, the six image targets are assigned by name to one of six parts, and the location of each part is defined by the translation and rotation attributes. To understand what a multi-target looks like, see the sample application for Multi-Targets.

<?xml version="1.0"?>
<QCARConfig xsi:noNamespaceSchemaLocation="qcar_config.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Tracking>
        <ImageTarget name="FlakesBox.Front" size="0.090 0.120"/>
        <ImageTarget name="FlakesBox.Top" size="0.090 0.060"/>
        <ImageTarget name="FlakesBox.Bottom" size="0.090 0.060"/>
        <ImageTarget name="FlakesBox.Left" size="0.060 0.120"/>
        <ImageTarget name="FlakesBox.Right" size="0.060 0.120"/>
        <ImageTarget name="FlakesBox.Back" size="0.090 0.120"/>

        <MultiTarget name="FlakesBox">
            <Part name="FlakesBox.Front" translation="0 0 0.030" rotation="AD: 1 0 0 0"/>
            <Part name="FlakesBox.Back" translation="0 0 -0.030" rotation="AD: 0 1 0 180"/>
            <Part name="FlakesBox.Left" translation="-0.045 0 0" rotation="AD: 0 1 0 -90"/>
            <Part name="FlakesBox.Right" translation="0.045 0 0" rotation="AD: 0 1 0 90"/>
            <Part name="FlakesBox.Top" translation="0 0.060 0" rotation="AD: 1 0 0 -90"/>
            <Part name="FlakesBox.Bottom" translation="0 -0.060 0" rotation="AD: 1 0 0 90"/>
        </MultiTarget>
    </Tracking>
</QCARConfig>

• The 'translation' attribute translates the origin of an image target (part) by the defined scene units along the x, y, z axis.
• The 'rotation' attribute rotates the target around a given axis by a given angle. The 'AD' prefix stands for 'Axis - Angle Degrees'

Dataset Schema Specification

You can view the entire Dataset Configuration XML schema and attribute definitions. The schema for the Vuforia Dataset Configuration XML is defined in the following figure and table.