Explore platform

Walkthrough: Generate a random datapoint

Make these samples interactive

Note

If this is your first visit to this page, it may take up to 5 minutes to activate the kernel and install the necessary packages.

!pip install datagen-tech -q

Step 1: Import relevant modules

Important

If you are pasting this code into your Python environment, make sure to install the datagen-tech python package first.

We will begin by importing modules:

import datagen.api as datapoint_api
from datagen.api import catalog, assets
from datagen.api.catalog import attributes
from datagen.api.catalog.attributes import Gender, Ethnicity, Age
from pprint import pprint
import random
import numpy as np

Step 2: Set the scene

Let us now set the scene by selecting a random background and rotating it by a random amount.

The background defines what can be seen behind the actor as well as the type and location of the scene’s lighting: house lights, streetlamps, the sun, etc.

backgrounds = catalog.backgrounds.get()
background = random.choice(backgrounds)
background.rotation = random.uniform(0, 360)
print("The selected background:")
pprint(vars(background))

Step 3: Set the Camera

Next we will position the camera and define its intrinsic parameters.

We want the camera to be close enough to clearly see the actor’s face, but far enough that the face fits comfortably within the frame.

Tip

Use this visualization tool to experiment with camera placement and settings.

camera = assets.Camera(
  name='camera',
  intrinsic_params=assets.IntrinsicParams(
    projection=assets.Projection.PERSPECTIVE,
    resolution_width=1024,
    resolution_height=1024,
    fov_horizontal=10,
    fov_vertical=10,
    wavelength=assets.Wavelength.VISIBLE
  ),
  extrinsic_params=assets.ExtrinsicParams(
    location=assets.Point(x=0., y=-1.6, z=0.12),
    rotation=assets.Rotation(yaw=0.0, pitch=0.0, roll=0.0)
  )
)

Step 4: Build the Actor

Now we will put together our actor. First, we will choose our actor’s identity based on a randomly selected gender, age, and ethnicity:

gender = random.choice([Gender.MALE, Gender.FEMALE])
age = random.choice([Age.YOUNG, Age.ADULT, Age.OLD])
ethnicity = random.choice([Ethnicity.AFRICAN, Ethnicity.NORTH_EUROPEAN, Ethnicity.MEDITERRANEAN, Ethnicity.HISPANIC, Ethnicity.SOUTH_ASIAN, Ethnicity.SOUTHEAST_ASIAN])
human = random.choice(catalog.humans.get(gender=gender, age=age, ethnicity=ethnicity))
# At first our actor will not be wearing any accessories, so we will set these to None. We will optionally add accessories later.
glasses = None
mask = None
print("The selected human:")
pprint(vars(human))

(Optional step: Change the actor's hair, eyes, and eyebrows)

The actor’s identity included a default hairstyle and color, eyebrow style and color, and eye color. If we like, we can change those defaults.

This code block does the following:

• Gives the actor a random hairstyle and eyebrow style appropriate to the actor’s gender, age, and ethnicity

• Applies a random hair color to both hair and eyebrows

• Gives the actor a random pair of eyes.

human.head.hair = random.choice(catalog.hair.get(age_group_match=human.attributes.age, gender_match=human.attributes.gender, ethnicity_match=human.attributes.ethnicity))
human.head.eyebrows = random.choice(catalog.eyebrows.get(gender_match=human.attributes.gender))
hair_color = assets.HairColor(melanin=random.random(), redness=random.random(), whiteness = random.random(), roughness=random.uniform(0.15, 0.5), index_of_refraction=random.uniform(1.4, 1.65))
human.head.hair.color_settings = hair_color
human.head.eyebrows.color_settings = hair_color
human.head.eyes = random.choice(catalog.eyes.get())
print("The selected hair:")
pprint(vars(human.head.hair))
print("\n" + "The selected eyebrows:")
pprint(vars(human.head.eyebrows))
print("\n" + "The selected eyes:")
pprint(vars(human.head.eyes))

Next we will choose the target of the actor’s gaze and how much their eyelids are closed:

# The gaze should be mostly in the -y direction (forward), with variance in the x and z dimensions.
gaze_direction = np.array([random.uniform(-0.7, 0.7), -1, random.uniform(-0.577, 0.577)])
# The gaze distance will be up to 1 kilometer away, weighted slightly towards closer targets
human.head.eyes.target_of_gaze = assets.Gaze(distance=10**(random.uniform(0,3)), direction=assets.Vector(x=gaze_direction[0], y=gaze_direction[1], z=gaze_direction[2]))
human.head.eyes.eyelid_closure = random.uniform(0, 1)
print("The selected eyes:")
pprint(vars(human.head.eyes))

(Optional step: Give the actor an accessory or facial hair)

This section adds optional extras to our actor: glasses, a mask or facial hair.

To give the actor facial hair:

human.head.facial_hair = random.choice(catalog.beards.get())
human.head.facial_hair.color_settings = human.head.hair.color_settings
print("\n" + "The selected facial hair:")
pprint(vars(human.head.facial_hair))

To give the actor a random pair of glasses:

glasses = random.choice(catalog.glasses.get(gender=human.attributes.gender))
glasses.frame_color = random.choice(list(assets.FrameColor))
glasses.frame_metalness = random.random()
glasses.lens_color = random.choice(list(assets.LensColor))
glasses.lens_reflectivity = random.random()
glasses.lens_transparency = random.random()
glasses.position = random.choice(list(assets.GlassesPosition))
print("The selected glasses:")
pprint(vars(glasses))

To give the actor a mask:

Important

Currently, you cannot give your actor a mask if they also have glasses or facial hair.

mask = random.choice(catalog.masks.get(gender=human.attributes.gender))
mask.color = random.choice(list(assets.MaskColor))
mask.texture = random.choice(list(assets.MaskTexture))
mask.position = random.choice(list(assets.MaskPosition))
mask.roughness = random.random()
print("The selected mask:")
pprint(vars(mask))

Finally, we will bring the actor to life, by choosing the facial expression and the rotation of the head:

human.head.rotation = assets.HeadRotation(yaw=random.uniform(-50, 50), pitch=random.uniform(-20, 20), roll=random.uniform(-10, 10))
human.head.expression = assets.Expression(name=random.choice(list(assets.ExpressionName)), intensity=random.uniform(0.1, 1))
print("The selected head rotation:")
pprint(vars(human.head.rotation))
print("\n" + "The selected facial expression:")
pprint(vars(human.head.expression))

Step 5: Package the data request

Now that every aspect of our scene has been defined, we can package it and save it to a JSON file.

DST_JSON_PATH = "data_request.json"
kwargs = {'human': human, 'camera': camera, 'background': background, 'glasses': glasses, 'mask': mask}
datapoints = []
datapoints.append(datapoint_api.create_datapoint(**kwargs))
datapoint_api.dump(assets.DataRequest(datapoints=datapoints),path=DST_JSON_PATH)

The above code creates a file called data_request.json in your working directory.

Step 6: (Site only) Download the JSON

If you have been running the code using the interactive kernel in this page, you need to take one last step to turn the JSON file into a downloadable link.

from IPython.display import HTML
import os, base64

def make_download_link(filepath):
  filename = os.path.basename(filepath)
  with open(filepath, "rb") as f:
    data = base64.b64encode(f.read()).decode()
    return HTML(f'<h4>Click here to download <a href="data:application/binary;base64,{data}" download={filename}>{filename}</a>.</h4>')

filepath = "data_request.json"
make_download_link(filepath)

Step 7: Generate your data

You now have a data request in the form of a JSON file.

Follow these instructions to upload the file to our platform. It will start generating your data immediately.