Unity 3D Plugin >
Local Planar Marker

This tutorial will guide you through the creation of a simple AR application that detects and tracks an image marker stored in the app assets and draws a simple 3D model on it. Our SDK is designed to work with Unity3D 5+ and support both iOS and Android.

First launch Unity3D and create a new project.

Name your project (i.e. PikkartARTutorial) and choose the project directory then click the Create project Button.

Once the project is created in the Editor select File/Build Settings... or press (Ctrl + Shift + B).

  • Android
    In this window select Android and click Switch Platform.Then click on Player Settings... On the inspector set the Minimum API Level to 15 and set the Write Access to External.

  • iOS
    For iOS development, you have to select iOS and Switch Platform. Check that the options listed on the right are the same as the following screenshot:
    you have to change some settings in “Other Settings” section ( see the following screenshot):
    - deselect Auto Graphics API option and leave only OpenGLES2 or OpenGLES3.
    - Set scripting Backend to il2cpp
    - Target minimum iOS version to 8.0

    When targeting the latest iOS you also need to set the description text that appear to the user informing him that the app uses the device camera.

Once the correct platform has been created we can continue with the setup of the scene:

If you have already purchased a license, set the Bundle Identifier to the package name you provided when buying your Pikkart AR license, otherwise use "com.pikkart.trial".

You MUST download the license file from our site (even for the trial identifier) as described in the Cloud Manager guide and put it into the StreamingAssets folder of your Unity3D project (if the folder doesn't exist, create it inside the Asset folder of your Unity project).

The license comes in Android or iOS variants, use the correct one accordingly.

Now you have to import the PikkartAR package in your project. To do that select Assets/Import Package/Custom Package... and select the Unity sdk file from <pikkart_sdk_dir>/Unity/PikkartAR.unitypackage. When the list of components appears click Import. Do the same for the tutorial asset package.

Now we are ready to set up the AR scene. Select File/New Scene (Ctrl + N) and save it with File/Save Scene (Ctrl + S).

Delete the Main Camera, the Directional Light and all the objects in the scene Hierarchy. From the PikkartAR/Prefabs folder add the PikkartARCamera prefab to the scene (drag and drop it in the hierarchy).In the Inspector, under MainScript, change Recognition Storage to LOCAL and Recognition Mode to CONTINUOUS.

Local markers can be created and downloaded as .unitypackage files from the developer web app then you have to import the unitypackage inside unity. To add one marker to the scene select and add the prefab (PikkartAR/Prefabs/Marker) to the hierarchy. Now select the marker and in the inspector click the Import Markers button (this function is also available on the PikkartARCamera). This will search and load all the local markers available. You can now select a marker from the Marker Id dropdown placed below the import button. Select the 3_754 marker.

The system is now able to detect the marker, we just need to add some augmented content. To do this put the Monkey prefab from the Samples/Prefabs folder into the hierarchy as a children of the marker object. Save the scene (Ctrl + S).

To start the application follow the steps for your platform:

  • Editor
    You can test the sdk directly on the editor. By checking the Use Webcam On Editor option in the PikkartARCamera inspector you can enable your webcam and use it to test your marker setup. Just press the Play Button (Ctrl+P), wait for the webcam to load and place the marker in front of the camera.
    You can also check the marker scene setup without cameras. Just uncheck the Use Webcam On Editor option in the inspector and again press the Play Button. In the Scene View you can see all the markers with their augmented content shown in the same way they would do if they are seen by a device camera.
  • Android
    Select File/Build Settings... and click Add Open Scenes to add the current scene to the build. Connect an android device with developer options enabled and click Build And Run.
  • iOS
    • - click Build button in File->Build Settings...
    • - Move to the Xcode auto generate project directory,
    • - we will see a structure like this:

    • Unity 5.3.5
      Due to a Unity bug, it is necessary to change permissions on MapFileParser.sh
      Open directory in Terminal and execute following command:
      chmod 775 MapFileParser.sh
      Now, open Unity-iPhone.xcodeproj and build and run from Xcode IDE.

Remember to print a physical copy of the marker! The end result of our tutorial should look like this when tracking a marker:

ADDENDUM: The main script

The MainScript (Scripts/MainScripts), which is added to the PikkartARCamera, is the center of control for the AR engine. You can use this script to initialize and start the recognition process, change recognition options and handle a lot of events.
The Start function calls InitRecognition and StartRecognition. The StartRecognition() function requires as parameters a RecognitionOptions object and a reference to an object implementing a IRecognitionListener interface. The RecognitionOptions object can be created on-the-fly using a 3-parameters constructor requiring a RecognitionManager.RecognitionStorage option that indicates whether to use LOCAL recognition mode or GLOBAL (cloud recognition + local markers) mode. The second parameter, of type RecognitionManager.RecognitionMode indicates whether to use CONTINUOUS scan/recognition of image markers or TAP_ON_SCAN mode (the latter requires user input to launch a new marker search by calling StartRecognition). The last parameter is a CloudRecognitionInfo object holding the names of cloud databases in which to search markers, it's useful only when using GLOBAL as RecognitionMode and will be explained in the next tutorial. If you don't want to create a new RecognitionOptions object, the default one can be edited by selecting the desired options in the PikkartARCamera inspector.

Let's now take a look at the callback functions of this script:

  • This function is called every time a cloud image search is initiated. In this tutorial it will never be called as we are working LOCAL only. 
    @Override
public void executingCloudSearch() {
}
  • This function is called when the cloud image search fails to find a target image in the camera frame. In this tutorial it will never be called as we are working LOCAL only. 
    @Override
public void cloudMarkerNotFound() {
}
  • This function is called by our SDK to check if connection is available. 
    @Override
public boolean isConnectionAvailable(Context context) {
    return Application.internetReachability != NetworkReachability.NotReachable;
}
  • This function is called when the app is set to do cloud operations or image search (RecognitionManager.RecognitionStorage.GLOBAL) but internet connection is absent. 
    @Override
public void internetConnectionNeeded() {
}
  • This function is called every time a marker is found and tracking starts.

     

    @Override
public void markerFound(MarkerInfo marker) {
}
  • This function is called as soon as the current marker tracking is lost.

     

    @Override
public void markerTrackingLost(int i) {
}
  • This function is called every time a marker is not found (after searching through all local markers, or after a tap-to-scan failed).

     

    @Override
public void markerNotFound() {
}

ADDENDUM: The marker object

You can use or extend the MarkerObject script to handle local marker recognition events. It is included in the Marker prefab and allows to import and select marker ids from in the inspector.
When the marker is found OnMarkerFound() is called:

public virtual void OnMarkerFound(){
    EnableWithChildren(true);
}

 

protected void EnableWithChildren(bool setting) {
    for(int i=0; i<transform.childCount; i++)
        transform.GetChild(i).gameObject.SetActive(setting);
}


The above EnableWithChildren function enables all the marker children objects. You can place 3D, 2D and scripts objects as children. You can even add personalised functionalities to MarkerObject. In this case we recommend the creation of a new class that extends MarkerObject.
OnMarkerLost calls the same function, passing "false" as the setting parameter, to set all the children inactive. This same call is made during the initialization process so you don't have to manually disable all augmented content on your scene.