Object API

An Object is represented by a transformation matrix representing it’s position in 3-space, as well as a collection of Assets (Mesh files, Texture files, Shader scripts, etc.). Objects are meant to be interacted with by individual devices, and these changes will be streamed to either devices via the forthcoming UDP API. This API exposes CRUD and Query operations for Objects.

Objects may also have a frame/timestamp, as well as animation graph handles. Both of these are, however, optional.

Object Creation

POST /v1/scene/(scene_key)/object/

Create a new object with key obj_key in scene scene_key. The generated key of the object will be returned in the response.

Request Headers:
 
Status Codes:

http

POST /v1/scene/scene-key/object HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "msg_type": 0,
  "objects":[
    {
            "name": "Test Object 123464",
            "type": "Curve",
            "subtype": "Sphere",
            "owner": "",
            "frame": 0,
            "timestamp": 123456789,
            "translation": [0, 0, 1],
            "quaternion_rotation": [0, 1, 0, 0],
            "euler_rotation": [0, 0, 0],
            "scale": [1, 1, 2],
            "assets": ["Asset_5"],
            "translation_handle":[
                    {"left_type":"test","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0},
                    {"left_type":"","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0},
                    {"left_type":"","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0}],
            "rotation_handle":[
                    {"left_type":"test","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0},
                    {"left_type":"","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0},
                    {"left_type":"","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0},
                    {"left_type":"","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0}],
            "scale_handle":[
                    {"left_type":"test","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0},
                    {"left_type":"","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0},
                    {"left_type":"","left_x":0,"left_y":0,"right_type":"","right_x":0,"right_y":0}]
      }
  ]
}

curl

curl -i -X POST http://localhost:8080/v1/scene/scene-key/object -H 'Content-Type: application/json' --data-raw '{"msg_type": 0, "objects": [{"rotation_handle": [{"left_type": "test", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}, {"left_type": "", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}, {"left_type": "", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}, {"left_type": "", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}], "euler_rotation": [0, 0, 0], "scale": [1, 1, 2], "name": "Test Object 123464", "timestamp": 123456789, "frame": 0, "scale_handle": [{"left_type": "test", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}, {"left_type": "", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}, {"left_type": "", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}], "subtype": "Sphere", "translation_handle": [{"left_type": "test", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}, {"left_type": "", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}, {"left_type": "", "left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0, "right_type": ""}], "quaternion_rotation": [0, 1, 0, 0], "owner": "", "translation": [0, 0, 1], "type": "Curve", "assets": ["Asset_5"]}]}'

response

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

{
  "num_records":1,
  "objects":[{"key":"jklmnop"}]
}

Object Update

POST /v1/scene/(scene_key)/object/(object_key)

Update an existing object with name obj_name in scene scene_name.

Request Headers:
 
Status Codes:

http

POST /v1/scene/scene-key/object/key HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
"name": "Test Object 123464",
"type": "Curve",
"subtype": "Sphere",
"owner": "456",
"timestamp": 123456789,
"translation": [0, 0, 1],
"quaternion_rotation": [0, 1, 0, 0],
"euler_rotation": [0, 0, 0],
"scale": [1, 1, 2],
"assets": ["Asset_5"]
}

curl

curl -i -X POST http://localhost:8080/v1/scene/scene-key/object/key -H 'Content-Type: application/json' --data-raw '{"assets": ["Asset_5"], "euler_rotation": [0, 0, 0], "name": "Test Object 123464", "owner": "456", "quaternion_rotation": [0, 1, 0, 0], "scale": [1, 1, 2], "subtype": "Sphere", "timestamp": 123456789, "translation": [0, 0, 1], "type": "Curve"}'

response

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

{
  "num_records":0,
  "objects":[]
}

Object Retrieval

GET /v1/scene/(scene_key)/object/(object_key)

Get an object with key obj_key in scene scene_key.

Status Codes:

http

GET /v1/scene/scene-key/object/key HTTP/1.1
Host: localhost:8080

curl

curl -i http://localhost:8080/v1/scene/scene-key/object/key

response

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

{
  "num_records":1,
  "objects":[
    {
    "key":"5951dd759af59c00015b1409",
    "name":"123",
    "scene":"DEFGHIJ123463",
    "type":"Mesh",
    "subtype":"Cube",
    "owner":"456",
    "transform":[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
    "assets": ["Asset_5"]
    }
  ]
}

Object Deletion

DELETE /v1/scene/(scene_key)/object/(object_key)

Delete an object.

Status Codes:

http

DELETE /v1/scene/scene-key/object/key HTTP/1.1
Host: localhost:8080

curl

curl -i -X DELETE http://localhost:8080/v1/scene/scene-key/object/key

Object Query

POST /v1/scene/(scene_key)/object/query

Query for objects in scene scene_key.

http

POST /v1/scene/scene-key/object/query HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
"name": "Test Object 123464",
"type": "Curve",
"subtype": "Sphere",
"owner": "456",
"timestamp": 123456789,
"translation": [0, 0, 1],
"quaternion_rotation": [0, 1, 0, 0],
"euler_rotation": [0, 0, 0],
"scale": [1, 1, 2],
"assets": ["Asset_5"]
}

curl

curl -i -X POST http://localhost:8080/v1/scene/scene-key/object/query -H 'Content-Type: application/json' --data-raw '{"assets": ["Asset_5"], "euler_rotation": [0, 0, 0], "name": "Test Object 123464", "owner": "456", "quaternion_rotation": [0, 1, 0, 0], "scale": [1, 1, 2], "subtype": "Sphere", "timestamp": 123456789, "translation": [0, 0, 1], "type": "Curve"}'

response

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

{
  "num_records":1,
  "objects":[
    {
    "key":"5951dd759af59c00015b1409",
    "name":"123",
    "scene":"DEFGHIJ123463",
    "type":"Mesh",
    "subtype":"Cube",
    "owner":"456",
    "transform":[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
    "assets": ["Asset_5"]
    }
  ]
}

Object Lock

GET /v1/scene/(scene_key)/object/(object_key)/lock

A lock allows a single client to obtain ‘ownership’ of an object. This is an atomic operation, and is guaranteed to return a lock to one and only one client who requests it. Keep in mind, however, that no checks are performed within CLyman to verify that the object’s owner is the only one updating it, it is the responsibility of the client to obtain a lock prior to making updates.

Status Codes:
Query Parameters:
 
  • device (string) – Required. The ID of the Device requesting the lock.

… http:example:: curl

GET /v1/scene/scene-key/object/key/lock?device=123 HTTP/1.1 Host: localhost:8080

Object Unlock

DELETE /v1/scene/(scene_key)/object/(object_key)/lock

Unlocking allows a client to release ‘ownership’ of an object. This is an atomic operation, and no additional locks will be granted on a locked object until this method is called by the owner.

Status Codes:
Query Parameters:
 
  • device (string) – Required. The ID of the Device requesting the lock.

http

DELETE /v1/scene/scene-key/object/key/lock?owner=abc HTTP/1.1
Host: localhost:8080

curl

curl -i -X DELETE 'http://localhost:8080/v1/scene/scene-key/object/key/lock?owner=abc'