The structure of the data request#

In addition to generating data through our UI, we also support generating synthetic data based on a request that you submit in the form of a JSON file. The primary advantage of this feature is that it grants you precise, granular control over every detail of your datapoint.

The structure of the data request must conform to the schema that is outlined on this page.

Overview#

For an overview of the entire data request in one place, see The data request structure: an overview.

Important

Every object and field in the JSON structure is mandatory unless stated otherwise.

Top level: The datapoints array#

The top-level structure of the data request consists entirely of a list called “datapoints”:

{
  "datapoints": [
    {
      //Datapoint #1
    },
    {
      //Datapoint #2
    },
    {
      //Datapoint #3
    },
    {
      //Datapoint #4
    },
    //...and so on, up to as many datapoints as you need
  ]
}

Second level: The individual datapoint#

Each individual datapoint provides our system with detailed instructions for constructing a single 3D-generated scene containing a synthetic human face. You will select a specific face from among our thousands of available identities; define a hair style and color; set the position and orientation of the face; choose the lighting and background; and more.

The datapoint must contain the following objects:

{
  "human": {
    //Settings that will define the construction of the human in the scene
  }
  "accessories": {
    //Settings that will define the construction of any accessories being worn by the human in the scene, such as glasses
  }
  "camera": {
    //Settings that apply to the location, orientation, and parameters of the camera that will render the scene
  }
  "background" {
    //Settings that apply to the background and ambient lighting in a scene
  }
  "lights" {
    //Settings that apply to special lighting that can be added to a scene
  }
}

Third level: Defining parts of the scene#

Each third-level object in the data request defines a particular category: a major aspect of the datapoint that is being generated.

Every datapoint must contain one of each of the human and camera objects at this level.
If your datapoint is a visible spectrum image, the background object is also required; if your datapoint is an image in the near-infrared spectrum, the lights object is required instead.
The accessories object is optional.

The human object defines every building block that is used to construct the actor at the (metaphorical) center of your scene. It has the following structure:

 "human": {
   "id": //A UUID representing the actor in the scene.
   "head": {
     "eyes": {
       //Settings that define eye texture, closure, and direction of gaze
     }
     "hair": {
       //Settings that define hair style and color
     }
     "facial_hair": {
       //Settings that define facial hair style and color
     }
     "eyebrows": {
       //Settings that define eyebrow style and color
     }
     "expression": {
       //Expression type and intensity
     }
     "location": {
       //The position of the face in the scene using global coordinates
     }
     "rotation": {
       // The rotation of the head about the neck
     }
   }
 }

For details on these fields, see human.

The accessories object is optional. You need to include it in your datapoint only if you want the human subject in the scene to wear an accessory.

The structure of the accessories object differs depending on which accessory you are defining (a subject can wear only one accessory at a time).

Defining a glasses accessory

"accessories": {
  "glasses": {
    "id": //A UUID that defines the pair of glasses that the actor will wear
    "frame_color": //The color of the glasses frame
    "frame_metalness": //The metalness, or reflectivity, of the glasses frame
    "lens_color": //The base color of the lens before reflectivity and transparency are applied
    "lens_reflectivity": //The reflectivity of the lens
    "lens_transparency": //The transparency of the lens
    "position": //Where the actor is wearing the glasses
  },
}

For details on each of these fields, see Glasses.

Defining a mask accessory

"accessories": {
  "mask": {
    "id": //A UUID that defines the mask that the actor will wear
    "color": //The color of the mask
    "roughness": //The roughness of the mask, which determines how it reflects light
    "texture": //The texture of the mask
    "position": //Where the actor is wearing the mask
  }
}

For details on each of these fields, see Masks.

The camera object defines how the scene will be rendered. It divides camera properties into two groups: intrinsic parameters, which define the internal workings of the camera, such as the resolution, field of view, and lens type; and extrinsic parameters, which define the location and orientation of the camera in the world.

The camera object has the following structure:

 "camera": {
   "name": //A unique name you can give to identify the camera
   "intrinsic_params": {
     "projection": //The type of camera projection that will be used
     "resolution_width": //Resolution of the resulting image file, in pixels
     "resolution_height": //Resolution of the resulting image file, in pixels
     "fov_horizontal": //The camera's horizontal field of view, in degrees
     "fov_vertical": //The camera's vertical field of view, in degrees
     "wavelength_kind": //Whether the camera captures visible or near-infrared light
   },
   "extrinsic_params": {
     "location": {
       //x, y, and z coordinates of the camera in the global space
     },
     "rotation": {
       //Yaw, pitch, and roll to determine the direction of the camera
     }
   }
 },

For details on each of these fields, see camera.

The background object defines the HDRI background behind the actor in the scene, as well as lighting that is applied automatically to match it. It is mandatory for visual-spectrum datapoints, and should be left out otherwise. This object has the following structure:
```
"background": {
  "id": //A UUID that defines the specific background that will be used
  "transparent": //Whether or not the background is transparent
  "rotation": //How much the background should be rotated
}
```
For details on each of these fields, see background.

The lights object defines any special lighting you may want in the scene. Currently it is used for near-infrared lighting only. This object is therefore mandatory if you are rendering an image in the infrared spectrum, and forbidden otherwise. The lights object has a variable structure depending on the number and type of customized lights you are including in your scene. For details, see lights.