Cloud Recognition

This example shows how to recognize images on a cloud server and then overlay it with augmentations utilizing the CloudTracker class.

For a better understanding, here are some terms that will be used in the following and other sections of this documentation related to vision-based augmented reality.

For both Cloud Recognition samples below we will use external rendering if you don't know what that means please go through the section on rendering before starting here.

The CloudTracker is able to run in two modes, we call them on-click and continuous. In On-Click mode a single recognition cycle will be executed, in continuous mode the recognition will be started in a variable interval.

Both view controller are located in Controller/CloudTracking.

Regional server endpoints

Before we get started please note that you have to choose which regional-distributed Wikitude server the SDK should contact.

The cloud recognition server region can be selected by calling -setCloudRecognitionServerRegion: which is a method of WTTrackerManager. As a parameter, pass a value of WTCloudRecognitionServerRegion to specify the regional server. Every cloud tracker that was created afterwards, will contact the specified server.

On-Click Cloud Tracking

The starting point for on-click recognition is WTOnClickCloudRecognition. In -viewDidLoad we create a new instance of WTWikitudeNativeSDK and initialize it with a valid license key. 

self.wikitudeSDK = [[WTWikitudeNativeSDK alloc] initWithRenderingMode:WTRenderingMode_External delegate:self];
[self.wikitudeSDK setLicenseKey:kWTLicenseKey];

Then in -viewDidAppear: the Wikitude Native SDK is started using the -start:completion: method. If the SDK could be started, a object of type WTCloudTracker is created using the WTTrackerManager factory method -createCloudTrackerWithToken:targetCollectionId:extendedTargets:andDelegate. The returned pointer needs to be retained in order to keep it alive, so assign it to a strong property.

[self.wikitudeSDK start:nil completion:^(BOOL isRunning, NSError * __nonnull error) {
    if ( !isRunning ) {
        NSLog(@"Wikitude SDK is not running. Reason: %@", [error localizedDescription]);
    }
    else
    {
        self.cloudTracker = [self.wikitudeSDK.trackerManager createCloudTrackerWithToken:@"b277eeadc6183ab57a83b07682b3ceba" targetCollectionId:@"54e4b9fe6134bb74351b2aa3" extendedTargets:nil andDelegate:self];
    }
}];

Creating a cloud tracker object will automatically load it in the background. To get notified when the cloud tracker finished loading, implement the WTCloudTrackerDelegate protocol. It provides two methods that are called once the cloud tracker finished loading or failed to load.

- (void)cloudTrackerFinishedLoading:(WTCloudTracker * __nonnull)cloudTracker
{
    NSLog(@"cloud tracker finished loading");
}

- (void)cloudTracker:(WTCloudTracker * __nonnull)cloudTracker failedToLoadWithError:(NSError *)error
{
    NSLog(@"Cloud tracker failed to load with error: %@", [error localizedDescription]);
}

To start a single recognition, call the cloud tracker -recognize:errorHandler: method. This method takes two block objects as parameter. The first on is called if a successful server connection could be established and the cloud tracker received a valid server response. The second one is called if any kind of error occurred during this communication. To call the -recognize:errorHandler: method, a UIButton is set up to call a specific method once it was touched.

- (IBAction)sendCloudRecognitionRequest:(id)sender
{
    if ( self.cloudTracker )
    {
        if (self.cloudTracker.isLoaded)
        {
            [self.cloudTracker recognize:^(WTCloudRecognitionResponse *response) {
                if ( response.recognized )
                {
                    NSLog(@"Recognized target '%@' which has a rating of '%ld'", [response.targetInformations objectForKey:WTCloudTrackerResponseKey_TargetName], (long)[[response.targetInformations objectForKey:WTCloudTrackerResponseKey_TargetRating] integerValue]);
                    NSLog(@"Associated (custom) metadata: %@", response.metadata);
                }
                else
                {
                    NSLog(@"No target image found in the analysed camera frame.\nKeep Calm \n\t&\nKeep Looking");
                }
            } errorHandler:^(NSError *error) {
                NSLog(@"Cloud recognition recognition failed. Reason: %@", [error localizedDescription]);
            }];
        }
        else
        {
            NSLog(@"Cloud tracker is not yet loaded. No request send.");
        }
    }
}

Please note that only a recognize call is made if the cloud tracker finished loading. In case the server communication was successful, the success handler is called with an object of type WTCloudRecognitionResponse that represents the server result. This object contains information if a image target was found or not, its name and, if specified, its associated meta data. In case of an error, a NSError object is passed to the errorHandler which contains detailed information about why the communication failed.

Since the WTCloudTrackerDelegate protocol also conforms to WTBaseTrackerDelegate, all tracking related methods to draw a augmentation around the recognized target are available as well.

Continuous Cloud Tracking

On-Click recognition is useful in some particular cases, but more often than not you probably want to use continuous recognition. For continuous cloud recognition we set an interval in which the CloudTracker automatically calls the recognize function.

To start continuous recognition, simply call the -startContinuousRecognitionWithInterval:successHandler:interruptionHandler:errorHandler: cloud tracker method once it finished loading.

if ( self.cloudTracker && self.cloudTracker.isLoaded )
    {
        [self.cloudTracker startContinuousRecognitionWithInterval:1.5 successHandler:^(WTCloudRecognitionResponse *response) {
        NSLog(@"received continuous response...");
        if ( response.recognized ) {
            dispatch_async(dispatch_get_main_queue(), ^{
                [self.cloudTracker stopContinuousRecognition];
                [self.continuousRecognitionButton setTitle:@"Start Continuous Recognition" forState:UIControlStateNormal];
            });
        }
    } interruptionHandler:nil errorHandler:^(NSError *error) {
    }];
    [self.continuousRecognitionButton setTitle:@"Stop Continuous Recognition" forState:UIControlStateNormal];
}
else
{
    NSLog(@"Cloud tracker is not ready yet.");
}

As before, this method is called once a UIButton was touched.

The first parameter defines in which interval new camera frames should be sent to the server for processing. The second parameter is again a success handler which contains information about a recognized target. The third parameter is a block that is invoked if the given interval is to short for the server to respond. The last parameter is again a error handle which is invoked in case of any error the occurred during the communication.

To stop a continuous recognition session, e.g. once a target was found, simply call the -stopContinuousRecognition method.