PuppetSpec#

Import

from scenet import PuppetSpec

Defined in

scenet.assets.contract (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

class scenet.assets.contract.PuppetSpec[source]#

Bases: Strict

The complete geometric contract for one character.

Everything the solver may know about a character, and nothing it draws: proportions in head units, a skeleton, named anchors, the face, its poses and expressions. The asset contract reference describes the file format, field by field.

Example

>>> from scenet import PuppetSpec, default_library
>>> alice = default_library().get("alice")
>>> isinstance(alice, PuppetSpec), alice.name, "mouth" in alice.anchors
(True, 'alice', True)

See also

load_puppet, to read one from a file. Landmark, the crop lines it declares.

name: str#

The name a cast member’s reference uses.

units_per_head: float#

How many of the puppet’s own units one head height is.

landmarks: dict[Landmark, float]#

Each vertical body landmark, as a distance down from the top of the head, in head units: the crop lines a shot type names.

joints: dict[str, JointSpec]#

The skeleton, by joint name.

root: str#

The joint every other one hangs from.

root_landmark: Landmark#

The landmark the root joint sits at.

parts: tuple[BonePart | BlobPart, ...]#

The shapes the body is drawn from, back to front.

anchors: dict[str, AnchorSpec]#

Named attachment points, such as mouth and eyes, each on a joint.

face: FaceSpec#

Where the face is, and what is drawn in it.

gaze: GazeSpec#

Where the puppet’s line of sight starts.

poses: dict[str, dict[str, float]]#

Named poses, each a set of joint angles.

expressions: dict[str, ExpressionSpec]#

Named expressions, each a state of brow, eyes and mouth.

property total_height: float#

Head top to feet, in the puppet’s own native units.

property heads_tall: float#

Height in head-heights – the classic figure-drawing proportion.

The unit the camera works in. Two puppets of different heads_tall framed at the same shot produce figures of visibly different build, which is the whole reason the shipped library has a 7.5-head character and a taller one.

pose_angles(pose)[source]#

Look up the joint angles for a named pose.

Parameters:

pose (str) – Name of a pose this puppet declares.

Return type:

dict[str, float]

Returns:

Joint name to angle in degrees. Joints absent from the mapping keep their rest angle.

Raises:

UnknownPoseError – This puppet has no pose by that name. The message lists the ones it does have. Also a KeyError, so except KeyError keeps working.

expression_states(expression)[source]#

Look up the feature states for a named expression.

The counterpart of pose_angles, and deliberately identical in shape down to the error: an expression is selected by name exactly as a pose is.

Parameters:

expression (str) – Name of an expression this puppet declares.

Return type:

ExpressionSpec

Returns:

The states its features take.

Raises:

UnknownExpressionError – This puppet has no expression by that name. The message lists the ones it does have. Also a KeyError, so except KeyError keeps working.

Example

>>> from scenet import default_library
>>> alice = default_library().get("alice")
>>> alice.expression_states("angry").mouth.value
'frown'