Designing a VuMark in Adobe Illustrator

You can use Adobe Illustrator to design your own VuMark and to export the corresponding SVG file which will be used to generate that VuMark in the Target Manager. This article will show you how to set-up Illustrator to use the VuMark Designer scripts, and will walk you through the steps needed to define your VuMark's elements and their corresponding layers.

Also be sure to read the VuMark Design Guide to understand the role and significance of a VuMark's design elements, See: VuMark Design Guide

There are three custom scripts for use with Illustrator that will help you create, verify and export your VuMark design.

• Setup script
This script creates a new Illustrator file for your VuMark, which we refer to as the VuMark template. It automatically creates the layers that you will place various parts of your VuMark design into.

• Verify script
This script helps you test your VuMark design by providing a list of design requirements, Pass/Fail results for each requirement and suggestions for resolving any issues that may have been found. You will typically run this script multiple times during the design process as you make changes to correct failed conditions.

• Export script
Once your design has been run through the Verify script and is determined to be ready for export , this script will export your VuMark template as a Scalable Vector Graphics (SVG) file. You will upload this SVG file into the Vuforia Developer Portal Target Manager to create the dataset that will be used within your iOS, Android, Unity, or Windows 10 application.

Installing and using the Illustrator Scripts

Download the VuMark Illustrator scripts from the Vuforia Developer Portal and copy it to the folder corresponding to your OS:

OS

Folder

OSX /Applications/Adobe Illustrator CC 2015 folder/Presets/en_US/Scripts
Windows C:\Program Files\Adobe\Adobe Illustrator CC\Presets\en_US\Scripts

Note: If you have Illustrator open, you must quit the application and re-open it to use the newly installed scripts.

You can now run the scripts from the Illustrator menu: File > Scripts > VuMark

Creating a VuMark in Illustrator

Using the Setup script

When you run the Setup script a dialog will appear that asks you to enter in a Name, Type and ID Length for your VuMark. The Type and ID Length fields are used to choose what type of data that you want to encode in your VuMark and this determines how many Elements that your VuMark template must have. Given these inputs, the script will configure your template accordingly.

VuMark Template Setup

VuMark Template Setup

Type

ID Length

String Use this if an ID will consist of printable ASCII characters.
If you choose String type, ID Length is the number of characters that your value will have.
Numeric Use this if an ID will only use numeric digits 0 - 9.
If you choose Numeric type, you have to enter the maximum numeric value that your VuMark will encode. For example, if you want a VuMark that supports numeric values from 0 to 20,000 you would enter 20,000 in the Maximum ID field.
Byte Use this for data in a byte format.
If you choose Byte type, the ID Length is the number of bytes that your value will have.

Template Layers

After running the Setup script you will have a new Illustrator file containing the layers meant to hold the various parts of a VuMark, as well as several additional layers that are also used in the design process. During the design process you may change order of the layers, but make sure other layers don t hide Border and ClearSpace graphics. Also ensure Bright and Dark Elements are always visible in your design and not covered by other graphics.

Vuforia Image

The VuMark native public sample shows an example of a detection highlight graphic displayed over the VuMark. The blue line is a path we added to the VuMark-UserData layer. Using this method you can build UI that is agnostic to the actual VuMark-shape.

IMPORT
It is not required that you use this layer, but we have found it helpful to have a work space where you can paste your VuMark design. From this layer, you can begin separating the various parts of your VuMark design by moving them to the corresponding layers.
VuMark-Description
INFORMATIONAL, LOCKED DO NOT ATTEMPT TO MODIFY THIS LAYER
This layer contains the details of your VuMark such as the Name, Type, Length and number of required Elements.
The Exporter script uses the information contained in this layer and that is why it is locked by default to prevent accidental deletion.
VuMark-Feedback
This layer is empty at first, but after you run the Verify script, it will be populated with feedback presented on top of your VuMark design to help you verify that it meets the design requirements.
VuMark-AsymmetryMarker CAN BE EMPTY
When creating a rotational symmetric Contour, this layer can be used to add Assymetry Markers that prevent from accidental wrong ID readout. See section TODO on more details.
VuMark-Contour
This layer shall only contain one closed path with 4-20 straight edges. Once you have placed your Border and Clear Space parts into their corresponding layers, you must use the Pen tool in Illustrator to draw a closed path along the invisible line that is formed where these two parts touch. This path must be placed in the VuMark-Contour layer.
VuMark-Origin
This layer contains a circle shaped object that represents a point that will be considered the origin on your VuMark design. Augmentations that will appear registered to the VuMark relative to this point. Move them in your design to match required origin. Circle can be scaled.
VuMark-Border
This layer should only contain the object representing your VuMark s Border.
VuMark-ClearSpace
This layer should only contain the object representing your VuMark s Clear Space.
VuMark-BrightElements
This layer will contain the Elements in their Bright state. The number of objects placed in this layer must match the number of required Elements exactly. Make sure Elements are actually brighter than Dark state.
VuMark-DarkElements
This layer will contain the Elements in their Dark state. The number of objects placed in this layer must match the number of required Elements exactly. Make sure Elements are actually darker than Bright state.
VuMark-Background CAN BE EMPTY
Contains background design. Use rich background if you intend to track VuMark in Vuforia.
VuMark-UserData
CAN BE EMPTY
This layer can contain graphical elements for various purposes, e.g. UI overlays, printing marks, metadata, etc. The graphic placed in this layer will be exported as part of the VuMark template SVG file and provided with VuMarkTemplate::getUserData() method inside the SDK when the VuMark is loaded.
  Detection highlight

Separating the parts of your VuMark

A common design workflow starts a conceptual phase where you experiment with various VuMark design concepts. Once you have chosen a design to move forward with, you can copy and paste it into the IMPORT layer of your newly created template. We have found it useful to place the design concept in the IMPORT layer and then start moving each part of the VuMark design into their corresponding layers in the Illustrator template.

Drawing the Contour

As described earlier, the Contour is normally not explicitly defined in your VuMark s design up to this point!

Now that you have placed the Border and Clear Space parts into their corresponding layers, you must use the Pen tool in Illustrator to draw a path along the length of the invisible line that is formed where these two parts touch. Make sure that this path is placed in the VuMark-Contour layer!

Labeled empire

NOTES:

  • The Contour path will not be visible in real instances of your VuMark.
  • The Clear Space in above example has been filled in pink to help show its boundaries it is normally filled in white in this design.

It is helpful to give the path a 1-2 point stroke in a highly visible highlight color like Magenta or Cyan so that you can easily see where the Contour has been defined.

Using the Verify script

After you have assembled the parts of your VuMark into their respective layers, you are ready to test your VuMark design.

The Verify script will first check that your VuMark conforms to the design requirements and then provides feedback in the form of a Pass, Fail, or Verify status message in an artboard adjacent to your main artboard in Illustrator.

After running the Setup script, you will have two artboards: your main design artboard, and a Feedback artboard adjacent to it.

The Feedback artboard provides a quick summary of the VuMark properties you have chosen, as well as a checklist of what will be verified by the script.

Before you have run the Verify script, the Design Guideline Verification section of the Feedback artboard will show a FAIL status for each item. It is useful to refer back to these status messages since they provide a reminder of the key design requirements your VuMark must adhere to.

Once you run the Verify script, the Feedback artboard will update to display the latest verification results.

What the script verifies

  • Number of Elements
  • Element sizes and locations
  • Element contrast
  • Contour segments
  • Border and Clear Space contrast
  • Border and Clear Space width
    (visual verification by user is required)

Feedback Artboard in Illustrator

Verification report

Understanding the Feedback layer overlays

Element sizes

The Verify script provide a Pass/Fail result for Element sizes. It draws on the VuMark Feedback layer magenta circles on top of every Element it finds. You should inspect the Elements in your design to make sure that they occupy or fill at least the same size and area as the circles. This visualization also helps to identify which Element cases the script to fail.

Border & Clear Space width

The Verify script doesn t automatically provide a Pass/Fail result for the Border and Clear Space widths but the feedback layer will display overlays that indicate the required Border and Clear Space sizes on each side of the Contour. In the examples below you can see how a magenta fill is overlaid on each side of the Contour to indicate the minimum width required for the Border and Clear Space.


FAIL
  • Border width is too small. Notice how the minimum Border width extends past the actual Border.
  • Clear Space width is too small. Notice how the minimum Clear Space width extends past the actual Clear Space.

PASS
  • Border is at least the same width as the minimum Border width indicated by the magenta overlay.
  • Clear Space is at least the same width as the minimum Clear Space width indicated by the magenta overlay.

Both the Border and Clear Space must be filled paths or compound paths.

ILLUSTRATOR TIP: If you ve designed your Border or Clear Space with a path that has a simple stroke width, you can use Illustrator s Object->Expand or Object->Expand Appearance to convert it to a compound path. Any Appearance Attributes that are assigned to your shapes, paths, or objects in your VuMark must be removed prior to exporting as an SVG.

ILLUSTRATOR TIP: You can use the Appearance Panel s menu option Reduce to Basic Appearance to remove the Appearance Attributes.

The VuMark-Border and VuMark-ClearSpace layers should only contain a single path or compound path each. The VuMark-Contour should contain only a single path that has exactly as many anchor-points as corners there are in your Contour. Make sure there is no overlapping anchors in your path. Use the Document Info > Object panel to list the anchor points by selecting the Contour path only.

Using the Export script

Export Script

When your VuMark design receives a Pass status for each of the items in the Design Guidelines Verification section and the message VuMark Template ready for export appears on the Feedback artboard, you can now run the Export script.

The Export script will again run verification, create a new file in Illustrator, and move contents from your VuMark template file gradually over. It will automatically trim your design artboard so that it is exactly the size of your VuMark design. It will then prompt you to save your VuMark template as an SVG file.

Troubleshooting

Occasionally you may find that the artboard trimming doesn t work correctly, and your artboard still appears larger than your VuMark design. Typically, the reason this happens is that there are one or more objects on your artboard that may be invisible to you, but are still there and the script interprets these as being part of your VuMark design. To fix this, you should inspect each of your layers looking for any objects that aren t part of your intended design and remove them. Sometimes there are invisible elements in Compound Paths or Sub-Layers preventing correct clipping. After cleanup you can run the Export script again and check that the artboard is trimmed correctly.

Target Generation in the Vuforia Developer Portal

In the Vuforia Developer Portal create a VuMark database. Since VuMark databases need to be associated to licenses, they cannot contain other target types. If you need to use different target types in your application download them as separate Device Databases and load them as simultaneous datasets.

Upload the VuMark SVG Template to create a VuMark target dataset on Add Target . The Device Database download process of the VuMark target is identical to other targets.

Additionally, you have the possibility to directly generate instances of the VuMark in the Vuforia Developer portal UI.

Advanced Topics

Rotational Symmetry Asymmetry Markers

We recommend to create designs that are not rotational symmetric, compare below:

Vuforia Image

Rotational symmetry examples

When contours are used that are rotational symmetric, there is a minimal, theoretical chance that a Code contained in a certain specific instance may not be read out correctly. If you want to assure that this never happens you will need to add Asymmetry Markers to your design.
Asymmetry Markers are little circles manually added to the VuMark-AsymmetryMarkers layer, named in order a0000 , a0001 , a0002 , . Their purpose is to markup one arbitrary, rotational symmetric location in your design with respect to the Contour rotation, that fulfills following criteria (see Figure 10 and Figure 11 for examples):

  • The number of Asymmetry Markers must be identical to the symmetry order of your Contour (see Figure 8 for examples).
  • When rotated around the symmetry center, individual Asymmetry Markers need to fall onto each-other. Basically they need to be on rotational symmetric locations (as shown in Figure 9).
  • One, and only one out of the multiple Asymmetry Markers must have in its center a different color than the other markers. The reason for that is that this specific marker is used to lock the orientation to a specific rotation. The contrast between the one and the other markers should be similar to what is used for Dark/Bright elements.

Asymmetry Marker Placement Example


Order 2 asymmetry marked up in ACME design


Order 4 asymmetry marked up in windmill design

Other Considerations

Physical Size

VuMark instances are generated in PNG, PDF, or SVG formats by Vuforia. Printing PDF documents will create the VuMark printouts in exactly the same size as you have designed them in Illustrator. When creating printout based on PNG or SVG files you should manage the print size correctly.

Detection Range

The detection range of a VuMark is limited by its apparent size in the mobile applications live camera viewfinder. The VuMark shall cover around 1/4-1/16 th of the live camera view in your application. This means, in a typical use scenario the user of your app shall be able to hold the mobile device camera pointing to a VuMark, so that the VuMark appears to cover 1/4-1/16 th of the screen.

The recommended smallest physical size of a VuMark shall be not smaller than a dime (~1 inch or 25mm). In case of a small VuMark when you move the device closer to the VuMark to fulfill above coverage requirement, at some point the camera will fail to focus.

Printing

VuMarks should be printed on paper and other media that ideally has a matte surface. Avoid glossy and reflective surfaces. The VuMark must be flat to be detected and tracked accurately.

Tips & Troubleshooting

Troubleshooting VuMark creation/detection fails

Due to the variety of ways how a VuMark design can be created there may be still cases when verification and export of the VuMark succeeds, but the VuMark generation upon upload to the Developer Portal fails, or even that a downloaded VuMark dataset is not capable of detecting instances (e.g. the 0 instance displayed in the VuMark Target detail panel.

Try to apply one of the recommended fixes based on the below listed possible reasons. We will work on improving the Illustrator toolchain over time to catch these issues and either provide feedback or automatically fix/bypass below mentioned cases:

  • Overlapping points in Contour path causing more points than actual corners in contour. When the Contour is not created carefully using the Pen-Tool as recommended, more points end up in contour path than your visual design actually has. Please verify using Document Info>Objects that you have as many points in the closed path as your design actually has when counting corners of contour visually.
  • Check maximum angle limit between contour segments is 150 .
  • Shape transformation in Contour/Border/Clear Space elements. Move/rotation/scale of an object results in an update to the anchor points of a path/compound path. Shapes however can store above changes either as update to their width/height and position coordinates OR in a separate transformation. If you find in your failed VuMark SVG Template file transform="matrix( attributes, use the Object>Shape>Expand Shape command to flatten them as paths.
  • Don t use appearance attributes for Elements/Contour/ClearSpace/Border! When listed objects have appearance attributes their export to SVG is not always properly rendered and verification may provide incorrect results. You can easily identify the issue, as appearance attributes are displayed with a filled dot in Layers panel:


Appearance attribute is used in VuMark-Border layer

To fix this issue select the object and use Object > Expand Appearance.

Calling Scripts with Keyboard-Shortcuts on MacOS

To save time during iterative checks using the VuMark Verify script, you might want to setup a keyboard shortcut to run the script. Shortcuts are OS platform-specific and techniques will vary. As a convenience, instructions for one way to do so on the Mac version of Illustrator are provided below:

  1. Launch Mac Automator
  2. Select Service and click the Choose button to accept
  3. Set the following values: Service receives no input in Adobe Illustrator
  4. Add a Get Specified Finder Items and click Add to select Vumark-Verify.jsx script located in the Presets/en_US/Scripts/ folder of Illustrator app
  5. Add an Open Finder Items and set it to the Illustrator app
  6. Save your new workflow service with name such as VuMark-Verify
  7. Open Keyboard in Settings and select Shortcuts tab
  8. With Services selected, scroll till you find VuMark-Verify and then click add shortcut and choose an available key combination.
  9. Restart Illustrator and check Services for your script with assigned hotkey.

User-added image