How To Modify the Dataset Configuration XML File

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
  1. 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:
  1. See Schema for QCAR Dataset Configuration XML to view the entire Dataset Configuration XML schema and attribute definitions.
  2. 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 100, you must set the height to be 173/247*100=70.

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" encoding="UTF-8"?>
<QCARConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="qcar_config.xsd">
    <Tracking>
        <ImageTarget size="247 173" name="stones" />
        <ImageTarget size="247 173" name="chips" />
    </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

<ImageTarget size="247 173" name="wood">
  <VirtualButton name="red" sensitivity="HIGH" rectangle="-108.68 -53.52 -75.75 -65.87" enabled="true" />
  <VirtualButton name="blue" sensitivity="LOW" rectangle="-45.28 -53.52 -12.35 -65.87" enabled="true" />
  <VirtualButton name="yellow" sensitivity="MEDIUM" rectangle="14.82 -53.52 47.75 -65.87" enabled="true" />
  <VirtualButton name="green" rectangle="76.57 -53.52 109.50 -65.87" enabled="true" />
</ImageTarget>

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="150" 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
  1. The name of each part must be the name of an existing ImageTarget.
  2. 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.

<QCARConfig xsi:noNamespaceSchemaLocation="qcar_config.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Tracking>
        <ImageTarget name="FlakesBox.Front" size="90 120"/>
        <ImageTarget name="FlakesBox.Top" size="90 60"/>
        <ImageTarget name="FlakesBox.Bottom" size="90 60"/>
        <ImageTarget name="FlakesBox.Right" size="60 120"/>
        <ImageTarget name="FlakesBox.Left" size="60 120"/>
        <ImageTarget name="FlakesBox.Back" size="90 120"/>
      <MultiTarget name="FlakesBox">
       <Part name="FlakesBox.Front" translation="0 0 30" rotation="AD: 1 0 0 0"/>
       <Part name="FlakesBox.Back" translation="0 0 -30" rotation="AD: 0 1 0 180"/>
       <Part name="FlakesBox.Left" translation="-45 0 0" rotation="AD: 0 1 0 -90"/>
       <Part name="FlakesBox.Right" translation="45 0 0" rotation="AD: 0 1 0 90"/>
       <Part name="FlakesBox.Top" translation="0 60 0" rotation="AD: 1 0 0 -90"/>
       <Part name="FlakesBox.Bottom" translation="0 -60 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' atribute 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.

User-added image

Element ImageTarget
Attribute name
Type string
Range maxLength(size) = 64
Default Value -
Definition Reference to the Target.
Example Value target
   
Element CylinderTarget
Attribute name
Type string
Range maxLength(size) = 64
Default Value -
Definition Reference to the Target
Example Value target
   
Element CylinderTarget
Attribute sideLength
Type string
Range maxLength(size) = 255, furthermore 0<val(sideLength)
Default Value 0
Definition Numeric value of CylinderTarget side length in scene units.
Example Value 40.0
   
Element ImageTarget
Attribute size
Type string
Range maxLength(size) = 255, furthermore 0<val(size.x,size.y)
Default Value 0 0
Definition 2D vector description of ImageTarget size in scene units.
Example Value 40.0 30.0
   
Element VirtualButton
Attribute name
Type string
Range maxLength(size) = 64
Default Value -
Definition Name of VirtualButton, unique for a given ImageTarget.
Example Value red
   
Element VirtualButton
Attribute rectangle
Type string
Range maxLength(size) = 255, furthermore
-ImageTarget.size.x/2<val(top_left.x, bottom_right.x)< ImageTarget.size.x/2 and
-ImageTarget.size.y/2<val(top_left.y, bottom_right.y)< ImageTarget.size.y/2
Default Value 0 0 0 0
Definition Rectangle defining the size of the Virtual Button on the Image Target in scene units in (top_left.x, top_left.y, bottom_right.x, bottom_right.y) order.
Example Value -108.68 -53.52 -75.75 -65.87
   
Element VirtualButton
Attribute enabled
Type boolean
Range [true;false]
Default Value true
Definition Virtual Button enabled?
Example Value false
   
Element VirtualButton
Attribute sensitivity
Type string
Range [LOW, MEDIUM, HIGH]
Default Value MEDIUM
Definition Sensitivity to detect the status of a Virtual Button.
Example Value HIGH
   
Element MultiTarget
Attribute name
Type string
Range maxLength(size) = 64
Default Value -
Definition Name of MultiTarget, unique for a given device database.
Example Value multitarget
   
Element Part
Attribute name
Type string
Range maxLength(size) = 64
Default Value -
Definition Reference to the name of one ImageTarget within the same device database.
Example Value target
   
Element Part
Attribute translation
Type string
Range maxLength(size) = 255
Default Value 0 0 0
Definition Part origin is translated by this offset in scene units.
Example Value -100.0 0.0 50.0
   
Element Part
Attribute rotation
Type string
Range maxLength(size) = 255, furthermore must follow one of the formats:
AD: x y z r rotation of r degrees around [x,y,z] vector
AR: x y z r rotation of r radians aroun d [x,y,z] vector
x y z w quaternion rotation with [x,y,z,w]
Default Value AD: 0 0 0 0
Definition Rotational offset of the ImageTarget s local coordinate system with respect to the MultiTarget s coordinate system at the origin.
Example Value AD: 0 1 0 -90