The Artcodes app on the AppStore and Google Play allows you to scan Artcodes and create end-to-end augmented reality experiences. If you need more features or customisation you can add Artcodes to your app by using a library/dependancy or by downloading the code.

Licence

The Horizon Artcodes applications and libraries are publicly distributed under version 3 of the Affero General Public License. If you obtained this code under that license, then all its terms are applicable. The same applications and libraries are also available under alternative license terms negotiated with the Horizon Digital Economy Research Institute at the University of Nottingham. Contact horizon.NOSPAM@nottingham.ac.uk for more details.

Library/dependancy

Cordova

Cordova is a cross platform development tool that allows you to create mobile apps using HTML, CSS and JavaScript. The Artcodes Cordova plugin only supports iOS and Android. To install the plugin:

$ cordova plugin add https://github.com/horizon-institute/artcodes-cordova.git --variable IOS_CAMERA_DESC_STRING="We use the camera to scan Artcodes." --save

To use:

function yourFunction() {
	Artcodes.scan(
		{
			name: "Scan screen title", 
			actions: [
				{ codes: ["1:1:3:3:4"] }, 
				{ codes: ["1:1:2:4:4"] }
			] 
		}, 
		function (code) { alert(code); }
	);
}

// like most plugins, Artcodes.scan(...) can only be called sometime after the deviceready event e.g.
document.addEventListener('deviceready', function () {
	yourFunction();
}, false);

Android

Follow these steps to add Artcodes to your Android app. You can also see an example app on GitHub: https://github.com/horizon-institute/artcodes-android-integration-demo. Step 1: Add Artcodes to your build.gradle dependencies.

compile 'uk.ac.horizon.artcodes:artcodes-scanner:3.3.0'

Step 2: Create an Artcode experience object to pass to the Artcodes scanner.

import uk.ac.horizon.artcodes.model.Experience;
import uk.ac.horizon.artcodes.model.Action;

...

Experience experience = new Experience();
String[] codes = {"1:1:1:1:2", "1:1:2:4:4"};
for (String code : codes)
{
  Action action = new Action();
  action.getCodes().add(code);
  experience.getActions().add(action);
}

Step 3: Start the Artcodes scanner activity.

import android.content.Intent;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import uk.ac.horizon.artcodes.scanner.ScannerActivity;

...

private final int ARTCODE_REQUEST = 12345; // Range: 0-65535

...

Intent intent = new Intent(getApplicationContext(), ScannerActivity.class);

// Put experience in intent
Gson gson = new GsonBuilder().create();
intent.putExtra("experience", gson.toJson(experience));

startActivityForResult(intent, ARTCODE_REQUEST);

Step 4: Handle the response, implement onActivityResult:

protected void onActivityResult(int requestCode, int resultCode, Intent data)
{
  if (requestCode == ARTCODE_REQUEST)
  {
    if (resultCode == RESULT_OK)
    {
      // This is where you will receive a response from the
      // Artcode scanner if an Artcode was found
      // Do any logic based on the result here

      // This is the code of the Artcode that was found (e.g. "1:1:1:1:2")
      String code = data.getStringExtra("marker");
    }
  }
}

Note: To access the camera this library will add the “Hardware controls: take pictures and video” permission to your app.

Code on GitHub

The Artcodes app is open source and available on GitHub (version 3 of the Affero General Public License applies):

• Android: https://github.com/horizon-institute/artcodes-android
• iOS: https://github.com/horizon-institute/artcodes-ios

This guide show you how to use the Artcodes with the iPhone and Android apps.

Getting Started

1. If you haven’t already download and open the Artcodes app.
   The first time you open the Artcodes app you will see a brief tutorial screen (not shown) after you’ll see the “Recommended” screen. This lists recently used, nearby and popular experiences.
2. Select the “Artcodes” experience from the list. ▶︎
   This will show you the experience’s details.
3. Tap to go to the scanning screen. ▶︎
4. Centre the penguins (below) in the camera image. ▶︎
   You can also use the butterfly you drew in the how to draw an Artcode tutorial.
5. When the link at the bottom appears tap on it. ▶︎
6. Congratulations you scanned your first Artcode!

Experiences?

The Artcodes app uses “experiences”. These are mappings from codes to content. You can think of them as lenses, looking through one lens you might see one thing and looking through a second lens another thing. For example on the right the blue lens/experience links to the Artcodes website but the red lens/experience links the same Artcodes to Wikipedia. In the Artcodes app you can use public experiences & those shared with you as well as create & share your own.

Creating an Experience

1. From the start screen tap . ▶︎
2. Tap “Login” and login with your Google account. ▶︎
   If you have already done this your username will appear, tap on that instead.
3. This screen lists all the experiences you have created. Tap in the bottom right corner to create a new experience. ▶︎
4. Give your experience a name, you can also add a description and image. Tap the next button in the bottom right or swipe right to left. ▶︎
5. On this screen (with a big padlock) you would set availability but we’ll leave it private for now. Tap the next button in the bottom right or swipe right to left. ▶︎
6. On this screen (with a big warning triangle) we enter the details of the markers we want to create, tap to add one. ▶︎
7. Enter a name, website address and code (say 1:1:1:1:2) then tap . ▶︎
   The name appears as a link to the website you enter when the Artcode is scanned. You could enter the penguins above, they have have code 1:1:2:3:5.
8. You can repeat the last 2 steps to add more codes, then tap “SAVE”.
9. That’s it! Now let’s use our experience, tap and centre the Artcode(s) you setup in the camera image. ▶︎

Sharing an Experience

The app allows you to share experience you have created with specific people or with everyone using the app. To share your experience with specific people:

1. Go to your experience.
2. Tap “Share”.
3. You can share experiences by Facebook, e-mail, text message, etc.

To share your experience with everyone:

1. Go to your experience.
2. Tap “Edit”.
3. Tap “Availability” at the top.
4. Tap in the bottom right corner.
5. You can limit availability by date and suggest a location. If you don’t enter a date it will always be available. Tap when you’re done or to delete this date and/or location.
   Repeat the last 2 steps to add multiple locations or time ranges.
6. Tap “Save” when you’re done.

By adding a date or location your experience may be found by anyone using the Artcodes app:

• When users are around the location you set your experience will be suggested to them under “Nearby”.
• Your experience will also appear in search results.
• If you leave location set to “Anywhere” your experience will only appear in search results and not under “Nearby”.
• If your experience is used a lot it may appear under “Popular”.

Troubleshooting

Q: The experience I create just disappeared? A: It’s still there! Sometimes the list of experiences doesn’t update try closing and reopening the app. (iOS: double press the home button and swipe the Artcodes app off the screen then reopen the app, Android: go to the app switcher and swipe the Artcodes app off the screen then reopen the app) Q: My experience didn’t update when I edited it? A: Sometimes the update doesn’t appear but has been saved, try closing and reopening the app. (iOS: double press the home button and swipe the Artcodes app off the screen then reopen the app, Android: go to the app switcher and swipe the Artcodes app off the screen then reopen the app)

Artcodes are made up of a boundary, regions and blobs. They have a simple hierarchical structure: blobs are inside the regions, regions are inside the boundary. You can draw as much as you like outside of the boundary as long as it doesn’t touch the boundary. Continue reading →