Specifying Physical Attributes of Tagged Objects



For each tag that you want your application to react to (whether for the purposes of object routing or just to interact with your application), you must create an object set XML file, and also include the tag values in the application registration XML file.

Object Set XML File

Within the object set XML file, you create one <Object> node for each tagged object that your application uses, and define the following values:

 

Key Description

BoundingBoxWidth

The width of the bounding box, in inches. (For more information, see the following "Bounding Box" section of this topic.)

BoundingBoxHeight

The height of the bounding box, in inches. (For more information, see the following "Bounding Box" section of this topic.)

PhysicalCenterOffsetFromTagX

The offset of the bounding box center from the tag center, in the x-direction. (For more information, see the following "Horizontal and Vertical Offsets" section of this topic.)

PhysicalCenterOffsetFromTagY

The offset of the bounding box center from the tag center, in the y-direction. (For more information, see the following "Horizontal and Vertical Offsets" section of this topic.)

OrientationOffsetFromTag

The offset of the bounding box orientation from the tag orientation, in degrees. (For more information, see the following "Orientation Offset" section of this topic.)

Text

The text to appear under the object.

ImportantImportant
The offset values are specified in screen coordinates, irrespective of the orientation of the application. The origin is the upper left corner of the screen.

The following illustration identifies the parts that define a tag in relation to the physical object it represents:

Tagged objects - Physical attributes labeled

The parts that define a tagged object in relation to the physical object it represents

  1. The offset of the bounding box center from the tag center, in the x-direction (PhysicalCenterOffsetFromTagX)

  2. The offset of the bounding box center from the tag center, in the y-direction (PhysicalCenterOffsetFromTagY)

  3. The center point of the bounding box

  4. The center point of the tag

  5. The offset of the bounding box orientation from the tag orientation, in degrees (OrientationOffsetFromTag)

The following code example shows a typical ApplicationNameObjectSet.xml file:

<?xml version="1.0" encoding="utf-8"?>
<ss:ObjectDescriptions
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ss="http://schemas.microsoft.com/Surface/2010/ObjectDescription">
    <Object ID="LoyaltyCard">
      <Layout
        BoundingBoxWidth="3"
        BoundingBoxHeight="2"
        PhysicalCenterOffsetFromTagX = "1.2" 
        PhysicalCenterOffsetFromTagY = "1.0" 
        OrientationOffsetFromTag = "3" 
        Text="Open Contoso Express" />
      <ObjectTagSet>
        <Schema>
          <Single Value="0x0" />
        </Schema>
        <Series>
          <Single Value="0x0" />
        </Series>
        <ExtendedValue>
          <Single Value="0x0" />
        </ExtendedValue>
        <Value>
          <Range Min="0xc1" Max="0xc3" />
        </Value>
      </ObjectTagSet>
    </Object>
</ss:ObjectDescriptions>

Name the file ApplicationNameObjectSet.xml, and copy it to the %ProgramData%\Microsoft\Surface\v2.0\ObjectSets folder on the device made for Microsoft Surface.

Localizing the Text that Appears in the Object Routing Menu

You can translate (localize) the text that appears under a tagged object by including a separate object set XML file for each locale that you support. The schema for the localized version of the object set XML file is a subset of the English version.

The following code example shows a French version of the previous ApplicationNameObjectSet.xml example code:

<?xml version="1.0" encoding="utf-8"?>
<ss:ObjectDescriptions
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ss="http://schemas.microsoft.com/Surface/2010/ObjectDescription">
    <Object ID="LoyaltyCard">
      <Layout Text="Ouvrez Contoso Express" />
    </Object>
</ss:ObjectDescriptions>

Make sure that localized versions of object set files have the same file name as the English version. Copy each localized object set file to a %ProgramData%\Microsoft\Surface\v2.0\ObjectSets\LanguageID folder, where LanguageID is one of the following:

 

LanguageID value Language

da-DK

Danish

de-DE

German

es-ES

Spanish

fr-FR

French

it-IT

Italian

ko-KR

Korean

nb-NO

Norwegian (Bokmål)

nl-NL

Dutch

sv-SE

Swedish

If you do not specify a localized version for a locale, or if you specify a language that Surface does not support, the default text is displayed.

If the Surface administrator changes the value of the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Surface\v2.0\Global\InternationalSupport\UILanguageName key, and your application includes a localized object set XML file for that language, the object routing menu will display your localized text.

For more information, see Deploying Localized Surface Applications, and see the topic "Preparing Microsoft Surface for Localized Applications" in the Surface Administration Guide.

Bounding Box

To determine the size of the object routing UI, the Surface software requires the size of the rectangle around the object, called the bounding box. The center point of the bounding box serves as the anchor for the tethers that connect the menu items to the tagged object in the object routing UI.

The bounding box is represented with values, in inches, for the BoundingBoxWidth and BoundingBoxHeight attribute values.

Horizontal and Vertical Offsets

You can place a tag anywhere on the relevant surface of a tagged object. It does not have to be centered within the bounding box. For the Surface screen to accurately reflect the position of the object, you must calculate the offset from the center of the tag to the center of the tagged object's bounding box.

Tagged objects - Offsets examples

Tag placement on a tagged object

Offsets are represented in inches from the center of the tag to the center of the x-axis or y-axis of the bounding box.

Orientation Offset

You can also place a tag in any orientation with respect to a tagged object. For the Surface screen to accurately reflect the position of the object, you must calculate the offset between the up orientation of the tag and the up orientation of the object's bounding box.

Orientation offsets are represented in degrees from the orientation of the tag.

Installation Considerations

Ideally, when you develop your application, you should also create an installer that installs the application, creates the correct entries in the ApplicationName.xml registration file and registers the tagged object in the %ProgramData%\Microsoft\Surface\v2.0\ObjectSets\ApplicationNameObjectSet.xml file.

Testing Applications

When you start your application from Microsoft Visual Studio or if you start it by running the executable file in Windows mode, the application is automatically registered with Surface Shell. However, applications that you open in this way cannot use object routing unless you have previously registered them with Surface Shell. For more information about how to register an application, see Registering Standard Applications.

Printing Tagged Objects

For information about how to create the physical tags, see Printing Tags.

Responding to Tags

To make your application respond to tags, include the tag values in the application registration XML file, and then use the tag-related APIs to test touch input for tags. For more information, see Tagged Object Recognition.

If you want a tag to start your application, object routing must be enabled on the device made for Surface by the administrator. For more information, see Starting an Application Using Tagged Objects.

Did you find this information useful? Please send us your suggestions and comments.

© Microsoft Corporation. All rights reserved.
Show: