Scene API

The scene API allows users to access Archilogic's scene structure and for instance convert it to A-Frame Elements.

Content:

Scene Id

Each scene has it's unique id which is generally refered to as sceneId.

You can get the sceneId of an Archilogic model for instance from the url:

https://spaces.archilogic.com/3d/!5dc58829-ecd3-4b33-bdaf-f798b7edecd4`
                                 |-------------scene-id---------------|
https://spaces.archilogic.com/3d/archilogic/zgkeizhc?modelResourceId=5dc58829-ecd3-4b33-bdaf-f798b7edecd4
                                                                    |-------------scene-id---------------|

Scene Structure

The scene structure is a JSON based scene format used in the Archilogic editor to describe scenes.

example of a simple scene structure snippet describing a furniture item:

{
  "type": "interior",
  "x": 3.4,
  "y": 0,
  "z": 1.4,
  "src": "!3aff54e2-fdff-44a3-9646-f2db1ea3bbfc"
}

Take a look at the Scene Structure Specifications

Get Structure

Use io3d.scene.getStructure(sceneId) to get the sceneStructure of an Archilogic model

io3d.scene.getStructure(sceneId)
.then(sceneStructure => { })

this returns an object with the following hierarchy:

{
  "type": "plan",
  "children": [
    {
      "type": "level",
      "children": [
         {
           "type": "interior"
         }
         // all elements are children of the level
      ]
    }
  ]
}

Get A-Frame Elements

io3d.scene.getAframeElements(sceneId) is a wrapper function for getStructure() and getAframeElementsFromSceneStructure()
The function returns an A-Frame DOM element with children nodes according to the hierarchy of the scene structure.

To add an Archiogic scene to your A-Frame scene you can do:

const sceneEl = document.querySelector('a-scene')
io3d.scene.getAframeElements(sceneId)
  .then(elements => {
    // this will give us two elements
    // The first is the actual scene according to the scene structure hierarchy
    // The second is the camera with potential waypoints that where defined in the scene structure
    // you can leverage the waypoints using our A-Frame tour component
    elements.forEach((el) => {
      // add elements to the scene
      sceneEl.appendChild(el)
    })
  })

Get A-Frame Elements From Scene Structure

io3d.scene.getAframeElementsFromSceneStructure(sceneStructure) converts scene structure into A-Frame DOM elements This is needed when working for instance with our Home Staging AI The sample converts a furniture item described in scene structure into an A-Frame entity using the io3d-furniture component

const element3d = {
  "type": "interior",
  "x": 3.4,
  "y": 0,
  "z": 1.4,
  "src": "!3aff54e2-fdff-44a3-9646-f2db1ea3bbfc"
}
const sceneEl = document.querySelector('a-scene')

io3d.scene.getAframeElementsFromSceneStructure(element3d)
  .then(result => {
    sceneEl.appendChild(result)
  })

result:

<a-scene>
    <a-entity io3d-furniture="id:3aff54e2-fdff-44a3-9646-f2db1ea3bbfc" position="3.4 0 1.4"></a-entity>
</a-scene>

Normalize scene structure

With io3d.scene.normalizeSceneStructure(sceneStructure) you make sure to always have a scene structure object that contains all the necessary information. This includes:

  • adding default values if not specified
  • adding a uuid to each element if not existant
const element3d = {
  "type": "interior",
  "x": 3.4,
  "z": 1.4,
  "src": "!3aff54e2-fdff-44a3-9646-f2db1ea3bbfc"
}
io3d.scene.normalizeSceneStructure(element3d)
  .then(result => {
    console.log(result)
  })
{
  "type": "interior",
  "x": 3.4,
  "y": 0,
  "z": 1.4,
  "ry": 0,
  "children": [],
  "id": "2140a713-2ac5-483a-a278-d45cfab1d68c",
  "src": "!3aff54e2-fdff-44a3-9646-f2db1ea3bbfc"
}

Validate scene structure

io3d.scene.validateSceneStructure(sceneStructure) allows you to validate a scene structure object.
This is useful when converting third party formats into scene structure or creating scene structure on the fly like in this Augmented Reality Demo

io3d.scene.validateSceneStructure({type:"foo"}).then(console.log)
{
    "isValid": false,
    "warnings": [],
    "errors": [{
        "message": "Parameter "type" of value "foo" is not supported",
        "item": {
            "type": "foo"
        },
        "code": 4
    }]
}

Error codes:

  OK: 0,
  MIN_VALUE: 1,
  MAX_VALUE: 2,
  MISSED: 3,
  NOT_SUPPOPRTED: 4,
  VALUE: 5,
  TYPE: 6,
  CHILDREN_TYPE: 7

Get viewer url

returns Archilogic Viewer Url from a scene Id

io3d.scene.getViewerUrl('5dc58829-ecd3-4b33-bdaf-f798b7edecd4')

returns

https://spaces.archilogic.com/3d/!5dc58829-ecd3-4b33-bdaf-f798b7edecd4

Export svg

converts sceneStructure into a 2D svg floor plan

io3d.config({
  // Replace this with your own publishable key for use on your own domain
  // More info: https://3d.io/docs/api/1/get-started-browser.html#using-publishable-api-keys
  publishableApiKey: 'YOUR_PUBLISHABLE_API_KEY'
})

// sceneId: reference to an Archilogic scene
// get your own via https://spaces.archilogic.com/order or https://spaces.archilogic.com/3d
const sceneId = '27fbe564-6cf4-48aa-8a19-6f0fb6cca7c4'

io3d.scene.exportSvg(sceneStructure)
.then(svg => {
  document.body.appendChild(svg)
})

returns

https://spaces.archilogic.com/3d/!5dc58829-ecd3-4b33-bdaf-f798b7edecd4