welcome to linkAR technical documentation

next previous

Quick Start

2.1.- Setting up the Development Environment

If you are new to Android developing the following steps will guide you through the very basics of getting started with Android Google mobile development.
If you already are an Android developer and have the development environment set up, skip to Create new project.

Read more in Android's developer site

2.1.1.- Become an Android Developer

Important !! Matcher applications can not run in the simulator,and must be deployed on Android devices.
You must install a suitable Android java Developmet environment (The most common is Eclipse) to run applications on Android devices.

All the relevant information on how to install and prepare development environment can be found at Android's: Installing the SDK

2.2.- Installing Matcher Framework and creating a Hello World

2.2.1.- Create new project (Eclipse)

Select from upper menu: (File → New → Android Project) to create a new android project. Another option (File → New → Other → Android Project)

2.2.2.- Fill project details

1.Set proper project name

2.Select Build target
The lowest target selected should be 2.3.3

3.Fill in the package name and Main activity name if necessary (The lowest target should be 2.3.3)

The best practice is to create package name that consists of 3 names divided by 2 dots (Example: com.coolproject.test). Package name is very important, it represents your application and act as a unique identifier.
Also the package name is used in the process of receiving an API_KEY for the Matcher lib, therefore it is crucial to make a good and valid package name.

2.3.- SDK Files

SDK lib files and a sample project can be downloaded from ImageMatching SDK

2.4.- Create and configure the project

2.4.1.- Copy Libs directory to the project

Download and extract the lib.zip folder

All the needed SDK files will be located in the libs folder.

The folders should maintain the same structure and integrity as they are provided:

* libs/
  * armeabi-v7a/
    * libEADMatching.so
    * libEADQ.so
    * libEADUtilities.so
    * libEADMatchingNeon.so
    * libEADInterface.so
  * EADMatching.jar

Copy the whole libs directory from SDK package provided - into your project

2.4.2.- Link Lib files to your project path

To link EADMatching.jar file to your project click right mouse button on project folder and select Properties

In the window select Java Build Path and Libraries .

In the Libraries section select Add JARs. In the opened window find your project and select the jar file from the libs directory

After successful Linking , the added .jar's should appear in the Libraries section.

2.4.3.- Add Images to Match

Create drawable folder under your Project:

Then, search the images you want to match (dolphins and underworld for the next steeps):

Search the pictures under de HelloARLib project.

  • Samples
    • HelloImageMatching
      • res
        • drawable
          • dolphins.jpeg
          • underworld.jpeg
          • horse.jpeg

Drag and drop the images into the drawable folder:

2.4.4.- Starting to Code and creating your first Matcher based Application

Add imports to the main activity class. ( The HelloARlibActivity.java of the sample project)

package com.arlab;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import android.app.Activity;
import android.app.ProgressDialog;
import android.content.Context;
import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
import android.graphics.Color;
import android.os.AsyncTask;
import android.os.Bundle;
import android.os.Environment;
import android.util.DisplayMetrics;
import android.util.Log;
import android.view.Gravity;
import android.view.View;
import android.view.ViewGroup.LayoutParams;
import android.widget.FrameLayout;
import android.widget.RelativeLayout;
import android.widget.TextView;
import android.widget.Toast;
import com.arlab.imagerecognition.ROI;
import com.arlab.callbacks.ARmatcherImageCallBack;
import com.arlab.callbacks.ARmatcherQRCallBack;
import com.arlab.imagerecognition.ARmatcher;
import com.arlab.R;
public class HelloMatcherlibActivity extends Activity implements ARmatcherImageCallBack, ARmatcherQRCallBack {

Those imports are needed in order to use Matcher lib classes.

2.4.5.- Add permissions and other changes to AndroidManifest.xml

For detailed explanation of AndroidManifest look here LINK

The folowing permissions must be added in AndroidManifest Extras area

  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />	
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.CAMERA" />
  <uses-feature android:name="android.hardware.camera" />
  <uses-permission android:name="android.permission.WAKE_LOCK"/>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

The folowing fields must be added to Main activity preferences


Final AndroidManifest should look like that:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionName="1.0" >
    <uses-sdk android:minSdkVersion="10" />
     <supports-screens android:resizeable="true"
		android:smallScreens="true" android:normalScreens="true"
		android:largeScreens="true" android:anyDensity="true" />
	<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
	<uses-permission android:name="android.permission.INTERNET" />
	<uses-permission android:name="android.permission.CAMERA" />
	<uses-feature android:name="android.hardware.camera" />
	<uses-permission android:name="android.permission.WAKE_LOCK"/>
	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
	<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
        android:label="@string/app_name" >
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />

2.4.6.- Create Default Matcher view instance

In order to start using The Matcher you need to create an instance of ARmatcher (ARmatcher.java) int the onCreate() method of your activity and add the view instance to content view.

public class HelloMatcherlibActivity extends Activity implements ARmatcherImageCallBack, ARmatcherQRCallBack {
  /** Called when the activity is first created. */
  /**The matcher instance */
  ARmatcher aRmatcher;
  int screenheight;
  int screenwidth;
  /**Array that holds added images id in the matching pool */
  private ArrayList<Integer> imageIdHolder = new ArrayList<Integer>();
  private static final String TAG = "HELLO";
  public void onCreate(Bundle savedInstanceState) {
    /**Get full screen size */
    DisplayMetrics displaymetrics = new DisplayMetrics();
    screenheight = displaymetrics.heightPixels;
    screenwidth = displaymetrics.widthPixels;            
    /**Create an instance of the ARmatcher object. */
    aRmatcher = new ARmatcher(this,"fVMgPgbiqOD9UZChyv7Y",
    /**Add camera view instance to content view */
    /**Set image and QR matching callbacks */
    /**Set the type of the matching. */
    /**Enable median filter ,which helps to reduce noise and mismatches in IMAGE matching .(Optional) */
    /**Set minimum image quality threshold, for image to be accepted in the image pool (0 - 10) */
  } // End onCreate()

You will receive a valid API_KEY for you own project by mail after downloading the SDK.
In order to start and stop the Matching process use the start() and stop() functions:

   protected void onResume() {
     /**Start matching*/
   protected void onStop() {			
     /**Stop matching*/

To clear images from the matching pool, the following function is used: (Must be launched before quitting the application).

  protected void onDestroy() {    	
    try {
      /**Empty image matching pool*/
    } catch (Exception e) {	 }

We have to implement the ARmatcherImageCallBack methods:

    public void onImageRecognitionResult(int res) {
      // TODO Later				

And implement the ARmatcherQRCallBack methods:

      public void onMultipleQRrecognitionResult(ArrayList<ROI> roiList) {
      // TODO Later				
    public void onSingleQRrecognitionResult(String res) {
      // TODO Auto-generated method stub
} // End HelloMatcherlibActivity

Full sample code located inside ARmatcher SDK downloaded

2.5.- How to Run

  • Connect android device by USB cable
  • Select the project folder from Package Explorer menu and press run button, for the first time will appear small window with different choices from which you should pick up “Android Application”.

  • Select your running device

2.6.- How to Debug

  • After running, make a breakpoint at the desired line to stop the debugger on runtime.
  • To make a breakpoint, click on the left margin of the line twice and a blue circle will appear indicating a new breakpoint was set.
  • Click on the debug (Bug button) to start debugging.

2.7.- How to upload the application to Google Play