Explore platform

Accessing the ‘hair’ asset catalog

You can access the catalog of hair assets using the datagen.api.catalog.hair class. It contains two important functions:

!pip install datagen-tech -q

get()

The datagen.api.catalog.hair.get() function gets one or more hair assets from the asset catalog. These assets come in the form of objects of the datagen.api.assets.Hair class.

Make these samples interactive

To get the full set of hair assets:

from datagen.api import catalog

catalog.hair.get()

<AssetInstancesList(231)>

To get a specific hair asset using its id:

from datagen.api import catalog

catalog.hair.get(id="d5ed1409-f401-41bf-8edd-579eead817a4")

Hair(

id=’d5ed1409-f401-41bf-8edd-579eead817a4’,

color_settings=HairColor(

melanin=0.2,

redness=0.2,

whiteness=0.25,

roughness=0.15,

index_of_refraction=1.4

),

attributes=HairAttributes(

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

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

gender_match=[Gender.MALE],

length=HairLength.BUZZ_CUT,

style=[HairStyle.CREW_CUT]

)

)

To cap the number of returned hair assets using the limit parameter:

from datagen.api import catalog

catalog.hair.get(limit=4)

<AssetInstancesList(4)>

To get a single hair asset using the limit parameter:

from datagen.api import catalog

catalog.hair.get(limit=1)

Hair(

id=’003cbe9f-3d2a-409c-bcfe-bfa085694199’,

color_settings=HairColor(

melanin=0.2,

redness=0.2,

whiteness=0.25,

roughness=0.15,

index_of_refraction=1.4

),

attributes=HairAttributes(

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

ethnicity_match=[Ethnicity.MEDITERRANEAN, Ethnicity.AFRICAN, Ethnicity.HISPANIC],

gender_match=[Gender.MALE],

length=HairLength.BUZZ_CUT,

style=[HairStyle.CREW_CUT]

)

)

To filter the hair assets using the attributes parameter (see below for the list of valid hair attributes):

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

catalog.hair.get(ethnicity_match=attributes.Ethnicity.SOUTH_ASIAN, style=attributes.HairStyle.BANGS)

<AssetInstancesList(11)>

count()

The datagen.api.catalog.hair.count() function tells you how many hair assets match your query. You can count how many hair assets there are in total, or filter the catalog using hair attributes.

Make these samples interactive

To count the full set of hair assets:

from datagen.api import catalog

catalog.hair.count()

231

To count the number of hair assets that match certain attributes (see below for the list of valid hair attributes):

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

catalog.hair.count(age_group_match=attributes.Age.YOUNG, ethnicity_match=attributes.Ethnicity.HISPANIC, length=attributes.HairLength.CHIN)

13

Hair attributes

The datagen.api.catalog.attributes.HairAttributes class defines which attributes can be used to filter the catalog of hair assets:

class datagen.api.catalog.attributes.HairAttributes

Each hair asset contains the following read-only attributes.

When you call the datagen.api.catalog.hair.get() or datagen.api.catalog.hair.count() functions, you can use this attribute to filter the catalog.

age_group_match: List[Enum]

Matches the requested hairstyle(s) with a desired age group. Uses the Age enum.

A hairstyle may match with any number of age groups, or even all of them.

NOTE: Age group matches are recommendations only and are not mandatory.

ethnicity_match: List[Enum]

Matches the requested hairstyle(s) with a desired ethnicity. Uses the Ethnicity enum.

A hair asset may match with any number of ethnicities, or even all of them.

NOTE: Ethnicity matches are recommendations only and are not mandatory.

gender_match: List[Enum]

Matches the requested hairstyle(s) with a desired gender. Uses the Gender enum.

A hair asset may match with either or both genders.

NOTE: Gender matches are recommendations only and are not mandatory.

length: Enum

The length of the haircut. Uses the HairLength enum.

style: List[Enum]

The style of the haircut, e.g., ponytail, crew cut, or afro. Uses the HairStyle enum.

A hair asset may match with more than one style.

For example, one hair asset may be both “balding” and “crew_cut”.

Sample usage:

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

catalog.hair.get(age_group_match=attributes.Age.ADULT, ethnicity_match=attributes.Ethnicity.SOUTHEAST_ASIAN, gender_match=attributes.Gender.FEMALE, length=attributes.HairLength.CHIN, style=attributes.HairStyle.CURTAIN)

<AssetInstancesList(5)>

Here is the complete list of valid values for these attributes:

class datagen.api.catalog.attributes.Age

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

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

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'

class datagen.api.catalog.attributes.HairLength

The list of valid hair lengths.

This enum is valid for use in the following attributes:

• HairAttributes.length

Values:

ARMPIT = 'armpit'

BUZZ_CUT = 'buzz_cut'

CHIN = 'chin'

EAR = 'ear'

MID_BACK = 'mid_back'

SHOULDER = 'shoulder'

TAILBONE = 'tailbone'

UNDEFINED = 'undefined'

class datagen.api.catalog.attributes.HairStyle

The list of valid hair styles.

This enum is valid for use in the following attributes:

• HairAttributes.style

Values:

AFRO = 'afro'

BALDING = 'balding'

BANGS = 'bangs'

BOB = 'bob'

BUN = 'bun'

CREW_CUT = 'crew_cut'

CURTAIN = 'curtain'

HAIR_DOWN = 'hair_down'

HIGH_TOP_CUT = 'high_top_cut'

LAYERED = 'layered'

PONYTAIL = 'ponytail'

PULLED_BACK = 'pulled_back'

UNDEFINED = 'undefined'

Properties of hair objects

When you get a hair object from the catalog, you can edit that object in certain ways. These are the editable properties of hair objects:

id

string

The id property selects a specific hairstyle from our catalog.

Tip

To download a CSV with a complete list of the hairstyles that we have available, click here

This property defines the shape of the hair but not its color or behavior in the light. Datagen has hundreds of unique hairstyles divided…

By gender

Female

To download a CSV with a complete list of UUIDs that define hairstyles appropriate for female actors, click here

Male

To download a CSV with a complete list of UUIDs that define hairstyles appropriate for male actors, click here

By style

Afros

To download a CSV with a complete list of UUIDs that define afro hairstyles, click here

Balding

To download a CSV with a complete list of UUIDs that define balding hairstyles, click here

Bangs

To download a CSV with a complete list of UUIDs that define hairstyles with bangs, click here

Bobs

To download a CSV with a complete list of UUIDs that define bob hairstyles, click here

Buns

To download a CSV with a complete list of UUIDs that define hairstyles with buns, click here

Crew cuts

To download a CSV with a complete list of UUIDs that define crew cut hairstyles, click here

Curtains

To download a CSV with a complete list of UUIDs that define curtain hairstyles, click here

Hair down

To download a CSV with a complete list of UUIDs that define hairstyles with the hair down, click here

High top cuts

To download a CSV with a complete list of UUIDs that define high top cut hairstyles, click here

Layered

To download a CSV with a complete list of UUIDs that define layered hairstyles, click here

Ponytails

To download a CSV with a complete list of UUIDs that define ponytail hairstyles, click here

Pulled back

To download a CSV with a complete list of UUIDs that define hairstyles with the hair pulled back, click here

Undefined

To download a CSV with a complete list of UUIDs that define hairstyles that don’t fit neatly into the other categories, click here

By length

Armpit

To download a CSV with a complete list of UUIDs that define armpit-length hairstyles, click here

Buzz cut

To download a CSV with a complete list of UUIDs that define buzz cut-length hairstyles, click here

Chin

To download a CSV with a complete list of UUIDs that define chin-length hairstyles, click here

Ear

To download a CSV with a complete list of UUIDs that define ear-length hairstyles, click here

Mid-back

To download a CSV with a complete list of UUIDs that define hairstyles with lengths that reach the middle of the back, click here

Shoulder

To download a CSV with a complete list of UUIDs that define shoulder-length hairstyles, click here

Tailbone

To download a CSV with a complete list of UUIDs that define tailbone-length hairstyles, click here

Undefined

To download a CSV with a complete list of UUIDs that define hairstyles of variable or unusual lengths, click here

By texture

Curly

To download a CSV with a complete list of UUIDs that define curly hairstyles, click here

Kinky

To download a CSV with a complete list of UUIDs that define kinky hairstyles, click here

Straight

To download a CSV with a complete list of UUIDs that define straight hairstyles, click here

Wavy

To download a CSV with a complete list of UUIDs that define wavy hairstyles, click here

Undefined

To download a CSV with a complete list of UUIDs that define hairstyles with textures that don’t fit neatly into the other categories, click here

color_settings

The color_settings object contains a variety of settings that determine the color and shine of the actor’s hair.

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

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

hair=catalog.hair.get(limit=1)
hair.color_settings=assets.HairColor(melanin=0.9, redness=0.7, whiteness=0.04, roughness=0.23, index_of_refraction=1.6)

The color_settings object contains the following properties:

melanin and redness

64-bit floats

The melanin and redness values together define the color of the actor’s hair. Melanin is the amount of black color in the hairs; redness is the amount of red. Both properties can accept floating-point values between 0 and 1:

Hair melanin vs. redness

melanin=0 redness=0	melanin=0 redness=0.25	melanin=0 redness=0.5	melanin=0 redness=0.75	melanin=0 redness=1
melanin=0.25 redness=0	melanin=0.25 redness=0.25	melanin=0.25 redness=0.5	melanin=0.25 redness=0.75	melanin=0.25 redness=1
melanin=0.5 redness=0	melanin=0.5 redness=0.25	melanin=0.5 redness=0.5	melanin=0.5 redness=0.75	melanin=0.5 redness=1
melanin=0.75 redness=0	melanin=0.75 redness=0.25	melanin=0.75 redness=0.5	melanin=0.75 redness=0.75	melanin=0.75 redness=1
melanin=1 redness=0	melanin=1 redness=0.25	melanin=1 redness=0.5	melanin=1 redness=0.75	melanin=1 redness=1

As you can see in the images above, the relationship between melanin and redness is not linear. The two influence each other greatly. At very high and very low concentrations of melanin, changing the redness has little or no effect. When melanin has medium-level values, the effects of redness are more noticeable.

The values for typical hair colors are at or close to:

Blonde: melanin=0.2, redness=0

Red: melanin=0.5, redness=1

Black: melanin=1, redness=0

Dark brown: melanin=0.8, redness=0.2

Light brown: melanin=0.5, redness=0.6

whiteness

64-bit float

The whiteness property defines how much of the hair has begun to go grey or white. This property accepts floating-point values from 0 (no white hairs) to 1 (fully white).

whiteness=0

whiteness=0.25

whiteness=0.5

whiteness"=0.75

whiteness=1

While the increase in grey and white hairs using this property is not strictly linear, 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.

roughness

64-bit float

The roughness property affects 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.

This property accepts floating-point values from 0.15 to 0.5.

roughness=0.15

roughness=0.225

roughness=0.5

index_of_refraction

64-bit float

The index_of_refraction property affects how the hair bends light that is traveling through it. All hair is at least somewhat translucent, lighter hair in particular. Simulating the changes in the direction of light rays as they travel through the hair is an important part of making hair look realistic.

This property accepts floating-point values from 1.4 to 1.65.

index_of_refraction=1.4

index_of_refraction=1.525

index_of_refraction=1.65

Although the above images may appear to be in different colors, they all have the same amount of melanin; the only change is in how light reflects inside and through the individual hairs.