Using JSON Files to configure Attributes

This document describes the appropriate tags to be used when authoring JSON files to properly customize attributes templates.

Attributes templates provide a mechanism by which the various constructions in Habitat can be customized and built with user-specified characteristics, either at program start or on the fly.

Physics Manager Attributes

Physics Manager Attributes templates describe quantities pertinent to building the simulation world. Any source configuration JSON files used to build these attributes should be formatted as follows:

<worldname>.phys_scene_config.json

An example of an appropriately configured Physics Manager Attributes file can be found below:

{
    "physics simulator": "bullet",
    "timestep": 0.0041666666,
    "gravity": [0,-9.8,0],
    "friction coefficient": 0.4,
    "restitution coefficient": 0.1,
    "rigid object paths":[
        "objects/nested_box"
    ]
}

Below are the supported JSON tags for Physics Manager Attributes templates, and their meanings.

“physics simulator”
  • string
  • What physics engine should be used for dynamics simulation. Currently supports “bullet” for Bullet physics simulation, and “none”, meaning kinematic motion is to be used.
“gravity”
  • 3-vector
  • The default gravity to use for physical modeling. This can be overridden by Stage attributes.
“timestep”
  • double
  • The timestep to use for forward simulation.
“friction coefficient”
  • double
  • The default coefficient of friction. This can be overridden in Stage and Object Attributes.
“restitution coefficient”
  • double
  • The default coefficient of restitution. This can be overridden in Stage and Object Attributes.
“rigid object paths”
  • list of strings
  • A list of locations to query for supported object files that should be available to be loaded into the world.

Stage Attributes

A stage in Habitat-Sim is a static object consisting of static background scenery wherein an agent acts. Stage Attributes templates hold relevant information describing a stage’s render and collision assets and physical properties. Any source configuration files used to build these attributes should be formatted as follows:

<stagename>.stage_config.json

An example of an appropriately configured Stage Attributes file can be found below:

{
        "render mesh": "stage_floor1.glb",
        "up":[0,1,0],
        "front":[0,0,-1],
        "origin":[0,0,0],
        "scale":[2,2,2],
        "gravity":[0,-9.8,0],
        "margin":0.03,
        "friction coefficient": 0.3,
        "restitution coefficient": 0.3,
        "units to meters":1.0,
        "requires lighting":true
}

Stage Mesh Handles And Types

Below are the handles and descriptors for various mesh assets used by a stage.

“render mesh”
  • string
  • The name of the file describing the render mesh to be used by the stage.
“collision mesh”
  • string
  • The name of the file describing the collision mesh to be used by the stage.
“semantic mesh”
  • string
  • The name of the file describing the stage’s semantic mesh.
“house filename”
  • string
  • The name of the file containing semantic type maps and hierarchy.
“nav mesh”
  • string
  • The name of the file describing the NavMesh for this stage.

Stage Frame and Origin

The tags below are used to build a coordinate frame for the stage, and will override any default values set based on render mesh file name/extension. If either “up” or “front” are specified, both must be provided and they must be orthogonal.

“up”
  • 3-vector
  • Describes the up direction for the stage in the asset’s local space.
“front”
  • 3-vector
  • Describes the forward direction for the stage in the asset’s local space.
“origin”
  • 3-vector
  • Describes the origin of the stage in the world frame, for alignment purposes.

Object Attributes

Object Attributes templates hold descriptive information for instancing rigid objects into Habitat-Sim. These files should be formatted as follows:

<objectname>.phys_properties.json

An example of an appropriately configured Object Attributes file can be found below:

{
        "render mesh": "donut.glb",
        "collision mesh": "donut.glb",
        "up":[0.0,1.0,0.0],
        "front":[0.0,0.0,-1.0],
        "scale":[1.0,1.0,1.0],
        "margin":0.03,
        "friction coefficient": 0.5,
        "restitution coefficient": 0.2,
        "units to meters":1.0,
        "requires lighting": true,
        "mass": 0.038,
        "COM" : [0.0,0.0,0.0],
        "use bounding box for collision" : false,
        "join collision meshes" : true
}

Object Mesh Handles And Types

Below are the handles and descriptors for various mesh assets used by an object.

“render mesh”
  • string
  • The name of the file describing the render mesh to be used by the object.
“collision mesh”
  • string
  • The name of the file describing the collision mesh to be used by the object.

Object Frame and Origin

The tags below are used to build a coordinate frame for the object, and will override any default values set based on render mesh file name/extension. If either “up” or “front” are specified, both must be provided and they must be orthogonal. The object’s COM is used as its origin.

“up”
  • 3-vector
  • Describes the up direction for the object in the asset’s local space.
“front”
  • 3-vector
  • Describes the forward direction for the object in the asset’s local space.

Below are object-specific physical quantities. These values will override similarly-named values specified in a Physics Manager Attributes.

“scale”
  • 3-vector
  • The default scale to be used for the object.
“margin”
  • double
  • Distance margin for collision calculations.
“friction coefficient”
  • double
  • The coefficient of friction.
“restitution coefficient”
  • double
  • The coefficient of restitution.
“units to meters”
  • double
  • The conversion of given units to meters.
“requires lighting”
  • boolean
  • Whether the object should be rendered with lighting or flat shading.
“mass”
  • double
  • The mass of the object, for physics calculations.
“inertia”
  • 3-vector
  • The values of the diagonal of the inertia matrix for the object. If not provided, will be computed automatically from the object’s mass and bounding box.
“COM”
  • 3-vector
  • The center of mass for the object. If this is not specified in JSON, it will be derived from the object’s bounding box in Habitat-Sim.
“use bounding box for collision”
  • boolean
  • Whether or not to use the object’s bounding box as collision geometry. Note: dynamic simulation will be significantly faster and more stable if this is true.
“join collision meshes”
  • boolean
  • Whether or not sub-components of the object’s collision asset should be joined into a single unified collision object.