GLUE Quickstart: Animations and GLUE!

Scan this marker with junaio to see what you are getting in this tutorial.

What should you have done by now?

Hint on what to look for
animated metaio man
  1. You should have followed the GLUE Quickstart: Hello GLUE

What will you learn?

Scan the QR Code on the left with junaio to see what you are getting...

  • Creating GLUE 3D Models using the AREL XML Helper for php
  • Use the HTML overlay to command the user to hold the phone over the pattern
  • Start an animation based on Object Event ontouchstarted (click)
  • Start an animation based on the onanimationended event

Download

  • AREL XML Helper for php
  • Download the quickstarts or check out from github: GLUE_2_AnimationsAndGlue

Reference Images used

Get Started

  1. The Getting Started Package with AREL XML Helper you have just downloaded will help you provide correct information to junaio. This package will be uploaded to your server and the callback URL of your channel will have to point to the index.php in the html folder of the package.

    We want to achieve that the metaio man is glued onto the image, and whenever the user is not holding the phone over the according image, a HTML warning will come up telling him/her to do so.

    So again let’s see what happens if a user opens your channel (this means you receive a pois/search request to your server), it will be a little different than the previous example.

    When you have a look at the index.php you will first see that it is determined, whether this is a pois/search call to your server. If this is a valid request, a pois/search request, we define the WWW_ROOT and include the search.php where the POI will be defined.

    The WWW_ROOT will be used frequestly later, when we reference resources, such as images.

//if issues occur with htaccess, also the path variable can be used
//htaccess rewrite enabled:
//Callback URL: http://www.callbackURL.com
//
//htacces disabled:
//Callback URL: http://www.callbackURL.com/?path=

if(isset($_GET['path']))
	$path = $_GET['path'];
else
	$path = $_SERVER['REQUEST_URI'];
	
$aUrl = explode('/', $path);

//if the request if correct, return the information
if(in_array_substr('search', $aUrl))
{
	define('WWW_ROOT', "http://".$_SERVER['HTTP_HOST'].dirname($_SERVER['SCRIPT_NAME'])); //path to online location
	
	//the search return needs to be provided
	include '../src/search.php';
	exit;
}

  1. We will have a look at the search.php next, where the information to be returned to junaio is gathered. Currently, the search.php looks like this:

require_once '../library/arel_xmlhelper.class.php';
 
/**
 * When the channel is being viewed, a poi request will be sent
 * $_GET['l']...(optional) Position of the user when requesting poi search information
 * $_GET['o']...(optional) Orientation of the user when requesting poi search information
 * $_GET['p']...(optional) perimeter of the data requested in meters.
 * $_GET['uid']... Unique user identifier
 **/
 
//use the Arel Helper to start the output with arel

//start output
//ArelXMLHelper::start(NULL, AREL_HTML_LINK, TRACKING);

//Output your objects here!

//end the output
//ArelXMLHelper::end();
  1. You can see that there is not much but comments. But this provides the basic structure of your Channel using the AREL XML Helper - start it, end it and return objects inbetween ;)
    First, we need to include the helper class (require_once in line 1) of course.

    And then we start the output:
//create the xml start
ArelXMLHelper::start(NULL, AREL_HTML_LINK, TRACKING);
Structure of a junaio Channel
Glue Tracking confiuration creator
  1. This will generate the XML declaration and will tell junaio that the content will start. Note that there are two fields to be filled in by you:

    AREL_HTML_LINK: This is the link to the HTML file that shall be overlaid on your channel to define additional GUI elements for example. In this file, also the AREL JavaScript will be linked. Please have a look at "What are Channels" for more information on the channel structure. We will set the default arel/index.php here that is provided in the getting started package. So it will look like this.

    TRACKING: Here you can provide the tracking configuration. You can either set a variable for the tracking type or for GLUE channels, the tracking xml file. Here we set a tracking configuration file (tracking xml), which tells junaio which images to look out for to overlay your specific information onto. Tracking Configurations of your reference images can be created here (you need to be logged in as a developer).

    ATTENTION: Please read the information on pattern creation carefully, since inapplicable reference images are the most common issue for unsatisfactory results.
    It is adviced to use the metaio Creator for creating tracking configurations, since it analyzes and optimizes your reference images.


    So for this tutorial, it needs to look like that:
//create the xml start
ArelXMLHelper::start(NULL, WWW_ROOT . "/arel/index.php", "http://www.junaio.com/publisherDownload/tutorial/tracking_tutorial.zip");
  1. We will output 1 Model 3D Object - our metaio man. You will notice it holds the basic information, which model with which texture (have a look at 3D Models for more information on supported 3D Models). Also how it is scaled, positioned and rotated. Note that you will define, the type of rotation you are providing. Have a look at the ArelRotation class for more information.
    Last, the coordinateSystemID is provided. This will tell junaio to which image, marker or 3D Map this model shall be glued to. For 2D images, the coordinateSystemID is the same as the order of your Objects.

    If you use multiple Objects, make sure that each object has a unique ID, otherwise it will be overwritten.
//return the metaio man on coordinate system 1 / reference image 1
$oObject = ArelXMLHelper::createGLUEModel3D(
	"1",	//ID 
	"http://dev.junaio.com/publisherDownload/tutorial/metaioman.md2", //model Path 
	"http://dev.junaio.com/publisherDownload/tutorial/metaioman.png", //texture Path
	array(0,-100,0), //translation
	array(3,3,3), //scale
	new ArelRotation(ArelRotation::ROTATION_EULERDEG, array(-90,0,0)), //rotation
	1 //CoordinateSystemID
);

//output the object
ArelXMLHelper::outputObject($oObject);
  1. Next have a look at the arel/index.php, since this is the HTML page that will be slapped on top and where the "What to track" - information will be defined.
    You can see that on top, the AREL JS library is included as well as jQuery, since it is used quite often. You can have a look at the full documentation of AREL JavaScript.
    Underneath you will find the arel.sceneReady call. Of course this can also be in a seperate JS file and linked (as done in code when you download it). Whenever the scene is done loading, this call will be made. 
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width; initial-scale=1.0; maximum-scale=1.0;"> 
<script type="text/javascript" src="http://dev.junaio.com/arel/js/arel_beta_min.js"></script>
<script type="text/javascript" src="js/jquery-1.7.1.min.js"></script>
<script type="text/javascript">
   arel.sceneReady(function()
   {
      //start with arel here      
   });      
      
</script>
  1. Further down there is some default CSS and the beginning of the HTML page. We will adjust the CSS and the body to define our "What to track" information.
    Note that it is set to invisible (display: none), so it is not see from the start.
<!--add this in the header to extend the default CSS-->
<style type="text/css">
   * {
      -webkit-highlight:           none;
      -webkit-touch-callout :      none;
      -webkit-user-select:         none;
   }      

   body {
      margin: 0px;
      padding: 0;
      -webkit-text-size-adjust: 100%;
      background-color:transparent;
   }

   #center {
      position: absolute;
      top: 50%;
      left: 50%;
      width: 60%;
      height: 50%;
      margin-top: -25%; 
      margin-left: -30%;
   }

   #info {
      border-color: #aaa;
      border-style:solid;
      border-width:2px;
      -webkit-border-radius: 8px;
      
      display: block;
      position: absolute;
      height: auto;
      bottom: 0;
      top: 0;
      left: 0;
      right: 0;
      padding: 10px;

      color: #333;
      background-color: #fff;
      font: normal normal bold 16px/normal Helvetica, Arial, sans-serif;
      text-align: center;
      opacity: 0.8;
      display: none;
   }   
</style>
   

<!--THE BODY-->
<body>
   <div id="center">
      <div id="info">Please hold your device over the metaio pattern.<br /><br /><img src="images/metaioMan.png" /></div>
   </div>            
</body>
  1. Next we will define, when the "What to Track" Information shall be visible, and when it shall be hidden. For that we need to define an event listener in our arel.sceneReady which will be triggered, whenever something happens with our Scene.

    Then we will check for when the there is a change in tracking, and depending whether the state switches to arel.Tracking.STATE_TRACKING or arel.Tracking.STATE_NOTTRACKING we will fadein or fadeout the information using jQuery.

    In addition, upon the arel.sceneReady callback, we will get the tracking values. If they are empty, we will also show the "What to track" - information. The reason for this back up is, that the user might be holding the phone over the image while the channel is loading. So there would be no event triggered, because there is no change of tracking state. This way we avoid showing the "What to track" - information,if the user was impatient and was looking at the image already.
arel.sceneReady(function()
{
   //set a listener to tracking to get information about when the image is tracked
   arel.Events.setListener(arel.Scene, function(type, param){trackingHandler(type, param);});
   
   //if the user holds the device over the pattern already, when the scene starts
   arel.Scene.getTrackingValues(function(trackingValues){receiveTrackingStatus(trackingValues);});   
});

function trackingHandler(type, param)
{
   //check if there is tracking information available
   if(param[0] !== undefined)
   {
      //if the pattern is found, hide the information to hold your phone over the pattern
      if(type && type == arel.Events.Scene.ONTRACKING && param[0].getState() == arel.Tracking.STATE_TRACKING)
      {
         $('#info').fadeOut("fast");
      }
      //if the pattern is lost tracking, show the information to hold your phone over the pattern
      else if(type && type == arel.Events.Scene.ONTRACKING && param[0].getState() == arel.Tracking.STATE_NOTTRACKING)
      {
         $('#info').fadeIn("fast");
      }
   }
};

function receiveTrackingStatus(trackingValues)
{
   if(trackingValues[0] === undefined)
      $('#info').fadeIn("fast");
   
};
  1. Second to last step that is missing is to have our metaio man being animated. We will assign another event listener in the arel.sceneReady callback, this time attach it to the metaioman object.

    Once the metaio man is clicked (ONTOUCHSTARTED) the animation "close_down" will be started, once that is done (ONANIMATIONENDED) the "close_up" animation will be started.
arel.sceneReady(function()
{
   /* KEEP THE TRACKING HANDLING INFORMATION HERE */
   
   //get the metaio man model reference
   var metaioman = arel.Scene.getObject("1");
   
   //set a listener on the metaio man
   arel.Events.setListener(metaioman, function(obj, type, params){handleMetaioManEvents(obj, type, params);});
   
});

function handleMetaioManEvents(obj, type, param)
{
   //check if the object has been clicked
   if(type && type === arel.Events.Object.ONTOUCHSTARTED)
   {
      obj.startAnimation("close_down");
   }//or if the animation of the object ended
   else if(type && type === arel.Events.Object.ONANIMATIONENDED && param.animationname == "close_down")
   {
      obj.startAnimation("close_up");
   }
};
  1. The last step is to return to our search.php one more time and close the XML ouput by calling at the very end:
ArelXMLHelper::end();
Screenshot Create New Channel
  1. This completes the tutorial. You just need to upload all files and folders to your server and create a new channel with the Callback URL pointing to the folder your index.php and .htaccess is in on your server.  
    Note that the channel is defined as a GLUE Channel and uses AREL.
  2. After creating your channel, you are lead back to "My Channels". Press the validate button to get some first information on your channel’s correctness.
    If your channel passes all tests without errors (warnings are to be considered as hints for you. So they will most likely not affect the functionality of your channel, but you can double check whether this is intended), you can open your channel on your device and test it there.
    For opening it on the device, either login with your developer credentials and search for the channel or simply scan the QR Code (if the visibility is not private)
  3. If something does not work as expected, please have a look at JavaScript Debugging and in our Forum
© metaio Inc. 2013