Augmentations¶

Randomize objects, materials and any other value in the scene, in place.

Compose applies a list of augmentations to every object it is called with. Each augmentation takes p, the probability that it runs, drawn per object. After a call, applied says whether it ran and actual (or actual_x/y/z) holds the values it set. Save the scene with State first, and restore it after every datapoint.

Number, Vector, Boolean and Menu change any value by its data path. A path starting with bpy. is absolute: right click a value in Blender > Copy Full Data Path. Any other path is relative to the augmented object, e.g. data.energy. Geometry nodes inputs moved in Blender 5, so their path depends on the version: modifiers["GeometryNodes"]["Socket_2"] in 4.x, modifiers["GeometryNodes"].properties.inputs.Socket_2.value in 5.x.

Compose ¶

Compose(
    augmentations: list[Callable[[Object], Any]],
    p: float = 1.0,
)

Applies a list of augmentations to every object it is called with, in place.

Each augmentation runs once per object, in list order. Save the scene with State before augmenting, so it can be restored.

Parameters:

augmentations (list[Callable[[Object], Any]]) –

augmentations to apply, each a callable taking one object.
p (float, default: 1.0 ) –

probability of applying the whole list, drawn once per call.

Attributes:

applied (bool | None) –

whether the last call applied the augmentations.

Example

objects_aug = augmentations.Compose([
    augmentations.Translation(x=0.5, y=0.5),
    augmentations.Rotation(z=180),
])
objects_aug([car_1, car_2])

Augmentation ¶

Augmentation(p: float = 1.0)

Base class of the augmentations.

It runs with probability p, drawn on every call, so once per object in a Compose. A skipped augmentation leaves the object unchanged. Boolean is the exception, it sets False when skipped.

Subclasses implement apply(obj) and store what they sampled in actual.

Parameters:

p (float, default: 1.0 ) –

probability of applying the augmentation, 0-1.

Attributes:

applied (bool | None) –

whether the last call applied it.
actual (Any) –

the values set by the last call, None when it was skipped.

Translation ¶

Translation(
    x: Offset = 0,
    y: Offset = 0,
    z: Offset = 0,
    p: float = 1.0,
)

Moves the object by a random offset per axis, in Blender units.

Each axis is a number v, sampled from (-v, v), or a pair (low, high). The offset is added to the location.

Parameters:

x (Offset, default: 0 ) –

offset on X in Blender units.
y (Offset, default: 0 ) –

offset on Y in Blender units.
z (Offset, default: 0 ) –

offset on Z in Blender units.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Example

augmentations.Translation(x=0.5, y=0.5, z=(0, 1))

Rotation ¶

Rotation(
    x: Offset = 0,
    y: Offset = 0,
    z: Offset = 0,
    p: float = 1.0,
)

Rotates the object by a random angle per axis, in degrees.

Each axis is a number v, sampled from (-v, v), or a pair (low, high). The angle is added to the rotation, in euler, quaternion and axis-angle modes.

Parameters:

x (Offset, default: 0 ) –

angle around X in degrees.
y (Offset, default: 0 ) –

angle around Y in degrees.
z (Offset, default: 0 ) –

angle around Z in degrees.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Example

augmentations.Rotation(z=180)          # any heading

Scale ¶

Scale(
    x: Offset = 0,
    y: Offset = 0,
    z: Offset = 0,
    p: float = 1.0,
)

Scales the object by a random percentage per axis.

Each axis is a number v, sampled from (-v, v), or a pair (low, high), in percent: the scale is multiplied by 1 + sample / 100.

Parameters:

x (Offset, default: 0 ) –

change of the X scale in percent.
y (Offset, default: 0 ) –

change of the Y scale in percent.
z (Offset, default: 0 ) –

change of the Z scale in percent.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Example

augmentations.Scale(x=10, y=10, z=10, p=0.5)   # ±10 %, in half of the datapoints

LookAt ¶

LookAt(
    target: Target,
    distance: Optional[RangeOrValue] = None,
    elevation: Optional[RangeOrValue] = None,
    azimuth: Optional[RangeOrValue] = None,
    roll: Optional[RangeOrValue] = None,
    focal_length: Optional[RangeOrValue] = None,
    p: float = 1.0,
)

Moves a camera (or a light, or any object) on a sphere around a target and points it at the target, upright.

The target stays in the center of the camera view. It sets matrix_world, so parented cameras work too. Each parameter is a (min, max) range, an exact number, or None to keep the current value.

Parameters:

target (Target) –

an object, a list of objects (the center of their bounding boxes), or a point (x, y, z).
distance (Optional[RangeOrValue], default: None ) –

distance from the target in Blender units.
elevation (Optional[RangeOrValue], default: None ) –

angle above the target's horizontal plane in degrees. Avoid exactly 90 / -90.
azimuth (Optional[RangeOrValue], default: None ) –

angle around the world Z axis in degrees, 0 = +X.
roll (Optional[RangeOrValue], default: None ) –

rotation around the camera's view axis in degrees. None = upright.
focal_length (Optional[RangeOrValue], default: None ) –

camera lens in mm, cameras only.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Attributes:

actual (dict | None) –

the distance, elevation, azimuth, roll and focal length set by the last call.

Note

Pass the camera to State, it restores the transform and the lens.

Example

camera_aug = augmentations.Compose([
    augmentations.LookAt([car_1, car_2], distance=(6, 12), elevation=(10, 45),
                         azimuth=(0, 360), roll=(-5, 5)),
])
camera_aug([bpy.context.scene.camera])

FocalLength ¶

FocalLength(
    focal_length: RangeOrValue,
    target: Optional[Target] = None,
    keep_size: bool = False,
    p: float = 1.0,
)

Sets a random camera lens, optionally as a dolly zoom.

With keep_size, the camera also moves along the line to the target by the same ratio as the lens, so the target keeps its size in the image while the perspective changes. That is exact for parts at the target's depth when the target is in the center of the view (e.g. after LookAt); an off-center target also moves in the image. Perspective cameras only.

Parameters:

focal_length (RangeOrValue) –

lens in mm, a (min, max) range or an exact number.
target (Optional[Target], default: None ) –

an object, a list of objects (the center of their bounding boxes), or a point (x, y, z). Needed for keep_size.
keep_size (bool, default: False ) –

move the camera so the target keeps its size in the image.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Raises:

ValueError –

keep_size without a target.

Example

augmentations.FocalLength((24, 85), target=[car_1, car_2], keep_size=True)

DepthOfField ¶

DepthOfField(
    target: Optional[Target] = None,
    f_stop: Optional[RangeOrValue] = None,
    p: float = 1.0,
)

Turns on depth of field, focused on a target, with a random f-stop.

Focus is measured along the view axis from where the camera is when this runs, so put it after LookAt / FocalLength in a Compose.

Parameters:

target (Optional[Target], default: None ) –

an object, a list of objects (the center of their bounding boxes), or a point (x, y, z) to focus on. None keeps the current focus.
f_stop (Optional[RangeOrValue], default: None ) –

aperture f-stop, a (min, max) range or an exact number, lower gives more blur. None keeps the current one.
p (float, default: 1.0 ) –

probability of applying the augmentation. When skipped, the depth of field settings are left unchanged, so with depth of field off in the scene only some images are blurred.

Example

augmentations.DepthOfField(car_1, f_stop=(1.4, 5.6), p=0.5)

Material ¶

Material(
    material_id: str,
    hue: Optional[tuple[float, float]] = None,
    saturation: Optional[tuple[float, float]] = None,
    value: Optional[tuple[float, float]] = None,
    roughness: Optional[tuple[float, float]] = None,
    metallic: Optional[tuple[float, float]] = None,
    p: float = 1.0,
)

Sets random Principled BSDF base color, roughness and metallic values.

Each parameter is an absolute (min, max) range, 0-1, and None leaves the value unchanged. The base color is set through hue, saturation and value. The sockets must not be connected to other nodes.

It changes the material, so every object using it is affected.

Parameters:

material_id (str) –

name of the material.
hue (Optional[tuple[float, float]], default: None ) –

range of the base color hue.
saturation (Optional[tuple[float, float]], default: None ) –

range of the base color saturation.
value (Optional[tuple[float, float]], default: None ) –

range of the base color value (brightness).
roughness (Optional[tuple[float, float]], default: None ) –

range of the roughness.
metallic (Optional[tuple[float, float]], default: None ) –

range of the metallic.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Example

augmentations.Material("CarPaint", hue=(0, 1), saturation=(0.5, 1), roughness=(0.1, 0.6))

Number ¶

Number(
    data_path: str,
    value_range: tuple[float, float],
    p: float = 1.0,
)

Sets any int or float value, given by its data path, to a random value.

For shader node inputs, geometry nodes inputs, shape keys, light settings and so on. Ints are rounded.

Parameters:

data_path (str) –

path to the value, absolute (starting with bpy.) or relative to the object. Use [index] for one vector component, e.g. 'location[2]'.
value_range (tuple[float, float]) –

(min, max) range of the new value.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Use it inside a Compose

With an absolute path (starting with bpy.) it doesn't use the object passed by Compose, but it still belongs in one: it runs with the rest of the list, and State(fields=compose.augmentations) restores it. It runs once per object the Compose is called with, and the last value set is kept.

Example

augmentations.Number("data.energy", value_range=(600, 1400))
augmentations.Number('data.shape_keys.key_blocks["Smile"].value', value_range=(0, 1))

Vector ¶

Vector(
    data_path: str,
    value_range: tuple[Bound, Bound],
    p: float = 1.0,
)

Sets any vector value, given by its data path, to random values per component.

For locations, colors, vector node inputs and so on. Each bound of value_range is a number for all components, or a sequence with one value per component, where None keeps that component. Int components are rounded.

Parameters:

data_path (str) –

path to the value, absolute (starting with bpy.) or relative to the object.
value_range (tuple[Bound, Bound]) –

(min, max) bounds of the new values.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Use it inside a Compose

With an absolute path (starting with bpy.) it doesn't use the object passed by Compose, but it still belongs in one: it runs with the rest of the list, and State(fields=compose.augmentations) restores it. It runs once per object the Compose is called with, and the last value set is kept.

Example

augmentations.Vector("data.color", value_range=(0.8, 1.0))
# a random RGB color that keeps alpha
augmentations.Vector(
    'bpy.data.materials["Mat"].node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value',
    value_range=((0, 0, 0, None), (1, 1, 1, None)),
)

Boolean ¶

Boolean(data_path: str, p: float = 0.5)

Sets any boolean value, given by its data path, to True with probability p, otherwise to False.

For geometry nodes switches, object visibility, modifier toggles and so on.

Parameters:

data_path (str) –

path to the value, absolute (starting with bpy.) or relative to the object.
p (float, default: 0.5 ) –

probability of True.

Use it inside a Compose

With an absolute path (starting with bpy.) it doesn't use the object passed by Compose, but it still belongs in one: it runs with the rest of the list, and State(fields=compose.augmentations) restores it.

Example

augmentations.Boolean("data.use_shadow", p=0.8)

Menu ¶

Menu(
    data_path: str,
    options: Optional[Sequence[Any]] = None,
    weights: Optional[Sequence[float]] = None,
    p: float = 1.0,
)

Sets any menu (enum) value, given by its data path, to a random option.

For geometry nodes menu inputs, node settings like the Principled BSDF distribution, the light type and so on.

Parameters:

data_path (str) –

path to the value, absolute (starting with bpy.) or relative to the object.
options (Optional[Sequence[Any]], default: None ) –

options to choose from. None = all options of the menu; required when Blender doesn't list them, e.g. for menu sockets not on a Menu Switch node.
weights (Optional[Sequence[float]], default: None ) –

relative probability of each option. None = equal.
p (float, default: 1.0 ) –

probability of applying the augmentation.

Raises:

ValueError –

the number of weights and options differ.

Use it inside a Compose

With an absolute path (starting with bpy.) it doesn't use the object passed by Compose, but it still belongs in one: it runs with the rest of the list, and State(fields=compose.augmentations) restores it.

Example

augmentations.Menu("data.type", options=["POINT", "SPOT", "AREA"], weights=[2, 1, 1])