Accessing the ‘backgrounds’ asset catalog#

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

!pip install datagen-tech -q

get()#

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

To get the full set of background assets:

from datagen.api import catalog

catalog.backgrounds.get()

<AssetInstancesList(165)>

To get a specific background asset using its id:

from datagen.api import catalog

catalog.backgrounds.get(id="151c5b4a-3022-49a6-91f0-8749958e7ab7")

Background(

id=’151c5b4a-3022-49a6-91f0-8749958e7ab7’,

transparent=False,

rotation=0.0,

attributes=BackgroundAttributes(

environment=Environment.INDOOR,

time_of_day=TimeOfDay.NA,

strength=1.0

)

)

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

from datagen.api import catalog

catalog.backgrounds.get(limit=4)

<AssetInstancesList(4)>

To get a single background asset using the limit parameter:

from datagen.api import catalog

catalog.backgrounds.get(limit=1)

Background(

id=’00cc4514-850c-45ec-b21b-a3d4281c8a24’,

transparent=False,

rotation=0.0,

attributes=BackgroundAttributes(

environment=Environment.OUTDOOR,

time_of_day=TimeOfDay.NIGHT,

strength=2.0

)

)

To filter the backgrounds using the attributes parameter (see below for the list of valid background attributes):

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

catalog.backgrounds.get(environment=attributes.Environment.INDOOR, time_of_day=attributes.TimeOfDay.MORNING)

<AssetInstancesList(28)>

count()#

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

To count the full set of background assets:

from datagen.api import catalog

catalog.backgrounds.count()

165

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

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

catalog.backgrounds.count(time_of_day=attributes.TimeOfDay.EVENING,environment=attributes.Environment.INDOOR)

Background attributes#

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

class datagen.api.catalog.attributes.BackgroundAttributes(environment: Enum, time_of_day: Enum, strength: Optional[float] = None)

Each background asset contains the following read-only attributes.

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

environment: Enum: The general location of the scene (indoor or outdoor). Uses the Environment enum.

time_of_day: Enum: The general time of day in the scene. Uses the TimeOfDay enum.

Sample usage:
from datagen.api import catalog
from datagen.api.catalog import attributes

catalog.backgrounds.get(time_of_day=attributes.TimeOfDay.EVENING,environment=attributes.Environment.INDOOR)
18
Here is the complete list of valid values for each attribute:

class datagen.api.catalog.attributes.Environment

The list of valid environments.

This enum is valid for use in the following attributes:

BackgroundAttributes.environment

Values:

CROSS_POLARIZED = 'cross_polarized'

INDOOR = 'indoor'

OUTDOOR = 'outdoor'

class datagen.api.catalog.attributes.TimeOfDay

The list of valid times of day.

This enum is valid for use in the following attributes:

BackgroundAttributes.time_of_day

Values:

EVENING = 'evening'

MORNING = 'morning'

NA = 'N/A'

This value is used for the cross-polarized lighting environment.

NIGHT = 'night'

Properties of background objects#

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

string

The id property selects a background from Datagen’s catalog of available backgrounds. The background that you choose provides not only an HDRI background image, but also an appropriate collection of light sources. For example, if your background image includes the sun, we will define a light source at that location and model the effects of direct sunlight on the scene, including reflections and shadows; the same is true for streetlamps, light bulbs, and other types of lighting that may appear in the image.

Tip

Datagen offers a unique background with lighting that simulates cross-polarization photography. To generate a datapoint with this background, set the id to 151c5b4a-3022-49a6-91f0-8749958e7ab7.

Tip

To download a CSV with a complete list of background UUIDs, click here

Backgrounds are categorized…

by time of day

Morning

To download a CSV with a complete list of available of backgrounds with morning lighting, click here

Evening

To download a CSV with a complete list of available of backgrounds with evening lighting, click here

Night

To download a CSV with a complete list of available of backgrounds with nighttime lighting, click here

by location

Indoor

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

Outdoor

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

rotation

64-bit float

The rotation property sets the orientation of the background relative to the actor in the scene.

When you select a background using the SDK background_id field above, you are selecting a full background image and series of light sources that wrap 360° around your actor. The rotation property is useful for ensuring that a specific part of the background is directly behind the actor, or ensuring that the sun casts shadows in a specific direction, or ensuring that light sources are in specific locations relative to the camera lens.

rotation=15.0#

rotation=0.0#

rotation=345.0#

In the above examples, notice how the rotation of the background affects the following:

The angle between the actor and the fence behind her

The different locations of the darker green segment of the tree behind her.

Subtle shifts in the shadows on the actor’s skin, particularly noticeable on the right cheek and left collarbone

The changing location of a light source behind the camera, which can be seen reflected in the actor’s eyes

This code takes a background from the catalog and changes the default rotation:
from datagen.api import catalog

background=catalog.background.get(limit=1)
background.rotation=180.0

transparent

Bool

The transparent property defines whether the background is visible behind the actor or not. If you make the background transparent, all background-associated light sources (such as the sun or streetlamps) will still cast light on the scene, but the actor will be the only visible physical object.

This code takes a background from the catalog and changes the default transparency:
from datagen.api import catalog

background=catalog.background.get(limit=1)
background.transparency=TRUE