The ‘Backgrounds’ asset catalog#

!pip install datagen-tech -q

Accessing the catalog#

class datagen.api.catalog.backgrounds#

The “backgrounds” object gives you access to the catalog of HDRI backgrounds. The Assets provided by this catalog are of type datagen.api.assets.Background.

You can query the backgrounds catalog using these functions:

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

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

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

from datagen.api import catalog

catalog.backgrounds.get()

<AssetInstancesList(165)>

  • Getting a specific background asset by 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

)

)

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

from datagen.api import catalog

catalog.backgrounds.get(limit=4)

<AssetInstancesList(4)>

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

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

)

)

  • Using attributes to filter the catalog:

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

datagen.api.catalog.backgrounds.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 Background attributes below.

Returns:

The number of assets in the catalog matching your query.

Return type:

int

Sample usage

  • Counting the full set of background assets:

from datagen.api import catalog

catalog.backgrounds.count()

165

  • Using attributes to filter the catalog:

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

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

18

Background attributes#

class datagen.api.catalog.attributes.BackgroundAttributes

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:

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:

Values:

EVENING = 'evening'
MORNING = 'morning'
NA = 'N/A'

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

NIGHT = 'night'

Properties of background objects#

These are the editable properties of background objects:

id

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.

../../_images/Rotation_151.png

rotation=15.0#
../../_images/Rotation_01.png

rotation=0.0#
../../_images/Rotation_-151.png

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’s head 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