Characters#
What a puppet must declare, and how a declared puppet becomes a posed figure in panel coordinates. The solver sees only this contract, never artwork.
scenet.assets.contract#
What a character puppet must declare.
The solver never sees artwork – only this contract. That is what keeps rendering swappable: the same panel lays out identically whether it is drawn as wireframe boxes, as vector puppets, or eventually as real artwork.
A character is a skeleton plus parametric limbs rather than a picture, so a pose is a set of joint angles and not a drawing. That avoids the combinatorial explosion of one image per pose per expression per facing direction.
- scenet.assets.contract.DEFAULT_POSE = 'standing_neutral'#
The pose a cast member gets when it does not ask for one, which every puppet declares.
- scenet.assets.contract.PUPPET_RULE = 'puppet-file'#
The rule every fault in a puppet file a document names is reported under.
- scenet.assets.contract.PUPPET_SUFFIX = '.puppet.yaml'#
What a puppet file’s name ends in. A cast member’s
referencethat ends in it names a file, relative to the document, rather than a shipped puppet.
- class scenet.assets.contract.AnchorSpec[source]#
Bases:
StrictA named point that rides along with a joint.
Anchors are how the solver addresses anatomy without knowing anatomy: the balloon tail terminates at
mouth, and it neither knows nor cares how the head is drawn.
- class scenet.assets.contract.BlobPart[source]#
Bases:
StrictA rounded mass – the head, or a torso – centred on a joint.
- class scenet.assets.contract.BonePart[source]#
Bases:
StrictA limb segment drawn as a capsule between two joints.
- class scenet.assets.contract.BrowState[source]#
Bases:
StrEnumWhat the eyebrows are doing.
angled_inputs the inner ends down, which is the anger brow;angled_outputs them up, which is the sad or frightened one. Inner and outer are resolved against the face centre rather than the screen, so both survive mirroring.- NEUTRAL = 'neutral'#
- RAISED = 'raised'#
- LOWERED = 'lowered'#
- ANGLED_IN = 'angled_in'#
- ANGLED_OUT = 'angled_out'#
- class scenet.assets.contract.ExpressionSpec[source]#
Bases:
StrictOne named expression, as a state per feature.
An expression is to features what a pose is to joints: a record the panel selects by name. A face deforms rather than rotating about bones, which is why this is a set of states and not a set of angles – a nose joint would swing a nose.
Every field defaults, so a
neutralexpression is{}and a happy one is{mouth: smile}. Unknown keys are rejected, somouth: raised– a real state, on the wrong feature – is an error rather than a silently ignored line.- mouth: MouthState#
The mouth’s state.
- class scenet.assets.contract.EyeState[source]#
Bases:
StrEnumHow open the eyes are.
halfis the heavy-lidded eye of boredom, distinct fromnarrowed, which is the squint of anger or suspicion: one is drooping, the other is tightened.- OPEN = 'open'#
- WIDE = 'wide'#
- NARROWED = 'narrowed'#
- HALF = 'half'#
- CLOSED = 'closed'#
- class scenet.assets.contract.FaceSpec[source]#
Bases:
StrictThe region a balloon may never cover, and what is drawn inside it.
A circle rather than a polygon: faces are roughly round, the test is cheap, and the cost of being slightly generous here is a balloon placed a little further away, which is never wrong.
featuresis optional. A puppet that declares none is drawn exactly as it was before faces existed – a head is a filled circle – and a puppet that declares some has those drawn and no others. There is no requirement to declare all of them, because a stylised character genuinely may have no eyebrows.- features: dict[Feature, FeatureSpec]#
What is drawn inside the face, by feature. Empty for a plain round head.
- class scenet.assets.contract.Feature[source]#
Bases:
StrEnumThe points on a face that an expression can move.
Named after the groups of the MPEG-4 FBA facial definition parameters – brow, eye, nose, mouth – rather than its full point set. The standard defines 66 displacements over dozens of points, which is a measurement rather than a notation; the grouping is the part worth reusing, and it lands at about the right size for a drawn face.
docs/reference/asset_contract.mdrecords the mapping to MediaPipe landmark indices, which is what buys convertibility later without importing 478 points into the language now.Two omissions are deliberate. Pupils are derived, not declared – they are offset inside the eye by where the character is looking, so authoring them would be authoring something the compiler already knows. And there is no jaw: the head is a circle that does not deform, so a jaw group would have no geometry to move.
- BROW_L = 'brow_l'#
- BROW_R = 'brow_r'#
- EYE_L = 'eye_l'#
- EYE_R = 'eye_r'#
- NOSE = 'nose'#
- MOUTH = 'mouth'#
- class scenet.assets.contract.FeatureSpec[source]#
Bases:
StrictWhere one facial feature sits, and how big it is.
Structurally an
AnchorSpecwith a size, and resolved through exactly the same forward kinematics – but declared underfacerather than inanchors, deliberately. Anchors are how the solver addresses anatomy: the balloon tail terminates atmouthand the solver never learns how a head is drawn. Features are artwork. Mixing them would put drawing landmarks into the one namespace that is supposed to be free of them.
- class scenet.assets.contract.GazeSpec[source]#
Bases:
StrictWhere a character’s line of sight starts.
The direction is not stored: it is derived at solve time from whom the character is looking at, so a
looking_atrelation is enough and nobody has to compute an angle by hand.
- class scenet.assets.contract.JointSpec[source]#
Bases:
StrictOne joint in the skeleton.
offsetis the rest-pose displacement from the parent joint, in native units. A joint’s pose angle rotates the bone arriving at it and everything below it, which is the formulation that makes posing read naturally: bendingelbow_lswings the upper arm and takes the forearm and hand with it.
- class scenet.assets.contract.MouthState[source]#
Bases:
StrEnumWhat the mouth is doing.
grinis an open smile,smilea closed one, andsmallthe reticent little mouth that does most of the work in a coy face.- NEUTRAL = 'neutral'#
- FLAT = 'flat'#
- SMILE = 'smile'#
- GRIN = 'grin'#
- FROWN = 'frown'#
- OPEN = 'open'#
- SMALL = 'small'#
- exception scenet.assets.contract.PuppetFileError[source]#
Bases:
NamedFileErrorA puppet file a cast member names, there and wrong: located in it.
Its
fileis the path the member’sreferencewrites, relative to the document, and itslocis thatreference.
- class scenet.assets.contract.Strict[source]#
Bases:
BaseModelBase for every puppet model: frozen, and rejecting unknown keys.
A misspelled key in a puppet file that was silently ignored would produce a character that is subtly wrong – an arm the wrong length, an anchor in the wrong place – with nothing to point at. A length of
.infor.nanis refused as well: it is a valid YAML float, and nothing downstream can draw it.
- scenet.assets.contract.is_puppet_file(reference)[source]#
Whether a cast member’s
referencenames a puppet file rather than a shipped puppet.A path is never a name:
aliceis the shipped puppet whatever sits beside the document, andpuppets/alice.puppet.yamlis a file, whatever it calls itself.Example
>>> from scenet.assets.contract import is_puppet_file >>> is_puppet_file("puppets/pip.puppet.yaml"), is_puppet_file("alice") (True, False)
- Return type:
- scenet.assets.contract.library_for(puppets, base, library)[source]#
The puppets a cast is drawn from: a library, and every puppet file the cast names.
Each file is read once, however many members it draws, and filed under the reference that names it, so everything downstream looks a member’s puppet up by its
referenceas it always has. Only what the cast names is read: a file beside the document that nobody casts changes nothing.- Parameters:
- Return type:
- Returns:
libraryitself when the cast names no file, or a new one with them added.- Raises:
PanelSyntaxError – Rule
puppet-file, for the first member whose file cannot be read, asload_puppet_filereports it.
- scenet.assets.contract.load_puppet_file(declared, base, *, loc=())[source]#
Read the puppet file a cast member names, beside the document or among the files sent.
Read as a document’s font and picture are: relative to the folder it is in, with
/between folders, never absolute – so a document and its puppets travel together, and the command line, the playground and the MCP server all read it the same way.- Parameters:
- Return type:
- Returns:
The validated puppet.
- Raises:
PanelSyntaxError – Rule
puppet-file, for a path that cannot be read, located where the document names it.PuppetFileError – The same rule, for a file that is there and is not a puppet, located in it too: not text, not YAML, a key written twice or unknown, or a puppet the validators refuse – at the key they find wrong.
Example
>>> from scenet.assets.contract import DEFAULT_LIBRARY_PATH, load_puppet_file >>> bob = (DEFAULT_LIBRARY_PATH / "bob.puppet.yaml").read_bytes() >>> load_puppet_file("puppets/mine.puppet.yaml", {"puppets/mine.puppet.yaml": bob}).name 'bob'
scenet.assets.kinematics#
Forward kinematics: skeleton plus pose, resolved into concrete geometry.
Everything downstream – camera scaling, actor placement, balloon avoidance, tail routing, rendering – consumes the output of this module and nothing else from the asset layer. That boundary is the whole point: swap the puppet for hand-drawn artwork exposing the same anchors and hulls, and layout is unchanged.
- class scenet.assets.kinematics.ResolvedCapsule[source]#
Bases:
objectA limb segment: a thick line with rounded ends.
- __init__(start, end, width)#
- class scenet.assets.kinematics.ResolvedBlob[source]#
Bases:
objectA rounded mass – head, hand, foot – after posing.
- __init__(centre, radius)#
- class scenet.assets.kinematics.ResolvedFeature[source]#
Bases:
objectOne facial feature point after posing.
- size#
Its extent in panel units, already scaled. What the number measures depends on the feature – see
FeatureSpec.- Type:
- __init__(centre, size)#
- class scenet.assets.kinematics.ResolvedPuppet[source]#
Bases:
objectA posed figure in panel coordinates.
Produced once per actor per compile, then treated as read-only by every consumer.
- __init__(name, pose, facing_right, scale, joints, anchors, landmarks, capsules, blobs, face, gaze, hull, expression='neutral', features=<factory>)#
- scenet.assets.kinematics.solve_pose(spec, pose)[source]#
Resolve joint positions in the puppet’s own units, root at the origin.
Returns the joint positions and the accumulated world angle at each joint, the latter being what anchors and gaze need in order to ride along with rotation.
- scenet.assets.kinematics.resolve(spec, *, pose, facing_right, scale, origin, expression='neutral')[source]#
Pose, mirror, scale and place a puppet.
originis where the puppet’s root joint lands in panel coordinates. Mirroring happens in the puppet’s own frame before scaling, so a mirrored figure is the exact reflection of the original rather than being offset by rounding.expressionselects which face is drawn. It is validated and carried here, but the states it names are not applied until the marks are built – feature points are where the anatomy is, and are the same whatever the face is doing.- Return type:
- scenet.assets.kinematics.convex_hull(points)[source]#
Andrew’s monotone chain, returning hull vertices counter-clockwise.
Implemented here rather than delegated to shapely because it runs on a handful of points per actor and the result must be bit-for-bit reproducible; shapely is reserved for the genuinely hard polygon work in balloon placement.
scenet.assets.face#
Drawing a face: feature points plus an expression, resolved into marks.
This is artwork, which is why it lives in the asset layer and not in solve. The
solver sees a face as one disc it may not cover, and that is all it will ever see –
the marks here could be replaced by hand-drawn artwork exposing the same feature
points and nothing about layout would change.
Curves are sampled to polylines here, not in the emitter. Every consequence of an expression is therefore a number in Panel Core: a face can be read, diffed and hand-adjusted like everything else at that tier, and the emitter stays mechanical.
Level of detail is a real constraint rather than an optimisation. At long_shot a
head is a couple of dozen panel units across, and five features inside it stop being
a face and become a smudge. Below MIN_FEATURE_RADIUS nothing is drawn at all, which
is what a cartoonist does too.
- scenet.assets.face.MIN_FEATURE_RADIUS = 22.0#
Face radius in panel units below which no features are drawn. Calibrated by eye against the contact sheet –
scripts/contact_sheet.pyrenders every expression at every shot type for exactly this decision.
- scenet.assets.face.PUPIL_FRACTION = 0.34#
Pupil radius, as a fraction of the drawn eye radius.
- scenet.assets.face.PUPIL_TRAVEL = 0.75#
How far a pupil travels toward the edge of the eye when the character is looking at somebody, as a fraction of the room it has. Short of 1.0 so an aimed eye still reads as an eye rather than as a pupil escaping.
- scenet.assets.face.STROKE_FRACTION = 0.055#
Stroke width of a face mark, as a fraction of the face radius. Proportional rather than fixed so that a face drawn small does not end up with lines as heavy as a face drawn large.
- class scenet.assets.face.ResolvedStroke[source]#
Bases:
objectA line of the face, already sampled into straight segments.
- __init__(id, points, width, closed=False)#
- class scenet.assets.face.ResolvedDisc[source]#
Bases:
objectA round mark – an eye, a pupil.
- __init__(id, centre, radius, filled=False, width=0.0)#
- scenet.assets.face.build_face(puppet, states, aim=None)[source]#
Draw one face.
- Parameters:
puppet (
ResolvedPuppet) – The posed figure, whosefeaturessay where everything sits.states (
ExpressionSpec) – What each feature is doing.aim (
Vector|None) – Unit vector from the eyes toward whatever the character is looking at, or None when they are looking at nobody in particular. Pupils are offset along it, which is the only thing that makes a gaze relation visible on the page.
- Return type:
- Returns:
Marks in a fixed order – brows, eyes, pupils, nose, mouth – so that the same face always serialises to the same bytes.
Example
>>> from scenet import compile_source >>> core = compile_source( ... "{camera: {shot: close_up}, cast: {a: {reference: alice, expression: angry}}}" ... ).core >>> any(mark.id == "mouth" for mark in core.actor("a").face_marks) True
scenet.assets.emanata#
Drawing emanata: the marks around a character that say what state they are in.
Plewds, squeans, grawlixes and briffits – Mort Walker’s names, from The Lexicon of
Comicana. See Mark for what each one says.
Like a face, this is artwork, and lives in the asset layer for the same reason. Unlike a face, it is drawn outside the head circle, in the space balloons are placed in, so it has to say something to the solver. What it says is a zone per mark: a convex polygon around everything that mark draws. The solver reads the zones as a soft cost and never sees a plewd. Replace these drawings with hand-drawn ones that occupy the same zones and no layout changes.
Emanata never enter the hull. The hull is what staging spaces characters by, so a sweating character would otherwise stand further from everyone else, and the camera might retreat to fit them – a mark that moved the people in a panel would be saying something the author never wrote.
Everything is placed from the face circle, the facing direction and the feet landmark, which every puppet has. So marks need nothing from a puppet beyond the contract it already meets, and are not declared per puppet the way expressions are.
Level of detail follows the face’s rule. A plewd at long_shot is a dot: below
MIN_EMANATA_DETAIL, each symbol collapses to a filled dot where it would have been
drawn. Below the face’s own MIN_FEATURE_RADIUS, nothing is drawn – a character too
small to have a face is too small to be sweating.
- scenet.assets.emanata.MIN_EMANATA_DETAIL = 60.0#
Face radius in panel units below which emanata are drawn as dots rather than as shapes. Calibrated by eye against
scripts/contact_sheet.py --marks: in a 1000-unit panel,full_shot(a face radius of about 75) still draws a plewd you can tell is a drop, andlong_shot(about 51) does not.
- scenet.assets.emanata.STROKE_FRACTION = 0.035#
Stroke width, as a fraction of the face radius. Lighter than a face’s own lines: these are small symbols, and drawn at face weight they clot into blots.
- scenet.assets.emanata.ZONE_PADDING = 0.05#
How far a zone reaches past what it encloses, as a fraction of the face radius, on top of the stroke width. Enough that a balloon cannot sit flush against a mark.
- scenet.assets.emanata.ZONE_SAMPLES = 8#
Points sampled around each disc and each padded point when a zone is built. Eight is plenty: the zone feeds a soft cost, not a hard edge.
- scenet.assets.emanata.DROP_SAMPLES = 11#
How a drop is sampled: points along its rounded end. Odd, so the samples are symmetric about the drop’s own axis and a mirrored figure’s sweat is the exact reflection of the original.
- scenet.assets.emanata.SINGULAR: dict[Mark, str] = {Mark.BRIFFITS: 'briffit', Mark.GRAWLIXES: 'grawlix', Mark.PLEWDS: 'plewd', Mark.SQUEANS: 'squean'}#
The id each mark’s primitives are numbered under,
plewd_0,plewd_1, …
- class scenet.assets.emanata.ResolvedEmanata[source]#
Bases:
objectEvery mark drawn around one character, and the space they take up.
- marks#
The drawing, as the same strokes and discs a face is made of, in a fixed order – by mark, then by position – so the same marks always serialise to the same bytes.
- Type:
- zones#
One convex polygon per mark, enclosing everything it draws. This is the whole of what the solver sees.
- __init__(marks=(), zones=())#
- scenet.assets.emanata.build_emanata(puppet, marks)[source]#
Draw the marks around one character.
- Parameters:
puppet (
ResolvedPuppet) – The posed figure. Its face circle, facing and feet are all that is read.marks (
tuple[Mark,...]) – Which marks to draw. Order does not matter.
- Return type:
- Returns:
The drawing and its zones, or nothing at all when there are no marks or the figure is too small for them to read.
Example
>>> from scenet import compile_source >>> core = compile_source( ... "{camera: {shot: medium_shot}, cast: {a: {reference: alice, marks: [plewds]}}}" ... ).core >>> core.actor("a").emanata[0].id 'plewd_0'
scenet.assets.artwork#
The artwork contract: what a supplied picture draws, declared in its own pixels.
A puppet’s contract (scenet.assets.contract) declares everything the solver needs
about a character, so it never has to look at the drawing. An artwork contract does the
same for a picture whose people are already drawn in it: where each face is, where each
mouth is, what each body covers, and which regions lettering should stay off. The solver
reads that, and never a pixel:
# art/p01-street.art.yaml, beside art/p01-street.png
size: [3000, 2000]
figures:
ana:
face: {center: [1240, 610], radius: 150}
mouth: [1270, 700]
body: [[1050, 520], [1450, 520], [1500, 2000], [1000, 2000]]
ben:
face: {center: [2210, 580], radius: 140}
keep_out:
- [[400, 1200], [900, 1200], [900, 1700], [400, 1700]]
The vocabulary is Manga109’s – a face and a body per character, with an identity – plus the one thing a letterer needs that Manga109 does not record: the mouth, where a tail ends.
It is found beside its picture, by name. art/p01-street.png has its contract at
art/p01-street.art.yaml: the contract is a measurement of one picture and travels with
it, as a puppet’s joint offsets live in its own file and never in a panel. It is read
through read_relative, from a folder or from the files
sent with a document, exactly as the picture is.
Coordinates are the picture’s own pixels, x rightward and y downward from its top
left corner, and the contract states the size it was measured on. That size must be the
picture’s: a contract measured on another export of it would put every face in the wrong
place, and nothing could tell.
- scenet.assets.artwork.CONTRACT_RULE = 'artwork-contract'#
The rule every fault in a contract is reported under.
- scenet.assets.artwork.CONTRACT_SUFFIX = '.art.yaml'#
What a contract’s name ends in, in place of its picture’s extension.
- scenet.assets.artwork.FIGURE_RULE = 'unknown-figure'#
The rule a figure its panel’s picture does not draw is reported under.
- class scenet.assets.artwork.ArtworkContract[source]#
Bases:
BaseModelEverything the solver may know about a supplied picture’s content.
- size: tuple[int, int]#
The picture’s size in pixels,
[width, height], as it was measured. It must be the picture’s own.
- figures: dict[str, ArtworkFigure]#
Each figure the picture draws, by the name a cast member’s
figuregives it. Every face here is kept clear of lettering, cast or not.
- class scenet.assets.artwork.ArtworkFace[source]#
Bases:
BaseModelA face, as a disc no lettering may cover.
- class scenet.assets.artwork.ArtworkFigure[source]#
Bases:
BaseModelOne figure the picture draws.
- face: ArtworkFace#
The figure’s face: a disc no balloon, caption or sound effect may cover.
- exception scenet.assets.artwork.ContractError[source]#
Bases:
NamedFileErrorA contract that cannot be read, located in it as well as where its picture is named.
Its
fileis the contract’s path, as derived from the picture’s – relative to the document – and itslocis where the document names the picture.- KIND: ClassVar[str] = 'artwork contract'#
What a file of this kind is called in a message, before its path.
- class scenet.assets.artwork.LoadedContract[source]#
Bases:
objectA contract, read and held to its picture.
- contract#
What it declares.
- Type:
- __init__(path, contract, sha256)#
- scenet.assets.artwork.contract_path(image)[source]#
Where a picture’s contract is: beside it, its extension replaced.
- Parameters:
image (
str) – The picture’s path, as the document writes it.- Return type:
- Returns:
The contract’s path, relative to the document as the picture’s is.
Example
>>> from scenet.assets.artwork import contract_path >>> contract_path("art/p01-street.png") 'art/p01-street.art.yaml' >>> contract_path("cover.final.jpg") 'cover.final.art.yaml'
- scenet.assets.artwork.load_contract(image, base, *, loc=())[source]#
Read the contract beside a picture, and hold it to the picture’s size.
- Parameters:
- Return type:
- Returns:
The contract.
- Raises:
PanelSyntaxError – Rule
artwork-contract, for a contract that is not there or cannot be read – located where the picture is named.ContractError – The same rule, for a contract that is there and wrong, located in it too: not text, not YAML, a key written twice or unknown, a value out of place, or a size that is not the picture’s.
- scenet.assets.artwork.pictureless(panel)[source]#
A cast of figures with no picture to be drawn by, reported once, at the first.
- Parameters:
panel (
PanelIR) – A validated panel that casts a figure and names no picture.- Return type:
- Returns:
The fault.
- scenet.assets.artwork.undrawn(panel, contract, image)[source]#
Every line spoken, or sound made, by a cast figure this panel’s picture does not draw.
A figure is in a panel when the panel’s picture draws it, so a script’s front matter or a scene’s defaults can cast every figure of a chapter and each panel holds those its picture draws. One that is not drawn is not there, which is a fault only when the panel has it say something – and that is where a misspelt name is caught.
- Parameters:
panel (
PanelIR) – The validated panel.contract (
ArtworkContract) – Its picture’s contract.image (
str) – The picture’s path, as the document writes it.
- Return type:
- Returns:
One fault per such line, in script order, at the key naming the figure.