API

The API is exposed as a Python module, pianoray.

This page contains documentation for each object. See Animation for information on how to use the API to animate.

Property Group

class pianoray.PropertyGroup

Group of properties. Define a subclass to create your PropertyGroup. Define properties by creating annotations with :. Don’t override any methods, as instancing a PropertyGroup subclass requires the methods.

class MyProps(PropertyGroup):
    temperature: FloatProp(
        name="Temperature",
        desc="Temperature to cook the food at.",
        default=-10,
    )

    food: StringProp(
        name="Food",
        desc="The food to cook.",
        default="Java",
    )

You can set and get properties.

pgroup.temperature                # Returns the property object.
pgroup.temperature.animate(...)   # Animate. See Property docs.
pgroup.temperature = -273         # Calls pgroup.temperature.set_value()

Properties

class pianoray.Property(name: str = '', desc: str = '', animatable: bool = True, required: bool = True, mods: Sequence[Modifier] = (), default: Optional[Any] = None)

Property base class.

animate(*args) → None

Insert a keyframe.

A few syntaxes are available:

prop.animate(Keyframe(frame, value, interp))
prop.animate(Keyframe(frame, value, interp), Keyframe(frame, value, interp))
prop.animate(frame, value, interp)
prop.animate((frame, value, interp))
prop.animate((frame, value, interp), (frame2, value2, interp2), ...)

They all do the same thing. However, please do not mix syntaxes in one call (don’t pass a keyframe object and then an unpacked tuple).

set_value(value: Any): Checks validity and sets self._value

value(frame: int, use_mods: bool = True, default: Optional[Accessor] = None) → Any: Returns value at frame. Uses keyframe interpolations. Converts to type. Applies modifiers.

verify(value: Any) → bool

Check whether the value can be assigned to this prop, e.g. min and max.

Default implementation returns True. Override in subclass, if applicable.

class pianoray.BoolProp(name: str = '', desc: str = '', animatable: bool = True, required: bool = True, mods: Sequence[Modifier] = (), default: Optional[Any] = None)

Boolean.

type: alias of bool

class pianoray.IntProp(min: Optional[int] = None, max: Optional[int] = None, coords: bool = False, **kwargs)

Integer. Min and max inclusive. Coords: Whether this quantity is in coords.

type: alias of int

verify(value: int) → bool: Checks min and max.

class pianoray.FloatProp(min: Optional[float] = None, max: Optional[float] = None, coords: bool = False, **kwargs)

Float. Min and max inclusive. Coords: Whether this quantity is in coords.

type: alias of float

verify(value: float) → bool: Checks min and max.

class pianoray.StrProp(min_len: Optional[int] = None, max_len: Optional[int] = None, **kwargs)

String. Min and max inclusive.

type: alias of str

verify(value: str) → bool: Checks length min and max.

class pianoray.PathProp(isfile: bool = False, isdir: bool = False, **kwargs)

Path property. Can verify if a path exists.

verify(value: str) → bool: Checks path isfile and isdir, if respective attributes are True.

class pianoray.ArrayProp(shape: Optional[Tuple[int]] = None, **kwargs)

Numpy array property.

verify(value: ndarray) → bool: Checks shape.

class pianoray.RGBProp(**kwargs): RGB color property.

Scene

class pianoray.Scene

Group of PropertyGroups.

Create a subclass with your pgroups. Set the dictionary _pgroups to mapping of id to property group instance.

class MyScene(Scene):
    _pgroups = {
        "food": FoodProps(),
    }

Create a subclass of a scene, and override the setup method to do animation. Scene.setup is called at initialize time.

# We are extending "MyScene", described above.
class MyOtherScene(MyScene):
    def setup(self):
        self.food.temperature = 100

property default: Accessor: Equivalent to self.values(0). Usually used to get non animatable props.

setup() → None: Do any animation or property value setting here.

values(frame: int, use_mods: bool = True) → Accessor: Returns Accesor object of all pgroup values at frame.