Core (Frame and Sequence)¶

class starfish.Frame(*, position=0, 0, 0, distance=100, pose=Quaternion(1.0, 0.0, 0.0, 0.0), lighting=Quaternion(1.0, 0.0, 0.0, 0.0), offset=0.5, 0.5, background=Quaternion(1.0, 0.0, 0.0, 0.0))¶

Represents a single picture of an object with certain parameters.

There are 6 parameters that independently define a picture:

Object position: the absolute 3D position of the object in the global coordinate system (i.e. where it is in the scene).
Camera distance: the distance of the camera from the object.
Object pose: the pose of the object relative to the camera (i.e. how it will appear to be oriented in the picture).
Lighting: the angle from which the sun’s rays will hit the object in the picture (e.g. from above, from the right, from behind the camera, etc.).
Object offset: the 2D translational offset of the object from the center of the picture frame.
Background/camera orientation: the orientation of the camera and object relative to the global coordinate system. This affects only what part of the scene appears in the background directly behind the object.

A note on coordinate systems: the representations for pose and translation were carefully chosen to match those of OpenCV rather than using Blender’s default coordinate system. This means that OpenCV camera projection functions such as projectPoints and solvePnP should produce correct results when pose and translation are treated as the rvec and tvec, respectively.

__init__(*, position=0, 0, 0, distance=100, pose=Quaternion(1.0, 0.0, 0.0, 0.0), lighting=Quaternion(1.0, 0.0, 0.0, 0.0), offset=0.5, 0.5, background=Quaternion(1.0, 0.0, 0.0, 0.0))¶

Initializes a picture with all of the parameters it needs.

A type of “rotation” means a mathutils.Quaternion object or any object with a to_quaternion() method (which includes mathutils.Euler, mathutils.Matrix, and starfish.rotations.Spherical).

Parameters

position – (seq, len 3): the (x, y, z) absolute position of the object in the scene’s global coordinate system (default: (0, 0, 0))
distance – (float or int): the distance of the camera from the object in blender units (default: 100)
pose – (rotation): the orientation of the object relative to the camera’s coordinate system (default: the identity quaternion (aka zero rotation), which corresponds to the camera looking directly in the object’s +Z direction with the object’s +X direction pointing to the right and +Y pointing down)
lighting – (rotation): the angle of the sun’s lighting relative to the camera’s coordinate system ( default: the identity quaternion (aka zero rotation), which corresponds to the light coming from directly behind the camera)
offset – (seq of float, len 2): the (vertical, horizontal) translational offset of the object from the center of the picture frame. Expressed as a fraction of the distance from edge to edge: e.g., for horizontal offset, 0.0 is the left edge, 0.5 is the center, and 1.0 is the right edge. Same for vertical, but 0.0 is the top edge and 1.0 is the bottom. (default: (0.5, 0.5))
background – (rotation): Imagine a ray starting at the camera and passing through the object. This parameter determines the orientation of this ray in the global coordinate system. For example, if you have a world background image that encircles your entire scene, two degrees of freedom of this parameter will determine the point in the background image that will appear directly behind the object, and the third degree of freedom will determine the rotation of this background image (i.e. which way is ‘up’). (default: the identity quaternion (aka zero rotation), which corresponds to the camera->object ray pointing directly in the -Z direction with the +X direction pointing to the right and +Y pointing up)

dumps()¶: Converts all of the frame’s attributes to a JSON object. By default, this will be the 6 frame parameters, plus translation if setup has already been called. Any additional metadata can be added by just setting it as an attribute: e.g. frame.sequence_name = '20k_square_earth_background'; metadata = frame.dumps()

setup(scene, obj, camera, sun)¶

Sets up a camera, object, and sun into the picture-taking position. Also computes and stores the translation vector of the object.

Parameters

scene – (BlendDataObject): the scene to use for aspect ratio calculations. Note that this should be the scene that you intend to perform the final render in, not necessarily the one that your objects exist in. If you render in a scene that has an output resolution with a different aspect ratio than the output resolution of this scene, then the offset of the object may be incorrect.
obj – (BlendDataObject): the object that will be the subject of the picture
camera – (BlendDataObject): the camera to take the picture with
sun – (BlendDataObject): the sun lamp that is providing the lighting

translation = None¶: The object’s position relative to the camera represented by a single translation vector (in Blender units). This value isn’t computed until setup time, and will be None beforehand. If you need this translation vector as part of your metadata, make sure to call setup first before calling dumps.

class starfish.Sequence(frames)¶

Represents a sequence of frames.

This class acts exactly like a list of starfish.Frame objects, with a few utility methods tacked on.

Most of the power of this class comes from the classmethod constructors, which can be used to create different types of sequences in a more convenient, expressive way.

The bake method is useful for previewing sequences in Blender while they are being tweaked and configured, in order to get an idea of what they will look like before rendering. However, it is not recommended to use bake at render time. Instead, the sequence object can be iterated over frame-by-frame, like so:

for frame in sequence:
    frame.setup(...)
    bpy.ops.render.render(...)

__init__(frames)¶: Initializes a sequence from a list of frames.

bake(scene, obj, camera, sun, num=None)¶

Creates keyframes representing this sequence, so that it can be played as a preview animation. Keyframes will be adjacent to each other, so no interpolation will be done. This is just a means to get an idea of what frames are in the sequence. If len(frames) is greater than num, only every (len(frames) / num) frames will be displayed.

This should not be called with large values of num (>5000), as it is quite slow and may crash Blender.

Parameters

scene – (BlendDataObject): the scene to set up the animation in
obj – (BlendDataObject): the object that will be the subject of the picture
camera – (BlendDataObject): the camera to take the picture with
sun – (BlendDataObject): the sun lamp that is providing the lighting
num – (int): The number of keyframes to generate. Defaults to min(100, len(frames))

Returns

A Sequence object.

classmethod exhaustive(**kwargs)¶

Creates a sequence that includes every possible combination of the parameters given.

The arguments to this constructor are the same as those to the Frame constructor, except instead of a single value, each argument may also be a list of values. For example, while position is normally an iterable of length 3 representing a 3D vector, it could instead be a list of 3D vectors (i.e. an array of shape (n, 3)).

This constructor then takes the lists of values for each parameter and generates frames out of their cartesian product. For example, if 10 distances, 10 poses, and 10 offsets are provided, the generated sequence will be 10*10*10 = 10,000 frames long, including every possible combination of given distances, poses, and offsets.

Returns: A Sequence object.

classmethod interpolated(waypoints, counts)¶

Creates a sequence interpolated from a list of waypoints.

Parameters

waypoints – (seq): A starfish.Sequence object (or just a list of starfish.Frame objects) representing the waypoints to interpolate between. (tip: use the starfish.Sequence.standard constructor to create this.)
counts – (int or seq): The number of frames to generate between each pair of waypoints. There will be counts[i] frames in between waypoints[i] (inclusive) and waypoints[i+1] (exclusive). The total number of frames in the sequence will be sum(counts) + 1. The length of counts should be 1 less than the length of waypoints. (If count is an integer, then there should only be 2 waypoints.)

Returns

A Sequence object.

classmethod standard(**kwargs)¶

Creates a sequence from parameters that are lists.

The arguments to this constructor are the same as those to the Frame constructor, except instead of a single value, each argument may also be a list of values. For example, while position is normally an iterable of length 3 representing a 3D vector, it could instead be a list of 3D vectors (i.e. an array of shape (n, 3)).

This constructor then generates a list of frames where the parameters for each frame come from these lists, zipped together.

Each list of parameters must be either the same length as all the others, or be list with a single value. If a single value is provided for a parameter, then that value is broadcasted across all the frames, i.e. every frame gets that value for that parameter. (The same thing happens if a parameter is omitted: every frame gets the default value for that parameter).

For example: Sequence(distance=[100, 200, 300]) will generate a sequence of 3 frames where the distances are 100, 200, and 300, while all other parameters are the default. Sequence(position=[(1, 1, 1)], distance=[100, 200, 300]) will generate a sequence of 3 frames where the distances are 100, 200, and 300, while the positions are (1, 1, 1) and all other parameters are the default.

Returns: A Sequence object.