Try for free

The ‘Humans’ asset catalog

!pip install datagen-tech -q

Accessing the catalog

class datagen.api.catalog.humans

The “humans” object gives you access to the catalog of human identities. The Assets provided by this catalog are of type datagen.api.assets.Human.

Each human identity comes with default values for subordinate assets: hair, eyes, eyebrows, and (when appropriate) facial hair. You can change any or all of these values.

You can query the humans catalog using these functions:

datagen.api.catalog.humans.get(self, id: str = None, limit: int = None, **attributes) → Union[Asset, List[Asset]]:

Gets human assets from the asset catalog.

Parameters:

• id (str) – Optional. Returns a single Asset matching the chosen UUID.

• limit (int) –

  Optional. Caps the number of Assets that will be included in the response.

  • If limit=1, returns a single Asset object.

  • If limit>1, returns an object of type List[Asset] (even if there is only one matching human asset in the list).

• attributes (Any) – Optional. A dictionary of attributes that you can use to filter the catalog. For details see Human attributes below.

Returns:

The asset or assets that match your search query

Return type:

• List[Asset] in the form of a lazy list

• Asset when limit=1 or when an id is provided

Sample usage

Make these samples interactive

• Getting the full set of human assets:

from datagen.api import catalog

catalog.humans.get()

<AssetInstancesList(52151)>

• Getting a specific human asset by id:

from datagen.api import catalog

catalog.humans.get(id="e5c4ba9b-4648-4e5b-9244-5c9373276408")

Human(

id=’e5c4ba9b-4648-4e5b-9244-5c9373276408’,

head=Head(

eyes=Eyes(

id=’ebdd956c-b763-490e-9afb-baed2c98a0ff’,

target_of_gaze=Gaze(distance=15.0, direction=Vector(x=0.0, y=-1.0, z=0.0)),

eyelid_closure=0.0,

attributes=EyesAttributes(color=EyesColor.BROWN)

),

hair=Hair(

id=’cb7f5afa-70ba-4c8c-a68b-c3bac225e3dd’,

color_settings=HairColor(

melanin=0.0948,

redness=0.9907,

whiteness=0.0679,

roughness=0.2827,

index_of_refraction=1.4086

),

attributes=HairAttributes(

age_group_match=[Age.OLD, Age.YOUNG, Age.ADULT],

ethnicity_match=[

Ethnicity.SOUTHEAST_ASIAN,

Ethnicity.SOUTH_ASIAN,

Ethnicity.EAST_ASIAN,

Ethnicity.HISPANIC,

Ethnicity.NORTH_EUROPEAN

],

gender_match=[Gender.FEMALE],

length=HairLength.UNDEFINED,

style=[HairStyle.PONYTAIL, HairStyle.PULLED_BACK]

)

),

eyebrows=Hair(

id=’7b14ee11-4128-411e-8213-9402ec6a189d’,

color_settings=HairColor(

melanin=0.0948,

redness=0.9907,

whiteness=0.0679,

roughness=0.2827,

index_of_refraction=1.4086

),

attributes=EyebrowsAttributes(gender_match=[Gender.FEMALE])

),

facial_hair=None,

location=Point(x=0.0, y=0.0, z=0.0),

rotation=Rotation(yaw=0.0, roll=0.0, pitch=0.0),

expression=Expression(name=ExpressionName.NEUTRAL, intensity=1.0)

),

attributes=HumanAttributes(

age=Age.YOUNG,

ethnicity=Ethnicity.MEDITERRANEAN,

gender=Gender.FEMALE

)

)

• Using the limit parameter to cap the number of human assets:

from datagen.api import catalog

catalog.humans.get(limit=4)

<AssetInstancesList(4)>

• Using the limit parameter to get a single human asset:

from datagen.api import catalog

catalog.humans.get(limit=1)

Human(

id=’00005401-8dc0-4d6c-9cf1-743f9b70beea’,

head=Head(

eyes=Eyes(

id=’a5a54dc7-53c3-41c4-bf39-ced2b794dd50’,

target_of_gaze=Gaze(distance=15.0, direction=Vector(x=0.0, y=-1.0, z=0.0)),

eyelid_closure=0.0,

attributes=EyesAttributes(color=EyesColor.BROWN)

),

hair=Hair(

id=’51cfc652-f90b-4850-aa5a-0128a07f0f89’,

color_settings=HairColor(

melanin=0.2899,

redness=0.3085,

whiteness=0.6258,

roughness=0.357,

index_of_refraction=1.4584

),

attributes=HairAttributes(

age_group_match=[Age.OLD, Age.ADULT],

ethnicity_match=[Ethnicity.HISPANIC, Ethnicity.SOUTH_ASIAN, Ethnicity.NORTH_EUROPEAN],

gender_match=[Gender.FEMALE],

length=HairLength.SHOULDER,

style=[HairStyle.CURTAIN, HairStyle.HAIR_DOWN, HairStyle.BOB]

)

),

eyebrows=Hair(

id=’880f57e4-bdc6-406e-bf9d-f76c633cbba2’,

color_settings=HairColor(

melanin=0.2899,

redness=0.3085,

whiteness=0.6258,

roughness=0.357,

index_of_refraction=1.4584

),

attributes=EyebrowsAttributes(gender_match=[Gender.FEMALE])

),

facial_hair=None,

location=Point(x=0.0, y=0.0, z=0.0),

rotation=Rotation(yaw=0.0, roll=0.0, pitch=0.0),

expression=Expression(name=ExpressionName.NEUTRAL, intensity=1.0)

),

attributes=HumanAttributes(age=Age.OLD, ethnicity=Ethnicity.NORTH_EUROPEAN, gender=Gender.FEMALE)

)

• Using attributes to filter the catalog:

from datagen.api import catalog
from datagen.api.catalog import attributes

catalog.humans.get(gender=attributes.Gender.MALE, ethnicity=attributes.Ethnicity.MEDITERRANEAN)

<AssetInstancesList(3331)>

datagen.api.catalog.humans.count(self, **attributes) → int:

Queries the catalog for the number of assets matching a certain request

Parameters:

attributes (Any) – Optional. A dictionary of attributes that you can use to filter the catalog. For details see Human attributes below.

Returns:

The number of assets in the catalog matching your query.

Return type:

int

Sample usage

Make these samples interactive

• Counting the full set of human assets:

from datagen.api import catalog

catalog.humans.count()

52151

• Using attributes to filter the catalog:

from datagen.api import catalog
from datagen.api.catalog import attributes

catalog.humans.count(age=attributes.Age.YOUNG, ethnicity=attributes.Ethnicity.AFRICAN)

853

Human attributes

class datagen.api.catalog.attributes.HumanAttributes(age: Enum, ethnicity: Enum, gender: Enum)

Each human asset contains the following read-only attributes.

When you call the datagen.api.catalog.humans.get() or datagen.api.catalog.humans.count() functions, you can use these attributes to filter the catalog.

age: Enum

The age category of the human asset. Uses the Age enum.

ethnicity: Enum

The ethnicity of the human asset. Uses the Ethnicity enum.

gender: Enum

The gender of the human asset. Uses the Gender enum.

Sample usage:

from datagen.api import catalog
from datagen.api.catalog import attributes

catalog.humans.get(age=attributes.Age.ADULT,ethnicity=attributes.Ethnicity.SOUTH_ASIAN,gender=attributes.Gender.FEMALE)

<AssetInstancesList(189)>

Here is the complete list of valid values for each attribute:

class datagen.api.catalog.attributes.Age(value)

The list of available genders.

This enum is valid for use in the following attributes:

• HumanAttributes.age

• HairAttributes.age_group_match

Values:

ADULT = 'adult'

Approximate age range: 31-50

OLD = 'old'

Approximate age range: 51+

YOUNG = 'young'

Approximate age range: 18-30

class datagen.api.catalog.attributes.Ethnicity(value)

The list of available ethnicities.

This enum is valid for use in the following attributes:

• HumanAttributes.ethnicity

• HairAttributes.ethnicity_match

AFRICAN = 'african'

EAST_ASIAN = 'east_asian'

HISPANIC = 'hispanic'

MEDITERRANEAN = 'mediterranean'

NORTH_EUROPEAN = 'north_european'

SOUTHEAST_ASIAN = 'southeast_asian'

SOUTH_ASIAN = 'south_asian'

class datagen.api.catalog.attributes.Gender(value)

The list of available genders.

This enum is valid for use in the following attributes:

• HumanAttributes.gender

• GlassesAttributes.gender

• MaskAttributes.gender

• HairAttributes.gender_match

• EyebrowsAttributes.gender_match

Values:

FEMALE = 'female'

MALE = 'male'

Properties of human objects

These are the editable properties of background objects:

id

string

The UUID of the actor in the scene.

This property selects one of Datagen’s thousands of available identities to be the actor at the (metaphorical) center of your scene. The value of this property defines the skin tone, skin textures, and body shape of the generated human subject. It also includes default values for the hair, eyes, eyebrows, and other aspects of human identity that can be easily altered.

Tip

To download a CSV with a complete list of available identities, click here

The actors in our catalogue are grouped…

By gender

Females

To download a CSV with a complete list of available female identities, click here

Males

To download a CSV with a complete list of available male identities, click here

By age group

Younger (ages 18-30)

To download a CSV with a complete list of available identities ages 18-30, click here

Adult (ages 31-50)

To download a CSV with a complete list of available identities ages 31-50, click here

Older (ages 51+)

To download a CSV with a complete list of available identities ages 51+, click here

By ethnicity

Africans

To download a CSV with a complete list of available African identities, click here

Hispanics

To download a CSV with a complete list of available Hispanic identities, click here

Mediterraneans

To download a CSV with a complete list of available Mediterranean identities, click here

North Europeans

To download a CSV with a complete list of available North European identities, click here

South Asians

To download a CSV with a complete list of available South Asian identities, click here

Southeast Asians

To download a CSV with a complete list of available Southeast Asian identities, click here

head

The head object defines aspects of the human’s appearance that relate to the head. It contains the following objects:

eyes

An eyes asset from the asset catalog. Each human identity comes with default eyes, which you can edit or replace.

This code takes a human from the catalog and changes the default eyes:

from datagen.api import catalog

human=catalog.human.get(limit=1)
human.head.eyes=catalog.eyes.get(limit=1)

See eyes for more.

hair

A hair asset from the asset catalog. Each human identity comes with default hair, which you can edit, remove, or replace.

This code takes a human from the catalog and changes the default hair:

from datagen.api import catalog

human=catalog.human.get(limit=1)
human.head.hair=catalog.hair.get(limit=1)

See hair.

eyebrows

An eyebrows asset from the asset catalog. Each human identity comes with default eyebrows, which you can edit, remove, or replace.

This code takes a human from the catalog and changes the default eyebrows:

from datagen.api import catalog

human=catalog.human.get(limit=1)
human.head.eyebrows=catalog.eyebrows.get(limit=1)

See eyebrows.

facial_hair

A facial_hair asset from the asset catalog. Each human identity comes with default facial hair (in many cases this default is “none”). You can add, remove, or change this default.

This code takes a human from the catalog and changes the default facial hair:

from datagen.api import catalog

human=catalog.human.get(limit=1)
human.head.facial_hair=catalog.beards.get(limit=1)

See facial_hair.

location

The location object defines where the head is located in the scene.

Location is defined using x, y, and z global coordinates, measured in meters. Each value is a floating-point variable that can range from -5 to 5 meters.

Important

The location of the head may be the most critical setting in your data request. If the head is in the wrong place, it might not be in the camera frame and you will render nothing but the background.

Tip

Use this visualization tool to experiment with positioning the actor’s head in the frame.

This code takes a human from the catalog and changes the default head location:

from datagen.api import catalog
from datagen.api import assets

human=catalog.humans.get(limit=1)
human.head.location=assets.Point(x=0.8, y=-0.04, z=0.3)

For an in-depth look at these axes, as well as which part of the head is actually placed at the coordinates you set, see About our coordinate systems.

rotation

The rotation object defines how the actor’s head will be rotated about the neck, while the neck remains upright. When we generate your datapoint, the coordinates of the neck are set first using the location setting; afterwards, we rotate the head about the neck using pitch, yaw, and roll settings that you define here.

The pitch, yaw, and roll properties are floating-point values measured in degrees. Pitch can range from -90 to 90, while yaw and roll can range from -45 to 45.

Tip

Use this visualization tool to experiment with rotating the actor’s head in the scene. Note that the visualizer rotates the head and neck together; when you create your datapoints, the neck will be held still while the head is tilted around it in a realistic fashion.

This code takes a human from the catalog and changes the default head rotation:

from datagen.api import catalog
from datagen.api import assets

human=catalog.humans.get(limit=1)
human.head.rotation=assets.HeadRotation(yaw=23.5, roll=25.8, pitch=36.4)

expression

The expression object defines the type and the intensity of your actor’s facial expression. The expression type is defined using an Enum, while the intensity is a float that ranges from 0 (neutral expression) to 1 (maximum intensity).

Examples of expressions:

Surprise (intensity 1)	Disgust (intensity 0.75)	Happiness (intensity 0.75)
Anger (intensity 1)	Neutral expression	Fear (intensity 0.75)
Mouth open (intensity 0.25)	Sadness (intensity 0.5)	Contempt (intensity 0.25)

This code takes a human from the catalog and changes the default expression:

from datagen.api import catalog
from datagen.api import assets

human=catalog.humans.get(limit=1)
human.head.expression=assets.Expression(name=assets.ExpressionName.HAPPINESS,intensity=0.65)