Try for free

api.assets

class datagen.api.assets.Accessories(*, glasses: Optional[Glasses] = None, mask: Optional[Mask] = None)

A 3D asset representing the accessory in the scene, if any. Only one accessory is supported at a time.

glasses: Optional[Glasses]

A 3D asset representing a pair of glasses.

mask: Optional[Mask]

A 3D asset representing a facemask.

class datagen.api.assets.Background(*, id: Optional[str] = None, transparent: bool = False, rotation: float = 0.0)

A 3D asset representing an HDRI background and its associated map of light sources.

Use datagen.api.catalog.backgrounds to get assets of this type from the asset catalog.

id: Optional[str]

A UUID that identifies a specific background asset.

rotation: float

The amount that the background should be rotated, clockwise, measured in degrees.

Min: 0

Max: 360

transparent: bool

Turns the background transparent. The choice of background is still relevant even if you make it transparent, because it defines all of the lighting in the scene.

class datagen.api.assets.Camera(*, name: str = 'camera_1', extrinsic_params: ExtrinsicParams = None, intrinsic_params: IntrinsicParams = None)

An object representing the camera in the scene. This object contains extrinsic and intrinsic parameters that define the camera’s internal workings and relationship to the world.

extrinsic_params: ExtrinsicParams

The set of intrinsic parameters that define a camera’s position and orientation relative to the rest of the 3D environment.

property extrinsics: ExtrinsicParams

An alias for the extrinsic_params property.

Returns:

The extrinsic_params property.

Return type:

extrinsic_params

intrinsic_params: IntrinsicParams

The set of intrinsic parameters that define a camera’s internal workings.

property intrinsics: IntrinsicParams

An alias for the intrinsic_params property.

Returns:

The intrinsic_params property.

Return type:

extrinsic_params

name: str

A custom name that you can give to the camera. When you access your datapoint, this name will appear as a subfolder that contains camera-dependent data (as opposed to global data).

class datagen.api.assets.DataRequest(*, datapoints: List[HumanDatapoint])

This class represents a list of datapoints.

Use the datagen.api.dump() function to convert this class into a .json request file. You can then upload that file to our platform.

datapoints: List[HumanDatapoint]

The list of datapoints in this data request.

class datagen.api.assets.Expression(*, name: ExpressionName = ExpressionName.NEUTRAL, intensity: ConstrainedFloatValue = 1.0)

Defines the expression on the face of an actor in the scene.

intensity: float

The strength of the expression.

Min: 0 - this value is indistinguishable from the neutral expression.

Max: 1

name: ExpressionName

The type of expression to depict on the face.

class datagen.api.assets.ExpressionName(value)

The available facial expressions, for use in Expression.name.

Any expression looks exactly like ExpressionName.NEUTRAL if given an Expression.intensity of 0.

ANGER = 'anger'

CONTEMPT = 'contempt'

DISGUST = 'disgust'

FEAR = 'fear'

HAPPINESS = 'happiness'

MOUTH_OPEN = 'mouth_open'

NEUTRAL = 'none'

The neutral expression is not affected by Expression.intensity.

SADNESS = 'sadness'

SURPRISE = 'surprise'

class datagen.api.assets.ExtrinsicParams(*, location: Point = None, rotation: Rotation = None)

The set of extrinsic parameters that define a camera’s position and orientation relative to the rest of the 3D environment.

For use with the Camera object.

location: Point

The location of the camera in the 3D environment, in global coordinates measured in meters.

rotation: Rotation

The orientation of the camera in the 3D environment, in Euler angles measured in degrees.

In the default orientation (yaw 0, pitch 0, roll 0), the camera is pointing in the +y direction.

Rotations are then applied in the order of yaw, pitch, then roll.

class datagen.api.assets.Eyes(*, id: str, target_of_gaze: Gaze = None, eyelid_closure: ConstrainedFloatValue = 0.0)

A 3D eyes asset and all related parameters, including eye textures, direction of gaze, and eyelid closure.

eyelid_closure: float

How much the actor’s eyes are closed.

Min: 0, the actor’s eyes are fully open.

Max: 1, the actor’s eyes are fully closed.

id: str

A UUID that identifies a specific eyes asset.

target_of_gaze: Gaze

The target of the actor’s gaze. In the output image, each eye will be rotated so that it faces this target point.

class datagen.api.assets.FrameColor(value)

The available base colors for glasses frames, for use in Glasses.frame_color.

BLACK = 'black'

BLUE = 'blue'

GOLD = 'gold'

GRAY = 'gray'

GREEN = 'green'

RED = 'red'

SILVER = 'silver'

WHITE = 'white'

class datagen.api.assets.Gaze(*, distance: ConstrainedFloatValue = 15.0, direction: Vector = None)

Defines a target point for an actor’s eye gaze, by uses distance and direction from a starting point.

The starting point is the midpoint between the center of the actor’s two pupils.

direction: Vector

A vector that defines the direction between the starting point to the target point.

The x, y, and z components of this vector are in the head space, with -y being straight ahead.

distance: float

The linear distance between the starting point (the midpoint between the center of the actor’s two pupils) and the target point.

class datagen.api.assets.Glasses(*, id: str, frame_color: FrameColor = FrameColor.BLACK, frame_metalness: ConstrainedFloatValue = 0.0, lens_color: LensColor = LensColor.BLACK, lens_reflectivity: ConstrainedFloatValue = 0.0, lens_transparency: ConstrainedFloatValue = 0.0, position: GlassesPosition = GlassesPosition.ON_NOSE)

A 3D asset representing a pair of glasses.

Use datagen.api.catalog.glasses to get assets of this type from the asset catalog.

frame_color: FrameColor

The base color of the glasses frames, which is further influenced by the frame_metalness property.

frame_metalness: float

A measure of the reflectivity of the glasses frames. Higher values are appropriate for metallic frames; lower values are appropriate for plastic ones.

Min: 0

Max: 1

id: str

A UUID that identifies a specific glasses asset.

lens_color: LensColor

The base color of the lenses, which is further influenced by the lens_reflectivity and lens_transparency properties.

lens_reflectivity: float

A measure of how much light is reflected off of the glasses lenses. Interacts closely with lens_transparency.

Min: 0

Max: 1

lens_transparency: float

A measure of how much light passes through the lenses. Interacts closely with lens_reflectivity.

Min: 0

Max: 1

position: GlassesPosition

The position of the glasses on the person wearing them.

class datagen.api.assets.GlassesPosition(value)

The positions where a glasses accessory can be worn, for use in Glasses.position.

ON_NOSE = 'on_nose'

class datagen.api.assets.Hair(*, id: str, color_settings: HairColor = None)

A 3D asset representing head hair, eyebrows, or facial hair, including color controls.

color_settings: HairColor

The set of controls that determine the color of hair.

id: str

A UUID that identifies a specific hair, eyebrows, or facial hair asset.

class datagen.api.assets.HairColor(*, melanin: ConstrainedFloatValue = 0.2, redness: ConstrainedFloatValue = 0.2, whiteness: ConstrainedFloatValue = 0.25, roughness: ConstrainedFloatValue = 0.15, index_of_refraction: ConstrainedFloatValue = 1.4)

The set of controls that determine the color of hair. This can be applied to any type of hair: regular hair, facial hair, or eyebrows.

index_of_refraction: float

Defines how the hair bends light that is traveling through it.

All hair is at least somewhat translucent, lighter hair in particular. This setting simulates the changes in the direction of light rays as they travel through the hair, which is an important part of making hair look realistic.

Min: 1.4

Max: 1.65

melanin: float

Together with redness, defines the base color of the hairs.

This control sets the amount of black in the strands of hair.

Min: 0 - fully white hair

Max: 1 - fully black hair

redness: float

Together with melanin, defines the base color of the hairs.

This control sets the amount of red in the strands of hair. Redness is primarily noticeable when there is a medium amount of melanin in the hair. When melanin is close to 0 or 1, redness has little or no effect.

Min: 0 - no redness in the hair

Max: 1 - maximum redness in the hair

roughness: float

Defines the reflectivity of the hair. The rougher the surface of the hair, the more light gets absorbed within it and gets reflected as diffuse light rather than mirror-like reflections.

Min: 0.15 - dull or matte hair

Max: 0.5 - shiny and reflective hair

whiteness: float

Defines how much the hair has greyed or whitened. The amount of greying is not strictly linear, but it is still useful to think of this value as whitening the hair roughly in percentage terms. As a rule, values between 0.4 and 0.7 generate greying hair, while values above 0.7 generate white hair.

Min: 0 - no whitening or greying in the hair

Max: 1 - the hair has gone fully white

class datagen.api.assets.Head(*, eyes: Eyes, hair: Optional[Hair] = None, eyebrows: Optional[Hair] = None, facial_hair: Optional[Hair] = None, location: Point = None, rotation: Rotation = None, expression: Expression = None)

Aspects of a 3D human asset that define the appearance and positioning of the head.

expression: Expression

Defines the type and intensity of the human’s facial expression.

eyebrows: Optional[Hair]

The eyebrows worn by this actor, including the 3D eyebrows asset and all related parameters such as color controls.

eyes: Eyes

The pair of eyes worn by this actor, including the 3D eyes asset and all related parameters such as eye textures, direction of gaze, and eyelid closure.

facial_hair: Optional[Hair]

The facial hair worn by this actor, including the 3D facial hair asset and all related parameters such as color controls.

hair: Optional[Hair]

The hair worn by this actor, including the 3D hair asset and all related parameters such as color controls.

location: Point

Defines the location of the human head in global coordinates, using a single reference point. Units are measured in meters.

Since the head is not a point-sized object, these coordinates actually define the position of a point at the front of the neck: the small pocket at the center of the V. (This pocket is known in medicine as the “suprasternal notch”.)

The rest of the 3D head is built around that point.

rotation: Rotation

Defines the rotation of the human head about the neck, using three rotation controls measured in degrees.

The neck remains for the most part fixed and facing in the -y direction, with slight changes based on the intensity of the rotation.

class datagen.api.assets.Human(*, id: str, head: Head)

A 3D asset representing a human being.

Use datagen.api.catalog.humans to get assets of this type from the asset catalog.

head: Head

The part of the human model that defines aspects of the human head: hair style and color, facial hair, eye textures, etc.

id: str

The UUID that identifies the specific human model.

class datagen.api.assets.HumanDatapoint(*, human: Human, camera: Camera, accessories: Optional[Accessories] = None, background: Optional[Background] = None, lights: Optional[List[Light]] = None)

Each instance of this class represents a single datapoint containing a single generated human being.

Use the datagen.api.create_datapoint() function to group multiple datapoints into a single data request.

accessories: Optional[Accessories]

Data defining accessories worn by the human in the scene, if any.

background: Optional[Background]

Data defining the background of the scene.

This property is required if, inside the camera property, IntrinsicParams.wavelength = Wavelength.VISIBLE.

If IntrinsicParams.wavelength = Wavelength.NIR, you must leave this property null.

camera: Camera

Data defining the camera’s location, orientation, and intrinsic parameters.

human: Human

Data defining the human in the scene.

lights: Optional[List[Light]]

Data defining special light sources in the scene, if any.

class datagen.api.assets.IntrinsicParams(*, projection: Projection = Projection.PERSPECTIVE, resolution_width: ConstrainedIntValue = 512, resolution_height: ConstrainedIntValue = 512, fov_horizontal: ConstrainedIntValue = 8, fov_vertical: ConstrainedIntValue = 8, sensor_width: float = 15, wavelength: Wavelength = Wavelength.VISIBLE)

The set of intrinsic parameters that define a camera’s internal workings.

For use with the Camera object.

fov_horizontal: int

The angle covered by the camera lens in the horizontal direction, in degrees.

Min: 5

Max: 180

fov_vertical: int

The angle covered by the camera lens in the vertical direction, in degrees.

Min: 5

Max: 180

projection: Projection

The basic type of projection that is used by the camera.

resolution_height: int

The height component of the camera’s image resolution, in pixels.

Min: 64

Max: 4096

resolution_width: int

The width component of the camera’s image resolution, in pixels.

Min: 64

Max: 4096

sensor_width: float

The horizontal width of the camera sensor, measured in millimeters.

Currently this setting does not have any effect on the output image.

wavelength: Wavelength

The type of light collected by the camera sensor (such as visible spectrum or near-infrared).

class datagen.api.assets.LensColor(value)

The available base colors for glasses lenses, for use in Glasses.lens_color.

BLACK = 'black'

BLUE = 'blue'

GREEN = 'green'

RED = 'red'

YELLOW = 'yellow'

class datagen.api.assets.Light(*, light_type: LightType, beam_angle: ConstrainedFloatValue = 6.5, brightness: ConstrainedFloatValue = 300.0, falloff: ConstrainedFloatValue = 0.5, location: Point = None, rotation: Rotation = None)

An object representing a specialized light source.

HumanDatapoint.lights can list any number of these for inclusion in the rendering of your scene.

beam_angle: float

The angle covered by the light cone.

Min: 3

Max: 90

brightness: float

The amount of energy output by the bulb in the form of light.

The wattage of this spotlight is not the same as the wattage listed on commercial light bulbs. On a commercial lightbulb, the wattage value measures energy usage; here the wattage measures energy output.

Min: 0

Max: 1000

falloff: float

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.

Min: 0 - at this value, the entire beam is at full strength, with a sharp cutoff between light and dark at the edges

Max: 1 - at this value, only the very center of the beam is at full strength, with the intensity tapering off gradually as you approach the edge.

light_type: LightType

The type of special light source.

location: Point

The location of the light in the 3D environment, in global coordinates measured in meters.

rotation: Rotation

The orientation of the spotlight in the 3D environment, in Euler angles measured in degrees.

In the default orientation (yaw 0, pitch 0, roll 0), the spotlight is centered on, and points in, the +y direction.

Rotations are then applied in the order of yaw, pitch, then roll.

class datagen.api.assets.LightType(value)

The available types of special lighting, for use in Light.light_type.

NIR = 'nir'

class datagen.api.assets.Mask(*, id: str, color: MaskColor = MaskColor.BLUE, texture: MaskTexture = MaskTexture.CLOTH, roughness: ConstrainedFloatValue = 0.5, position: MaskPosition = MaskPosition.ON_NOSE)

A 3D asset representing a facemask.

Use datagen.api.catalog.masks to get assets of this type from the asset catalog.

color: MaskColor

The base color of the mask, which is further influenced by the roughness property.

id: str

A UUID that identifies a specific mask asset.

position: MaskPosition

The position of the mask on the human body.

roughness: float

A measure of the reflectivity of the mask. Lower values make the mask shinier and more reflective; higher values make the mask more matte.

Min: 0

Max: 1

texture: MaskTexture

The texture or pattern of the cloth from which the mask is made.

class datagen.api.assets.MaskColor(value)

The available base colors for masks, for use in Mask.color.

BLACK = 'black'

BLUE = 'blue'

GREEN = 'green'

RED = 'red'

YELLOW = 'yellow'

class datagen.api.assets.MaskPosition(value)

The positions where a mask accessory can be worn, for use in Mask.position.

ON_CHIN = 'on_chin'

ON_MOUTH = 'on_mouth'

ON_NOSE = 'on_nose'

class datagen.api.assets.MaskTexture(value)

The available base textures for a mask asset, for use in Mask.texture.

CLOTH = 'cloth'

DIAMOND_PATTERN = 'diamond_pattern'

WOVEN = 'woven'

class datagen.api.assets.Point(*, x: ConstrainedFloatValue, y: ConstrainedFloatValue, z: ConstrainedFloatValue)

A point in 3D space, in global coordinates measured in meters. This can define, e.g., the location of the human head or the camera in the scene.

x: float

Defines the position of an object on the left-right axis. Lower values move the object to the right, while higher values move the object to the left (from the point of view of the default position of a human asset: at the origin, with the neck facing in the -y direction).

Min: -5.0

Max: 5.0

y: float

Defines the position of an object on the back-to-front axis. Lower values move the object forward, while higher values move the object backward (from the point of view of the default position of a human asset: at the origin, with the neck facing in the -y direction).

Min: -5.0

Max: 5.0

z: float

Defines the position of an object on the up-down axis. Lower values move the object down, higher values move the object up.

Min: -5.0

Max: 5.0

class datagen.api.assets.Projection(value)

The available camera projections, for use in IntrinsicParams.projection.

PERSPECTIVE = 'perspective'

This projection is currently the only one available.

class datagen.api.assets.Rotation(*, yaw: float, roll: float, pitch: float)

A set of rotation instructions. These are used in multiple places, such as datagen.api.assets.ExtrinsicParams.rotation and datagen.api.assets.Head.rotation.

pitch: float

Rotates the object around the x axis.

roll: float

Rotates the object around the y axis.

yaw: float

Rotates the object around the z axis.

class datagen.api.assets.Vector(*, x: ConstrainedFloatValue, y: ConstrainedFloatValue, z: ConstrainedFloatValue)

A direction in 3D space. This can define, e.g., the direction of eye gaze.

x: float

The component of the vector along the left-right axis. Lower values angle the vector to the right, while higher values angle the vector to the left (from the point of view of the default position of a human asset: at the origin, with the neck facing in the -y direction).

Min: -5.0

Max: 5.0

y: float

The component of the vector along the back-to-front axis. Lower values angle the vector to the front, while higher values angle the vector to the back (from the point of view of the default position of a human asset: at the origin, with the neck facing in the -y direction).

Min: -5.0

Max: 5.0

z: float

The component of the vector along the up-down axis. Lower values angle the vector downward, while higher values angle the vector upward.

Min: -5.0

Max: 5.0

class datagen.api.assets.Wavelength(value)

The available camera sensor types, for use in IntrinsicParams.wavelength.

NIR = 'nir'

This camera detects near-infrared light.

VISIBLE = 'visible'

This camera detects visible spectrum light.