lights#
The lights object defines the location, orientation, and behavior of unique lighting objects that you want to add to your scene.
Tip
In most circumstances you do not need to add lighting to your scene. Your scene is usually lit by the ambient lighting that makes up part of your selected background.
You should add unique lighting objects only if you really need unique lighting. Currently the only type of unique lighting that is available is a near-infrared spotlight. New types of lighting will be added in the future.
The lights object takes the form of a standard list, as follows:
"lights": [
]
If you do not want to add any unique lighting objects, simply leave the lights object out or leave it blank as above. To add unique lights to your scene, add one object to the list for each light.
The following lighting objects are available:
Near-infrared spotlight#
object
A near-infrared spotlight is a spotlight that you can freely place in your scene to cast near-infrared light on your actor.
Important
If you want your datapoint to be a near-infrared image, you must also make the following changes to your request:
Set your camera’s wavelength field to
nir, to make sure your camera is capable of capturing near-infrared light.Remove the background object, since the background and scene lighting no longer have any effect on the rendering of the scene.
You can place any number of near-infrared spotlights in your scene, by adding them one by one to the lights list as follows:
"lights": [ { "light_type": "nir", //Identifies this as a near-infrared spotlight object "beam_angle": //Defines the angle of the spotlight - how much space it covers "falloff": //Defines how quickly the light tapers off as it approaches the edges of the beam "brightness": //Defines the strength of the spotlight "location": { //Sets the location of the spotlight in x, y, and z coordinates }, "rotation": { //Sets the orientation of the spotlight using yaw, pitch, and roll controls } }, { //An additional complete near-infrared spotlight object }, ]
Sample usage
A sample complete near-infrared spotlight object
"lights": [ { "light_type": "nir", "beam_angle": 3, "falloff": 0.5, "brightness": 50, "location": { "x": 0.20, "y": -2, "z": 0.1 }, "rotation": { "yaw": 0.0, "pitch": 0.0, "roll": 0.0 } } ]
These values will generate a near-infrared spotlight that covers 3 degrees of arc, of strength 50 watts, of which 50% of the beam is at full strength. The spotlight will be located 20 centimeters to the left of the origin, 2 meters ahead of it, and 10 centimeters above it; and will be pointing in the +y direction.
light_type#
string
When the light_type field is set to nir, it identifies this object as a near-infrared spotlight.
Sample usage
A sample "light_type"="nir" field and its location in the data request
In the JSON hierarchy of the data request, the light_type field is found here:
{
"datapoints": [
{
"lights": [
{
"light_type": "nir",
}
]
}
]
}
beam_angle#
int
The beam_angle field defines how many degrees of arc are covered by the near-infrared spotlight. No matter what your other settings, the spotlight does not shed any light outside of this arc.
This field accepts integer values from 3 to 90.
Here are some sample images that show how beam angle affects the spotlight at a distance of 1.6 meters from the actor’s face:
Sample usage
A sample beam_angle field and its location in the data request
In the JSON hierarchy of the data request, the beam_angle field is found here:
{
"datapoints": [
{
"lights": [
{
"beam_angle": 17
}
]
}
]
}
This value will generate an infrared spotlight that covers 17 degrees of arc.
falloff#
64-bit float
The falloff field defines how far into the spotlight you have to go, starting from the edge and moving towards the center, before you reach the point where the beam is at full strength. This field accepts floating-point values from 0 to 1.
At falloff level 1, only the very center of the spotlight is at full strength, and the intensity tapers off very very gradually as you approach the edge of the beam.
At falloff level 0, the entire spotlight is at full strength, with a sharp cutoff between light and dark at the edge of the beam.
Some examples:
Sample usage
A sample falloff field and its location in the data request
In the JSON hierarchy of the data request, the falloff field is found here:
{
"datapoints": [
{
"lights": [
{
"falloff": .235
}
]
}
]
}
This value will generate a near-infrared spotlight that reaches full strength when it is approximately 23.5% of the way from the spotlight’s edge towards its center.
brightness#
64-bit float
The brightness field defines how much energy the near-infrared spotlight outputs in the form of light. This field accepts floating-point values from 0.0 to 1000.0 and is measured in watts.
Note
The wattage of this spotlight is not the same as the wattage listed on commercial lightbulbs. On a commercial lightbulb, the wattage value measures energy usage; here the wattage measures energy output.
Here are some examples of the brightness of the spotlight at a distance of 1.6 meters from the actor’s face:
|
|
|
|
|
|
Note
The brightness setting takes the current beam angle into account. You do not need to increase the brightness when you have a wider beam, or decrease it when you have a narrower one; the lit-up portion of the image will be of the same brightness no matter what the beam angle is.
Sample usage
A sample brightness field and its location in the data request
In the JSON hierarchy of the data request, the brightness field is found here:
{
"datapoints": [
{
"lights": [
{
"brightness": 1500
}
]
}
]
}
This value will generate a spotlight that is almost blindingly bright.
location#
object
The location object defines the position of the spotlight using global coordinates measured in meters. Each value is a floating-point variable that can range from -5 to 5 meters.
The location object contains the following fields:
"location": { "x": //The x coordinate, which moves the spotlight from side to side "y": //The y coordinate, which moves the spotlight from back to front "z": //The z coordinate, which moves the spotlight down and up },
Movement on the x axis
Movement on the y axis
Movement on the z axis
Sample usage
Location in the data request
In the JSON hierarchy of the data request, the location field is found here:
{
"datapoints": [
{
"lights": [
{
"location": {
},
}
]
}
]
}
A sample complete location object
"location": { "x": 0.0, "y": 2.8, "z": 0.12 },
These values create a spotlight located 2.8 meters behind the head. At that position, it will need to be rotated using the rotation controls so that it can illuminate the back of the head.
rotation#
object
The rotation object defines how the spotlight is oriented in the scene, using yaw, pitch, and roll controls.
The yaw, pitch, and roll fields are floating-point values measured in degrees, all of which can range from -180 to 180.
The rotation object contains the following fields:
"rotation": { "yaw": //Turns the spotlight from side to side. Positive values turn the spotlight to its left; negative values turn the spotlight to its right. "pitch": //Tilts the spotlight up and down. Positive values tilt the spotlight up; negative values tilt the spotlight down. "roll": //Tilts the spotlight from side to side. Positive values tilt the spotlight counterclockwise while negative values tilt the spotlight clockwise. },
Because the spotlight is rotationally symmetric and roll is applied last, the value you place in the “roll” field has no practical effect.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Important
Rotations of the spotlight are applied in a specific order: first yaw, then pitch, then roll. The spotlight is initially pointed in the +y direction before the rotations are applied.
Sample usage
Location in the data request
In the JSON hierarchy of the data request, the rotation object is found here:
{
"datapoints": [
{
"lights": [
{
"rotation": {
}
}
]
}
]
}