Lens

The Lens API allows developers to easily build applications for the LuminAR platform. Applications are websites that leverage the Lens API to access the augmented reality, networking, and data management functionality of the LuminAR platform.

Running Lens Apps

Running Lens apps requires 3 things: a backend, the Lens Webserver, and a specially-configured Chrome or Chromium browser. In addition, there are some optional services that provide additional functionality.

You'll need to have LuXoR compiled (see README.md in the LuXoR root directory) and you'll need the dependancies installed by scripts/install-requisites-ubuntu.sh.

Backend

To runs Lens apps, you first need a backend. This can be provided either by the LuXoR Bridge (which talks to the real Vision Server and Nearby Server), or by the dummy bridge, which reads messages from STDIN and sends them to Lens and prints messages from Lens to STDOUT.

To run the real LuXoR Bridge, cd to the LuXoR root and run bin/Bridge.

To run the dummy bridge, cd to the lens directory and run scripts/dummy-bridge.rb

Webserver

To run the webserver, cd to the LuXoR root and run scripts/runWebserver.sh.

Chrome

You need to have Chrome or Chromium installed. To run Chrome with the flags required by Lens, cd to the LuXoR root and run scripts/runBrowser.sh. This should open http://launcher.lens, which is the Lens Launcher.

Lens uses some experimental WebKit features, in particular, CSS variables. To enable these features, go to chrome://flags and select "Enable experimental WebKit features." Lens LAF will not work correctly without this option enabled.

Optional Services

VisionServer

To use any of the computer vision features of Lens (Touch, Lens.Snapshot, Lens.ContourSearch, Lens.Marker, Lens.Conversions, or Lens.Coordinate#transform), you will need to run VisionServer.

cd to the LuXoR root and run bin/VisionServer. For documentation on the command-line options, run bin/VisionServer -h.

Nearby

To use Lens.Machines, Lens.DB.published, and Lens.DB.shared, you will need the Nearby service running. Nearby automatically discovers nearby LuminAR on the same network using Zero-configuration Networking.

To run Nearby, cd to the LuXoR root and run scripts/runNearby.sh.

DBServer

To use any kind of Lens.DB other than Lens.DB.inMemory, you will need the DBServer. The DB Server handles saving your database persistently, sharing them across apps on the same device, and (in combination with Nearby), synchronizing them in real-time between multiple devices.

To run DBServer, cd to the LuXoR root and run scripts/runDBServer.sh.

Application Structure

There are only two required files in an application. Application may also include a templates directory.

app.json

First, applications must have an app.json file. It looks like this:

{
    "name": "Capabilities",
    "group": "Tests",
    "visible": true,
    "sizes": {
        "icon": {
            "frame": "icon.png",
            "width": 100,
            "height": 100
        },
        "small": {
            "frame": "index.html",
            "width": 300,
            "height": 300
        },
        "large": {
            "frame": "index.html",
            "width": 500,
            "height": 500
        },
        "full": {
            "frame": "index.html"
        }
    },
    "default_size": "small"
}

The app.json file is used by the launcher to list application. name is the human-readable name of your application. group is the name of the launcher group to place the application in. visible is a boolean that allows you to hide an application from the launcher. sizes is an object containing the available sizes for the application. Applications can have four sizes: icon, small, large, and full. Your application must at least support the icon size; the others are optional. Though, your application will not be able to do much without at least one other size. Each size has a frame attribute. frame is the path to an html file (relative to the root of your application) that will be loaded when the application is that size. The frame attribute for the icon size is the path to an image instead. The image must be square, and should be at least 100 pixels by 100 pixels. Sizes icon, small and large also have width and height attributes which are numbers, in pixels, describing how big to make the frame for that size. The full size is always fullscreen, so it doesn't need any width or height information. default_size is the size that your app most prefers to be in. The desktop will load your application in this size.

index.html

The index.html file is the front page of your application. Is is a standard HTML page that may do anything it wants. You will likely want to include the Lens API (available at http://lens2.lens/dist/latest/lens.js) as well as your own javascript. The Lens javascript will not leak any variables other than Lens into the global namespace. Here's an example:

<!doctype html>
<html>
    <head>
        <title>Capabilities</title>
        <script type="text/javascript"
                src="http://lens2.lens/dist/latest/lens.js">
                </script>
        <script type="text/javascript"
                src="app.js">
                </script>
        <link rel="stylesheet"
              type="text/css"
              href="styles.css" />
    </head>
    <body>
        <!-- ... -->
    </body>
</html>

templates/

The templates/ directory is optional. It may contain Handlebars templates in files ending in .html. These templates are automatically defined for you application to use; see Lens.Templates for details on the Lens templating system.

Using the API

First, you must include the API with a script tag:

<script type="text/javascript"
        src="http://lens2.lens/dist/latest/lens.js">
        </script>

Lens is loaded asynchronously. Before you use the Lens API, you should call Lens.init, passing in a callback function that will be called once Lens has been loaded:

Lens.init(function() {
    // your code here
});

By default, only the core API is loaded. If you'd like to use a Component, you must request it specifically:

Lens.init(['Components/draggable', function() {
    // your code here
});

Or require all of the Components:

Lens.init(['Components', function() {
    // your code here
});

Requiring LAF will load in the complete look-and-feel toolkit as well as all of the Components:

Lens.init(['LAF', function() {
    // your code here
});

The API

The API is exposed as a hierarchy of classes and namespaces under the global Lens variable. Note that Lens uses factory functions rather than constructors; there is no need to use the new keybord to create instances of classes in the Lens API. For example, you should use var marker = Lens.Marker() rather than var marker = new Lens.Marker().

In addition, most objects exposed as part of the API are frozen. This means that you won't be able to add or alter their properties. If a property is writeable, it will be explicity noted in the documentation. Trying to modify a frozen object will fail silently unless you're running in strict mode, in which case it will throw a TypeError. It is trongly recommended that you use strict mode for your Lens apps. Just have the first statement in your file or function be "use strict";. Read more about strict mode at MDN.

All API functions perform run-time type checking, which incurs a small performance hit. If you find that this performace hit is significant, you can disable the type checking with Lens.disableArgChecking. If you find the type checking too rigid, you can make it print a warning to the console instead of throwing an error with Lens.warnForArgChecking, or you can temporarily diable type checking with Lens.disableArgChecking and then re-enable it with Lens.enableArgChecking.

You may notice that some objects have properties and methods that start with _. These properties are not documented and are part of the internal API. Do not use these methods. They may changed or be removed at any time without warning. In addition, some classes in the API have no documented constructor. These classes have factory method (e.g. Lens.Snapshot.fromImageURL). Their constructors are part of the internal API and should not be used.

The Lens API is divided into 4 sections.

Core

These classes and namespaces expose the core capabilities of the LuminAR platform. They are accessible directly under the Lens namespace, e.g. Lens.Snapshot. In addition, the Core API includes the Touch system, which fires events directly on page elements. See Touch for details.

Data Structures

The data structures are not exposed directly to applications; you cannot instantiate them directory, but they are used to pass data to your application as the result of API calls or as events fired by the Touch module.

Components

The Lens Components are a set of reusable user interfaces widgets that provide for common interaction paradigms such as scrolling, dragging, and modal dialogs.

Look-and-Feel

The Look-and-Feel (LAF) toolkit is a set of CSS styles and javascript modules that transform standard HTML pages into LuminAR-friendly applications. It requires no special markup; it styles standard elements such as <button> and <input> elements. Unless you're adapting an existing webpage, it is strongly suggested you use the LAF toolkit.