Aesel Workflow¶

Scene Registration¶

Whether we are building an Augmented Reality, Virtual Reality, traditional game console, or other application, our first step is to ask Aesel for information on scenes that are available. A scene is simply a logical grouping of objects which devices can move between, so they can correspond to different physical locations (in a typical AR application), different independent games (in a typical VR/PC/Console game)

This amounts to executing a Scene Query. We can look for scenes based on names, regions, and tags, or we can look for scenes within a specific distance of our latitude/longitude.

For example:

POST /v1/scene/query HTTP/1.1
Host: localhost:5885
Content-Type: application/json

{
  "scenes":[
    {
      "name":"test",
      "region":"US-MD",
      "latitude":124,
      "longitude":122,
      "assets":["TestAsset10"],
      "tags":["Testing2"]
    }
  ]
}

curl -i -X POST http://localhost:5885/v1/scene/query -H 'Content-Type: application/json' --data-raw '{"scenes": [{"name": "test", "tags": ["Testing2"], "region": "US-MD", "longitude": 122, "latitude": 124, "assets": ["TestAsset10"]}]}'

HTTP/1.1 200 OK
Location: http://localhost:5885/v1/scene/query
Content-Type: application/json

{
"num_records":1,
  "scenes":[
    {
    "key":"jklmnop",
    "name":"TestScene10",
    "region":"US-MD",
    "latitude":124.0,
    "longitude":122.0,
    "tags":["test","test2"],
    "asset_ids":["asset1","asset2"]
    }
  ]
}

Joining a game or walking into a new area is represented by a Scene Registration. Aesel responds to this message by informing you about all of the objects in the scene, as well as any other information you need to render the scene as a whole. We download all of the data we need to actually visualize the 3D objects from the server.

This exchange of information is initiated by a Scene Registration message:

POST /v1/scene/key/register HTTP/1.1
Host: localhost:5885
Content-Type: application/json

{
  "scenes":[
    {
      "key":"jklmnop",
      "devices":[
        {
          "key":"Ud132",
          "hostname": "localhost",
                            "port":4444,
                            "connection_string": "127.0.0.1:4444",
          "transform":{
            "translation":[0,0,0],
            "rotation":[0,0,0]
          }
        }
      ]
    }
  ]
}

curl -i -X POST http://localhost:5885/v1/scene/key/register -H 'Content-Type: application/json' --data-raw '{"scenes": [{"devices": [{"connection_string": "127.0.0.1:4444", "hostname": "localhost", "port": 4444, "key": "Ud132", "transform": {"translation": [0, 0, 0], "rotation": [0, 0, 0]}}], "key": "jklmnop"}]}'

HTTP/1.1 200 OK
Location: http://localhost:5885/v1/scene/key/register
Content-Type: application/json

{
    "msg_type": 4,
    "err_code": 100,
    "num_records": 2,
    "scenes": [
        {
            "key": "20dd78a2-9224-11e8-b492-d850e6db3ad1",
            "active": true,
            "distance": 0,
            "assets": [],
            "tags": [],
            "devices": [
                {
                    "key": "12345",
                    "transform": {
                        "translation": [
                            0,
                            0,
                            0
                        ],
                        "rotation": [
                            0,
                            0,
                            0
                        ]
                    }
                }
            ]
        },
        {
            "key": "123456",
            "active": true,
            "distance": 0,
            "assets": [],
            "tags": [],
            "devices": []
        }
    ]
}

After Registration, there may be a great deal of communication between the user’s device and the Aesel server. Rather than dumping all of the necessary information directly to the device, Aesel simply responds to a registration with the keys to find both it’s Assets and Objects. The client then responds with load messages for these records, so it loads each file on the server until the device has everything it needs. For a more detailed explanation of the process involved in loading a scene, please see the Loading a Scene page.

Scene Synchronization¶

In this stage, we need to correct our view with that of everyone else. This can be done any number of ways (from a real reference object to device-device communication), but once the right adjustments are made we send this information back to Aesel.

The message to Aesel takes the form of a Scene Synchronization Message:

POST /v1/scene/key/align HTTP/1.1
Host: localhost:5885
Content-Type: application/json

{
  "scenes":[
    {
      "key":"jklmnop",
      "devices":[
        {
          "key":"Ud132",
          "transform":{
            "translation":[0,0,0],
            "rotation":[0,0,0]
          }
        }
      ]
    }
  ]
}

curl -i -X POST http://localhost:5885/v1/scene/key/align -H 'Content-Type: application/json' --data-raw '{"scenes": [{"devices": [{"transform": {"translation": [0, 0, 0], "rotation": [0, 0, 0]}, "key": "Ud132"}], "key": "jklmnop"}]}'

We need to perform this step to determine the difference between the default coordinate system of your device, and the coordinate system of the Scene. This is the coordinate system that all of the objects are stored in, and that your device will need to use when referencing the scene. Think of it this way: If I tell you that there is a cube located at the point (1, 2, 3), how do you know where (0, 0, 0) is? If we don’t agree, then we’ll end up seeing the cube in different places.

Object Updates¶

Now, we can move around any of the virtual objects we downloaded right in front of us. When we do, that information is sent to Aesel and, from there, to everyone else in the scene.

Here we utilize the Object Streaming API to move the object around:

Aesel provides live change feeds of Object location, rotation, and scaling for any users registered to the Scene containing that Object. These feeds are designed to be extremely high-speed, and are sent via UDP.

Cross-Registration¶

When entering another, different physical location, we send another registration message to Aesel. And, just like before, we need to correct our view with that of everyone else.

This time, Aesel sees that you’ve corrected two different scenes that you’ve moved between, and it uses this information to calculate a general correction that can be used by anyone else going between these two scenes. This means that, if anyone else wants to change from one of these scenes to another, they will be provided with the correct transformation upon registration.

De-Registration¶

We finish by de-registering from the first scene, as we no longer need to recieve updates on the objects in that scene. This can be done after moving out of a physical area in an Augmented Reality application, or when leaving a game in a Virtual Reality or standard gaming application.

This message to Aesel comes as a De-Registration Message:

POST /v1/scene/jklmnop/deregister HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "scenes":[
    {
      "key":"jklmnop",
      "devices":[
        {
          "key":"Ud132"
        }
      ]
    }
  ]
}

curl -i -X POST http://localhost:8080/v1/scene/jklmnop/deregister -H 'Content-Type: application/json' --data-raw '{"scenes": [{"devices": [{"key": "Ud132"}], "key": "jklmnop"}]}'

Notice that we only de-register after performing any corrections needed, and once we are synchronized we can leave the original scene. Also note that we do not necessarily need to leave the original scene. We may also remain registered and continue receiving updates on all objects in both scenes.

Continue on to Loading an Aesel Scene to read about the process of loading an Aesel scene