The ‘Eyes’ asset catalog#

!pip install datagen-tech -q

Accessing the catalog#

class datagen.api.catalog.eyes#

The “eyes” object gives you access to the catalog of eye textures. The Assets provided by this catalog are of type datagen.api.assets.Eyes.

You can query the eyes catalog using these functions:

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

Gets eyes 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 eyes asset in the list).

  • attributes (Any) – Optional. A dictionary of attributes that you can use to filter the catalog. For details see Eye 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

  • Getting the full set of eyes assets:

from datagen.api import catalog

catalog.eyes.get()

<AssetInstancesList(401)>

  • Getting a specific eyes asset by id:

from datagen.api import catalog

catalog.eyes.get(id="9eb72c2d-5bc7-4d6d-bfb2-4940784a5d1a")

Eyes(

id=’9eb72c2d-5bc7-4d6d-bfb2-4940784a5d1a’,

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)

)

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

from datagen.api import catalog

catalog.eyes.get(limit=4)

<AssetInstancesList(4)>

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

from datagen.api import catalog

catalog.eyes.get(limit=1)

Eyes(

id=’008f5f51-b320-44ca-9762-cd31b0a8e121’,

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.BLUE)

)

  • Using attributes to filter the catalog:

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

catalog.eyes.get(color=attributes.EyesColor.BROWN)

<AssetInstancesList(200)>

datagen.api.catalog.eyes.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 Eye attributes below.

Returns:

The number of assets in the catalog matching your query.

Return type:

int

Sample usage

  • Counting the full set of eyes assets:

from datagen.api import catalog

catalog.eyes.count()

401

  • Using attributes to filter the catalog:

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

catalog.eyes.get(color=attributes.EyesColor.BLUE)

101

Eye attributes#

class datagen.api.catalog.attributes.EyesAttributes

Each eyes asset contains the following read-only attribute.

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

color: Enum

The base color of the texture of the Eyes asset. Uses the EyesColor enum.

Sample usage:

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

catalog.eyes.get(color=attributes.EyesColor.BROWN)

<AssetInstancesList(200)>

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

class datagen.api.catalog.attributes.EyesColor

The list of available eye colors.

This enum is valid for use in the following attributes:

Values:

BLUE = 'blue'
BROWN = 'brown'
GREEN = 'green'

Properties of eye objects#

These are the editable properties of eye objects:

id

string

The UUID of the texture that you want to apply to the eyes.

Tip

To download a CSV with a complete list of eye textures, click here

This property defines the color and texture of the actor’s eyes. Datagen has hundreds of eye textures available in the following colors:

Blue

To download a CSV with a complete list of blue eye textures, click here

Brown

To download a CSV with a complete list of brown eye textures, click here

Green

To download a CSV with a complete list of green eye textures, click here

eyelid_closure

64-bit float

The eyelid_closure property defines how much the actor’s eyes are closed. Valid values for this property range from 0 (fully open) to 1 (fully closed).

../../_images/eyelid_closure_01.png

eyelid_closure=0#
../../_images/eyelid_closure_0.251.png

eyelid_closure=0.25#
../../_images/eyelid_closure_0.51.png

eyelid_closure=0.5#
../../_images/eyelid_closure_0.751.png

eyelid_closure=0.75#
../../_images/eyelid_closure_11.png

eyelid_closure=1#

Note

If your actor is looking down, their eyes will automatically be closed at least some amount.

This code takes a pair of eyes from the catalog and changes the default eyelid closure:

from datagen.api import catalog

eyes=catalog.eyes.get(limit=1)
eyes.eyelid_closure=0.8

target_of_gaze

object

The target_of_gaze object defines the point in space that the actor’s eyes are focused on.

The target point is defined based on direction and distance from an origin: the midpoint between the center of the actor’s left pupil and the center of the actor’s right pupil.

This code takes a pair of eyes from the catalog and changes the default direction of gaze:

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

eyes=catalog.eyes.get(limit=1)
eyes.target_of_gaze=assets.Gaze(distance=1.3, direction=assets.Vector(x=0.3,y=-1.0, z=-0.4))

direction

object

The direction object contains the x, y, and z components of a normalized vector that defines the direction that the actor’s eyes are pointing.

This vector is defined in the eye space, meaning that if the head is turned or tilted all of these directions will be turned or tilted along with it.

  • The -x direction is to the eye’s right, while the +x direction is to the eye’s left.

  • The -y direction is directly ahead of the eye, while the +y direction is directly behind the eye.

  • The -z direction is straight down, while the +z direction is straight up.

The origin point for this normalized vector is the midpoint between the center of the actor’s left pupil and the center of the actor’s right pupil; the directions are in the head space.

Some sample values for the direction object:

../../_images/target_of_gaze_upper_right1.jpg

x=-0.24184#

y=-0.93969

z=0.24184
../../_images/target_of_gaze_up1.jpg

x=0#

y=-0.95106

z=0.30902
../../_images/target_of_gaze_upper_left1.jpg

x=0.24184#

y=-0.93969

z=0.24184
../../_images/target_of_gaze_right1.jpg

x=-0.5#

y=-0.86603

z=0
../../_images/target_of_gaze_forward1.jpg

x=0#

y=-1

z=0
../../_images/target_of_gaze_left1.jpg

x=0.5#

y=-0.86603

z=0
../../_images/target_of_gaze_lower_right1.jpg

x=-0.35355#

y=-0.86603

z=-0.35355
../../_images/target_of_gaze_down1.jpg

x=0#

y=-0.85717

z=-0.51504
../../_images/target_of_gaze_lower_left1.jpg

x=0.35355#

y=-0.86603

z=-0.35355

Combined with the distance property below, the vector and distance define a single point in space; each eye will be oriented towards that point. Here are two examples:

../../_images/gaze_diagram1.jpg

The gaze vectors for each eye (one pair of examples in blue, one pair of examples in green) will be calculated based on the direction from the eye to the selected point in space.#

distance

64-bit float

The distance property defines the distance, in meters, between the point of origin and the target of the actor’s gaze. This determines how much the actor is crossing or diverging their eyes. In combination with the normalized vector defined in the direction property above, the direction and distance define a single point some distance away from the head, which each eye is focused on.

The point of origin, from which this distance will be measured, is the midpoint between the center of the actor’s left pupil and the center of the actor’s right pupil.

Distance to target of gaze#
../../_images/Eye_Gaze_0.11.png

distance=0.1#
../../_images/Eye_Gaze_11.png

distance=1#
../../_images/Eye_Gaze_151.png

distance=15#