Your first Target Collections
Target Collections are central to working with Cloud Recognition service. They keep all your target images and are the base for the cloud archive.
Think of TargetCollection as a directory, where your images are stored. A TargetCollection forms a logical group, which is searched as a whole. Of course you can have several TargetCollections in your account, each consisting up to 50,000 images each.
What is the difference between Cloud Archive and Target Collection
Structure of a TargetCollection
|An ID that uniquely identifies the TargetCollection
|The Name of the TargetCollection, as defined by the user
Create a Target Collection
Creating a Target Collection is easy and can be done without any prerequisites in your account. In general it is your starting point and most likely your very first action.
Call the endpoint (using the domain of one of the regional servers)
with the mandatory
name field as a
POST request and you will create a new TargetCollection. The response will contain a TargetCollection object, where the ID is most important parameter. You can also add
metadata to a TargetCollection in case you want to some additional descriptive information. The next step is to add images to your TargetCollection, so they can be recognized.
Add Target Images
A Target is an plain image that can be recognized by the Wikitude Cloud Recognition service. Adding or creating a target means to provide a URL to your image to the server, which then downloads the image, analyzes it and adds it to the TargetCollection. To add an image call the endpoint
ID of the TargetCollection, where you want to add the image. You need to add the a field
imageUrl to your request. The image must be publicly accessible.
Pay attention to the optional fields
name is a unique identifier for your target within the TargetCollection. It is up to you to set and use this. The same is true for the
metadata object, which takes a full JSON object and can be filled with any value you like. The
metadata object will be present in the recognition response.
Structure of a Target
|An ID that uniquely identifies the Target
|The Name of the Target, as defined by the user
|The URL pointing to the original, uncompressed and uncropped Target binary file
|The URL pointing to a thumbnail representation of the Target
|The rating (from 0 to 3) of the Target
|The file size of the original Target binary image file, in bytes
|The physical (real world) height of the target, in millimeters
|Arbitrary JSON data that is stored together with the target.
Generate a Cloud Archive
Once you are done with adding targets you need to tell the server that it should generate your TargetCollection into a Cloud Archive. Call
again with the
ID of your TargetCollection and the process will be started. Since this call is asynchronous you will receive the response immediately with a path in the Location-property in the header of the response. By calling the url with the path, for example
with a GET-method request, you will see the status of the progress of the cloud archive generation in the response body as a JSON object. When the generation is completed, the cloud archive is available for recognition. Note that the generation process can take a while when generating a large TargetCollection for the first time. Small additions to existing cloud archives are processed a lot faster.
- your newly added image will not be recognized
- your deleted image will still be recognized
Your Cloud Archive is now ready on the server and can be used in combination with the Wikitude SDK from your app. See the SDK sample called Cloud Recognition for more details.
Generate a WTC file via API
You can create and download a wtc file of a Target Collection (Generate WTC) with up to 1000 targets by calling
with method POST. You have to specify the SDK version the wtc file should be built for in the request body. Valid values for the version are
5.3. Optionally, an email address can be added. The email is used for a notification once the generation of the wtc file has finished. Example for the request body:
Similar to the cloud archive generation this call is asynchronous, so the response header (
Location) contains a path useful for requesting the status of the wtc creation. Once the status is
COMPLETED the link to the actual wtc file can be requested from the TargetCollection. The received
TargetCollection object (in the body of the response) contains an additional property called
wtc, which is an array of wtc objects. Those objects consists of the following properties:
urlto the wtc file,
- the number of targets (
- the creation date (
The physical height and the metadata of an existing target can be updated.