Getting started >
Android SDK

Welcome to PIKKART AR SDK®. This document is designed to help you in your very first steps with our SDK  for developing your augmented reality project. Our SDK is designed for use with Android Studio (versions 2.1+), and support Android SDK level 15+ (21+ for the 64 bit version). Android NDK is not required.

  1. Create a new Android Application Project.

  2. Unzip the SDK zip you downloaded from Pikkart web site and copy the file Android/pikkart_ar_sdk.aar into the libs folder of your module (<project-root>/app/libs/)

  3. Open build.gradle from your module (usually found in <project-root>/app/), add  pikkart_ar_sdk.aar as a dependency and tell gradle to search the libs folder by modifying the gradle file as below:

    android 
    { 
        ... 
    } 
    dependencies { 
        compile fileTree(dir: 'libs', include: ['*.jar']) 
        compile (name: 'pikkart_ar_sdk', ext:'aar') 
        compile 'com.android.support:appcompat-v7:21.0.3' 
    } 
    repositories { 
        flatDir{ 
            dirs 'libs' 
        } 
    }
  4. If you have already purchased a license, please set the applicationId to the package name you provided when buying your Pikkart's AR license, otherwise you can use "com.pikkart.trial" and sign in to get the trial license.
    defaultConfig {
        applicationId "xxxx"
    }
    
  5. Copy the license file (license.spz) we provided to you (or the trial license) inside your app assets dir (<project-root>/app/src/main/assets/, create this dir if it doesn't exist).
  6. Add the following permission to your AndroidManifest.xml:
    <uses-permission android:name="android.permission.CAMERA" /> 
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> 
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> 
    <uses-feature android:name="android.hardware.camera" android:required="true" /> 
    <uses-feature android:glEsVersion="0x00020000" android:required="true" /> 
    <uses-sdk android:targetSdkVersion="21" android:minSdkVersion="15"/>
    
  7. If you plan to use Pikkart's Cloud Recognition Service also add the following permissions:
    <uses-permission android:name="android.permission.INTERNET" /> 
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> 
    
  8. For Android 6+ the permission mechanism is a little different, see our Tutorials for an example of the new mechanism in action or the Android documentation.
  9. The activity holding Pikkart's AR fragment ( com.pikkart.ar.recognition.RecognitionFragment ) must have set android:configChanges="screenSize|orientation" in the AndroidManifest.xml as in the following example:
    <activity android:name="com.yourcompany.yourapp.Your_AR_Activity" 
    android:configChanges="screenSize|orientation"/>
    
    Right now you probably want that line to look like this:
    <activity android:name=".MainActivity" android:configChanges="screenSize|orientation"/>
    
  10. Add Pikkart's AR Recognition Fragment to your AR activity. You can add it through your app layout XML file as:
    <?xml version="1.0" encoding="utf-8"?>
    <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
                 android:layout_height="match_parent" android:layout_width="match_parent"
                 android:id="@+id/rootLayout">
    <fragment android:layout_width="match_parent" android:layout_height="match_parent"
              android:id="@+id/pikkart_ar_fragment" android:name="com.pikkart.ar.recognition.RecognitionFragment" />
    </FrameLayout>
  11. All is set, now you just have to start the recognition process. You can do it (as an example) directly in you activity's onCreate function: 
    
    
    RecognitionFragment _cameraFragment = ((RecognitionFragment) getFragmentManager().findFragmentById(R.id.pikkart_ar_fragment));
    _cameraFragment.startRecognition(new RecognitionOptions(
                            RecognitionOptions.RecognitionStorage.LOCAL,  //use only local marker search
                            RecognitionOptions.RecognitionMode.CONTINUOUS_SCAN, //use continuous scan
                            new CloudRecognitionInfo(new String[]{})
                    ), this);
  12. In the previous example we are using LOCAL marker recognition only (RecognitionManager.RecognitionStorage.LOCAL), in this case you also need to add marker files to your app asset folder. Move to that folder (usually <project-root>/app/src/main/assets/), create a new directory "markers" and copy into it the local marker you want your app to recognize. You can create and download those files using our Marker Manager Web App or you can use the ones provided with the SDK Sample package ( you can find the marker files in <sample-root>/markers/).
  13. As second parameter to our _cameraFragment.startRecognition  function we have to pass a reference to a class implementing the interface IRecognitionListener  , in our example we are passing a reference to the AR activity itself (MainActivity in this example) which needs to implement IRecognitionListener and override the following callback functions:
    1. )
      
      @Override 
      public void executingCloudSearch() { 
      //TODO: add your code here 
      }
      Called every time Pikkart's AR sdk send a cloud recognition search query to our cloud recognition service.
    2. )
      
      @Override 
      public void cloudMarkerNotFound() { 
      //TODO: add your code here 
      }
      Called when a cloud recognition search query fails to find the captured image
    3. )
      
      @Override 
      public void internetConnectionNeeded() { 
      //TODO: add your code here 
      } 
      
      Inform that internet connection is not available (i.e. the app is set to use our cloud recognition service but the user has disabled internet connection).
    4. )
      
      @Override 
      public void markerFound(Marker marker) { 
      //TODO: add your code here 
      } 
      
      Called when a marker search (either local or cloud based) successfully find a marker.
    5. )
      
      @Override 
      public void markerNotFound() { 
      //TODO: add your code here 
      } 
      
      Called when a marker search fails to find a marker.
    6. )
      
      @Override 
      public void markerTrackingLost(String markerId){ 
      //TODO: add your code here 
      } 
      
      Called when the SDK lose tracking of the given marker.
    7. )
      
      @Override 
      public boolean isConnectionAvailable(Context context) { 
      //TODO: add your code here  
      }
      Inquire if a connection is available, to be implemented by the app developer. For a purely LOCAL search app you can simply return false here, otherwise use Android's NetworkInfo class.
    8. 
      )
      @Override 
      public void ARLogoFound(String markerId, int code) { 
      //TODO: add your code here  
      }
      Called when an ARLogo is found. Pikkart's ARLogo is a new technology that allows to embed binary codes inside an image. It lets app developers to unleash different AR experiences from visually similar marker images (i.e. images that looks the same but have different binary codes embedded in them).
       
  14. Now you can use the various static functions of the RecognitionFragment class to get the state, matrices and marker data of the detected and tracked marker
    
    public static boolean isTracking();
    
    public static Marker getCurrentMarker();
    
    public static float[] getCurrentProjectionMatrix();
    
    public static float[] getCurrentModelViewMatrix();
    
    public static void renderCamera(int viewportWidth, int viewportHeight, int angle);
    

The renderCamera functions is particularly important because it allows your app to render the current camera image. This function needs to be called inside your OpenGL rendering cycle, see our tutorials for additional details.