The language#
The intermediate representation: a validated semantic scene graph, and the real definition of the language. Nothing here carries a coordinate.
scenet.ir#
.. py:module:: scenet.ir
The intermediate representation: a validated semantic scene graph.
This is the language’s real definition. The YAML surface syntax is one way to produce it; a comic-script frontend will be another. Nothing here carries a coordinate – computing those is the solver’s job.
Validation is strict on purpose. Panel sources are untrusted input, and a typo in a predicate or an actor id should be a clear error at parse time rather than a silently wrong picture.
.. py:class:: AnchorX
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhere along the panel width an actor would like to stand.
Horizontal only. Actors stand on a ground line, so their vertical position is derived from the camera rather than requested – which is why this has no vertical counterpart and :class:
PlacementZone <scenet.ir.PlacementZone>, used for balloons, does.These are weak preferences. Non-overlap and declared left-to-right ordering are required constraints and will override an anchor without complaint; two actors both asking for
centerwill simply be pushed apart around it... py:attribute:: AnchorX.LEFT_EDGE
- module:
scenet.ir
- value:
‘left_edge’
.. py:attribute:: AnchorX.LEFT_THIRD
- module:
scenet.ir
- value:
‘left_third’
.. py:attribute:: AnchorX.CENTRE
- module:
scenet.ir
- value:
‘center’
.. py:attribute:: AnchorX.RIGHT_THIRD
- module:
scenet.ir
- value:
‘right_third’
.. py:attribute:: AnchorX.RIGHT_EDGE
- module:
scenet.ir
- value:
‘right_edge’
.. py:method:: AnchorX.new(value)
- module:
scenet.ir
.. py:class:: BalloonKind
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhat kind of balloon carries a line, which is how it gets drawn.
The kind changes the outline and the tail, never the placement: a whisper is subject to exactly the same face-avoidance and reading-order rules as a shout.
Kind
Outline
Tail
speechrounded rectangle
tapered pointer
thoughtellipse
trail of bubbles
whisperdashed rounded rectangle
tapered pointer
shoutjagged burst
tapered pointer
.. py:attribute:: BalloonKind.SPEECH
- module:
scenet.ir
- value:
‘speech’
.. py:attribute:: BalloonKind.THOUGHT
- module:
scenet.ir
- value:
‘thought’
.. py:attribute:: BalloonKind.WHISPER
- module:
scenet.ir
- value:
‘whisper’
.. py:attribute:: BalloonKind.SHOUT
- module:
scenet.ir
- value:
‘shout’
.. py:method:: BalloonKind.new(value)
- module:
scenet.ir
.. py:class:: CameraAngle
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumThe camera’s height relative to the subject.
Affects headroom rather than perspective: this is a flat, orthographic compiler, so a tilted camera does not foreshorten anything. What it changes is how much air sits above the head – which is the compositional cue readers actually take from an angle, and one that survives being drawn flat.
A low camera looks up and the subject looms, so the head rides high in the frame with little space above it. A high camera looks down, so the head sits lower and more space opens up above. See
- func:
headroom_for <scenet.solve.camera.headroom_for>for the exact factors.
.. py:attribute:: CameraAngle.LOW
- module:
scenet.ir
- value:
‘low’
.. py:attribute:: CameraAngle.EYE_LEVEL
- module:
scenet.ir
- value:
‘eye_level’
.. py:attribute:: CameraAngle.HIGH
- module:
scenet.ir
- value:
‘high’
.. py:method:: CameraAngle.new(value)
- module:
scenet.ir
.. py:class:: CameraSpec
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictHow the panel is framed.
.. attribute:: shot
Requested framing; an upper bound on tightness, see
- class:
ShotType <scenet.ir.ShotType>.
.. attribute:: angle
Camera height, see :class:
CameraAngle <scenet.ir.CameraAngle>.There is exactly one camera per panel, and every actor is drawn at the scale it implies. Scaling each actor to its own crop landmark instead would make everybody the same apparent height and erase the body differences a comic uses to tell characters apart.
.. py:attribute:: CameraSpec.shot
- module:
scenet.ir
- type:
~scenet.ir.ShotType
.. py:attribute:: CameraSpec.angle
- module:
scenet.ir
- type:
~scenet.ir.CameraAngle
.. py:class:: CaptionEvent
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne caption box: the panel speaking in its own voice.
A caption is what lets a panel say where and when it happens without a character having to explain it out loud.
MIDNIGHT. THE DOCKS.in the corner does the work of an establishing shot with no artwork at all, which is how comics established place long before they had reliable backgrounds... attribute:: verb
Always
caption, written as- caption: {...}... attribute:: text
What the box says. As with dialogue, line breaking is computed, and a word between underscores is stressed.
.. attribute:: kind
What the box is doing, which decides how it is set.
.. attribute:: tone
What the box is filled with. Defaults to
paper, the white every caption has been since captions shipped, so no existing panel moves... attribute:: prefer
Where it would like to sit. Defaults to
top_left, which is where alocalecaption conventionally goes... attribute:: by
Who is speaking, for a
spokencaption only.A caption is not a fifth balloon kind. It has no speaker to point at and no tail, and :attr:
CoreBalloon.tail <scenet.core.CoreBalloon.tail>is required – a fifth kind would mean inventing a speaker and leaving a field dead.byis the one place where the rule that every actor id resolves does not hold, and deliberately: an off-panel speaker is not in the panel, so requiring them to be in the cast would defeat the point of saying they are off panel... admonition:: Example
from scenet.ir import CaptionEvent CaptionEvent(text=”Midnight. The docks.”).kind.value ‘locale’
.. py:attribute:: CaptionEvent.verb
- module:
scenet.ir
- type:
~typing.Literal[‘caption’]
.. py:attribute:: CaptionEvent.text
- module:
scenet.ir
- type:
~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable), ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._balanced)]
.. py:attribute:: CaptionEvent.kind
- module:
scenet.ir
- type:
~scenet.ir.CaptionKind
.. py:attribute:: CaptionEvent.tone
- module:
scenet.ir
- type:
~scenet.ir.CaptionTone
.. py:attribute:: CaptionEvent.prefer
- module:
scenet.ir
- type:
~scenet.ir.PlacementZone
.. py:attribute:: CaptionEvent.by
- module:
scenet.ir
- type:
~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable)] | None
.. py:method:: CaptionEvent.check_speaker_is_meaningful(by, info)
- module:
scenet.ir
- classmethod:
Only an off-panel line has a speaker to name.
A check on
byrather than on the whole caption, so the finding points at theby:to delete. Fields are validated in the order they are declared, sokindhas been by now; if it failed, there is no kind to holdbyto, and the finding aboutkindis the one to report.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str` | :py:obj:`None``
- returns:
The speaker, unchanged.
- raises ValueError:
bywas given for a kind that has no speaker. A locale box states a place; nobody says it, so naming who did is a mistake worth reporting rather than a field to ignore.
.. py:class:: CaptionKind
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhat a caption box is doing, which is how it gets set.
These four are the letterers’ own vocabulary, taken from Blambot’s Comic Book Grammar & Tradition rather than invented – for the same reason the predicates were taken from Visual Genome. Note that “narration”, the obvious guess, is not among them.
Kind
What it is
How it is set
localeLocation and time – “Midnight. The docks.”
Italic
monologueA character’s inner voice
Italic
spokenOff-panel dialogue
Roman, in quotation marks
editorialThe voice of the writer or editor
Italic
monologuehas largely replaced the thought balloon in modern comics, so a panel has two ways to render an inner voice: this and- attr:
BalloonKind.THOUGHT <scenet.ir.BalloonKind>. Both are correct. They are different eras of the same convention, not a duplication.
.. py:attribute:: CaptionKind.LOCALE
- module:
scenet.ir
- value:
‘locale’
.. py:attribute:: CaptionKind.MONOLOGUE
- module:
scenet.ir
- value:
‘monologue’
.. py:attribute:: CaptionKind.SPOKEN
- module:
scenet.ir
- value:
‘spoken’
.. py:attribute:: CaptionKind.EDITORIAL
- module:
scenet.ir
- value:
‘editorial’
.. py:property:: CaptionKind.is_italic
- module:
scenet.ir
- type:
bool
Whether this kind is set in italic. Everything except
spoken.
.. py:property:: CaptionKind.is_quoted
- module:
scenet.ir
- type:
bool
Whether this kind takes quotation marks.
spokenonly, because it is the one kind where somebody is talking.
.. py:method:: CaptionKind.new(value)
- module:
scenet.ir
.. py:class:: CaptionTone
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumThe value a caption box is filled with.
A caption box is opaque, so its lettering is never at risk: the text sits on the fill whatever is behind it. What a tone changes is whether the box reads. On a clear day the atmosphere is
#eeeeeeand a white box on it is 1.16:1 – legible, and invisible. The failing case is the pale end, not the dark one.Tone
Fill
Where it comes from
Lettered in
paper#ffffffthe paper the panel is printed on
ink
pale#adadadthe
dayrow of the value ladder, far planeink
ink#090909the
dayrow of the value ladder, foregroundpaper
Drawn from the ladder in
solve/backdrop.py, not from a second palette. Two of the three are rungs of it, taken by index rather than restated, which is what keeps lettering and backdrop from drifting apart as either is tuned. Thedayrow is the ladder at its widest, so tones taken from it span the most ground.A tone is fixed, not a function of the panel’s hour. A caption’s value is a property of the caption; letting it drift with
timewould make the contrast table a function of the panel and the legibility floor unenforceable.inkproduces what letterers call reversed type: the lettering inverts to paper, because black type on a near-black box is not lettering, it is a filled rectangle. Which mark reads is resolved by the solver – see- attr:
CoreCaption.ink <scenet.core.CoreCaption>– exactly as falling rain’s is.
There is no free-form colour here, and no yellow. A
fill:taking any string would be the language’s one open vocabulary and would let an author produce an unreadable box; the classic yellowlocalecaption would be the first non-neutral value in the codebase, and the language has no colour policy yet to put it under... py:attribute:: CaptionTone.PAPER
- module:
scenet.ir
- value:
‘paper’
.. py:attribute:: CaptionTone.PALE
- module:
scenet.ir
- value:
‘pale’
.. py:attribute:: CaptionTone.INK
- module:
scenet.ir
- value:
‘ink’
.. py:method:: CaptionTone.new(value)
- module:
scenet.ir
.. py:class:: CastMember
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne character present in the panel.
.. attribute:: reference
Name of a puppet in the library. This is what gets drawn; the key this member is filed under in
castis the actor id used everywhere else... attribute:: pose
Named pose from that puppet’s declared set.
.. attribute:: expression
Named expression from that puppet’s declared set. Selected by name exactly as a pose is, because a face is the same kind of thing as a body: a small closed set of arrangements the character can be in.
.. attribute:: marks
Emanata drawn around the character – sweat, dizziness, swearing, a hasty exit. A list, because they compose with each other and with the expression. Kept sorted, so the order they were written in never changes the output.
.. attribute:: at
Preferred horizontal anchor.
.. attribute:: facing
Which way the figure is turned.
The split between actor id and
referenceis what lets one puppet appear twice in a panel as two different people:cast: guard_left: {reference: bob, pose: arms_crossed} guard_right: {reference: bob, pose: standing_neutral, facing: left}.. py:attribute:: CastMember.reference
- module:
scenet.ir
- type:
str
.. py:attribute:: CastMember.pose
- module:
scenet.ir
- type:
str
.. py:attribute:: CastMember.expression
- module:
scenet.ir
- type:
str
.. py:attribute:: CastMember.marks
- module:
scenet.ir
- type:
tuple[~scenet.ir.Mark, …]
.. py:attribute:: CastMember.at
- module:
scenet.ir
- type:
~scenet.ir.AnchorX
.. py:attribute:: CastMember.facing
- module:
scenet.ir
- type:
~scenet.ir.Facing
.. py:method:: CastMember.check_marks(marks)
- module:
scenet.ir
- classmethod:
Reject a mark listed twice, and put the rest in a fixed order.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Mark`, :py:data:`…<Ellipsis>`]`
- returns:
The marks, sorted.
- raises ValueError:
A mark appears more than once. Harmless to draw, but almost certainly a slip, and this language reports slips.
.. py:class:: Column
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictPanels stacked top to bottom, beside the other columns of a tier.
.. attribute:: width
Its share of the tier’s width, relative to the other columns.
.. attribute:: panels
The panels in it, top to bottom.
.. py:attribute:: Column.width
- module:
scenet.ir
- type:
float
.. py:attribute:: Column.panels
- module:
scenet.ir
- type:
tuple[~scenet.ir.StackedPanel, …]
.. py:class:: Corner
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhich corner of its parent an inset sits in.
.. py:attribute:: Corner.TOP_LEFT
- module:
scenet.ir
- value:
‘top_left’
.. py:attribute:: Corner.TOP_RIGHT
- module:
scenet.ir
- value:
‘top_right’
.. py:attribute:: Corner.BOTTOM_LEFT
- module:
scenet.ir
- value:
‘bottom_left’
.. py:attribute:: Corner.BOTTOM_RIGHT
- module:
scenet.ir
- value:
‘bottom_right’
.. py:method:: Corner.new(value)
- module:
scenet.ir
.. py:class:: Face
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhich face of the lettering family a run of text is set in.
Not something an author writes: a caption’s kind decides between roman and italic, and a word written between underscores is set in bold italic. It is recorded in Panel Core, run by run, so the emitter draws each run in the face it was measured in.
Face
Used for
regularDialogue, and
spokencaptionsitalicEvery other caption kind
bold_italicEmphasis, in either – Blambot’s rule for a stressed word
displaySound effects: letters that are part of the picture
Each is a real font file of the same family. A synthetic slant or a stroked-out bold would measure as the roman face and draw as neither, which is the disagreement between measurement and rendering that lettering as outlines exists to prevent.
.. py:attribute:: Face.REGULAR
- module:
scenet.ir
- value:
‘regular’
.. py:attribute:: Face.ITALIC
- module:
scenet.ir
- value:
‘italic’
.. py:attribute:: Face.BOLD_ITALIC
- module:
scenet.ir
- value:
‘bold_italic’
.. py:attribute:: Face.DISPLAY
- module:
scenet.ir
- value:
‘display’
.. py:method:: Face.new(value)
- module:
scenet.ir
.. py:class:: Facing
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhich way an actor is turned.
Mirroring the whole puppet, gaze vector included. Defaults to
right, so a cast written left to right ends up looking into the panel rather than out of it... py:attribute:: Facing.LEFT
- module:
scenet.ir
- value:
‘left’
.. py:attribute:: Facing.RIGHT
- module:
scenet.ir
- value:
‘right’
.. py:method:: Facing.new(value)
- module:
scenet.ir
.. py:class:: FontSpec
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictThe font files a panel is lettered in, each a path relative to the document.
.. attribute:: regular
Dialogue, and
spokencaptions. Written alone –font: path– it is the only face, and stands in for the others... attribute:: italic
Every other caption kind. Left out, captions are set in
regular... attribute:: display
Sound effects. Left out, they are lettered in the shipped display face, Bangers, whatever the other faces are: a sound effect is not text.
.. attribute:: bold_italic
Emphasis. Left out, emphasis is set in
italicwhen there is one, inregularwhen there is not – and a note says so when it happens.Paths, never names: a font is a declared file and never a system lookup, so a document letters the same on every machine. They are read relative to the folder the document is in, and an absolute one is refused; see :mod:
scenet.paths... admonition:: Example
from scenet import parse_panel parse_panel(“lettering: {font: fonts/Comic.ttf}”).lettering.font.regular ‘fonts/Comic.ttf’
.. py:attribute:: FontSpec.regular
- module:
scenet.ir
- type:
str
.. py:attribute:: FontSpec.italic
- module:
scenet.ir
- type:
str | None
.. py:attribute:: FontSpec.bold_italic
- module:
scenet.ir
- type:
str | None
.. py:attribute:: FontSpec.display
- module:
scenet.ir
- type:
str | None
.. py:class:: Horizon
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhere the ground meets whatever is behind it.
One line for the whole panel, which every mass is composed against: masses of the ground sort start at it and run down, masses that stand in the world rise from it. Named rather than given as a number for the same reason
at:is – the author is saying how the panel is composed, not typing a coordinate... py:attribute:: Horizon.HIGH
- module:
scenet.ir
- value:
‘high’
.. py:attribute:: Horizon.MID
- module:
scenet.ir
- value:
‘mid’
.. py:attribute:: Horizon.LOW
- module:
scenet.ir
- value:
‘low’
.. py:property:: Horizon.fraction
- module:
scenet.ir
- type:
float
Where the line sits, as a fraction of panel height.
A high horizon sits nearer the top of the frame, so more ground is in view and the camera reads as looking down over it.
.. admonition:: Example
from scenet.ir import Horizon Horizon.HIGH.fraction < Horizon.LOW.fraction True
.. py:method:: Horizon.new(value)
- module:
scenet.ir
.. py:class:: Inset
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictA small panel set into a corner of another, and drawn over it.
Readers do not agree on when to read an inset: in Cohn’s 2013 experiments, overlap split them about evenly between the inset and the panel under it. So the order is stated rather than guessed – after its parent, unless
read: before... attribute:: use
The name of a panel under
panels:... attribute:: at
The corner of its parent it sits in, a gutter in from both edges.
.. attribute:: size
Its width and height, as a fraction of its parent’s: more than 0, at most 0.5.
.. attribute:: read
Whether it is read before its parent or after it.
.. py:attribute:: Inset.use
- module:
scenet.ir
- type:
str
.. py:attribute:: Inset.at
- module:
scenet.ir
- type:
~scenet.ir.Corner
.. py:attribute:: Inset.size
- module:
scenet.ir
- type:
float
.. py:attribute:: Inset.read
- module:
scenet.ir
- type:
~scenet.ir.InsetOrder
.. py:class:: InsetOrder
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhether an inset is read before the panel it sits in, or after it.
.. py:attribute:: InsetOrder.BEFORE
- module:
scenet.ir
- value:
‘before’
.. py:attribute:: InsetOrder.AFTER
- module:
scenet.ir
- value:
‘after’
.. py:method:: InsetOrder.new(value)
- module:
scenet.ir
.. py:class:: LetteringSpec
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictHow a panel is lettered.
.. attribute:: size
The dialogue type size, in panel units – the units
panel.sizeis given in, which on a page are the page’s, since a panel there is compiled at its frame’s size. Captions keep their proportion to it: 30 parts in 35, as they are by default. Left out, a panel letters at 3.5% of the height it letters against: its own alone, one tier of a three-tier page on a page... attribute:: font
The font files to letter in, in place of the shipped Source Sans Pro.
A size or a font set beside
panels:is a default every panel inherits, which is how a page letters at one size of the author’s choosing. Set on one panel, it letters that panel alone – the author’s call to make, and not one the compiler second-guesses.The type is measured at exactly this size, so it decides how big every balloon is. A size too large for the panel leaves a balloon nowhere to go, which
scenet check --deepreports asballoon-placement... admonition:: Example
from scenet import parse_panel parse_panel(“lettering: {size: 30}”).lettering.size 30.0
.. py:attribute:: LetteringSpec.size
- module:
scenet.ir
- type:
float | None
.. py:attribute:: LetteringSpec.font
- module:
scenet.ir
- type:
~scenet.ir.FontSpec | None
.. py:class:: Mark
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumSomething drawn around a character, rather than on them, to say how they are.
The vocabulary is Mort Walker’s, from The Lexicon of Comicana (1980), which grew out of his 1964 National Cartoonists Society piece “Let’s Get Down to Grawlixes”. The book is tongue-in-cheek, but the terms entered real use, and they are comics’ own names for comics’ own conventions. So the set is closed and citable, and nothing in it is invented here.
Mark
What it is
What it says
plewdsDroplets flying off the head
sweating: effort, heat, nerves
squeansLittle starbursts and circles over the head
dizzy, drunk, or sick
grawlixesSymbols over the head standing in for words
swearing
briffitsA dust cloud left at the feet
gone, fast
“Emanata” is Walker’s general term for these, which is why it names the module that draws them and the Core field that holds them.
A mark is not an expression. A character can be angry and sweating, so marks are a list that composes with
expression:rather than a second one. Grawlixes are drawn as symbols – a jarn (spiral), a nittle (bursting star), a bolt and a hash – rather than typed: an oath written as@#$%!already works, as dialogue.All four are drawn outside the head circle, in the space balloons are placed in. They never move a character. A balloon prefers not to cover them, and covers them anyway rather than fail when a panel is too crowded to oblige.
.. py:attribute:: Mark.PLEWDS
- module:
scenet.ir
- value:
‘plewds’
.. py:attribute:: Mark.SQUEANS
- module:
scenet.ir
- value:
‘squeans’
.. py:attribute:: Mark.GRAWLIXES
- module:
scenet.ir
- value:
‘grawlixes’
.. py:attribute:: Mark.BRIFFITS
- module:
scenet.ir
- value:
‘briffits’
.. py:method:: Mark.new(value)
- module:
scenet.ir
.. py:class:: Mass
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne tonal mass in the backdrop: what it is, how far back, how wide.
.. attribute:: kind
What the mass is made of, which decides its silhouette.
.. attribute:: plane
How far back it sits, which decides its value and its draw order.
.. attribute:: spans
How much of the panel’s width it covers.
Backdrops are never author-drawn, and there are two reasons. The structural one: crisp architecture needs a vanishing point, and this is deliberately a flat, orthographic compiler, so drawn buildings would fight the compiler’s own model. Soft tonal masses have no perspective to get wrong.
The second is that this is how comics actually establish place. Notan – the Japanese light/dark mass principle, which reached Western art teaching through Arthur Wesley Dow’s Composition (1899) – says place is read from the arrangement of masses rather than from rendered detail.
.. admonition:: Example
from scenet.ir import Mass, MassKind Mass(kind=MassKind.SKY).plane.value ‘mid’
.. py:attribute:: Mass.kind
- module:
scenet.ir
- type:
~scenet.ir.MassKind
.. py:attribute:: Mass.plane
- module:
scenet.ir
- type:
~scenet.ir.Plane
.. py:attribute:: Mass.spans
- module:
scenet.ir
- type:
~scenet.ir.Spans
.. py:class:: MassKind
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhat a tonal mass in the backdrop is made of.
Subsetted from the supercategories of COCO-Stuff, the canonical taxonomy of stuff – “amorphous background regions” as opposed to things with a well-defined shape. Its own argument is that stuff classes explain scene type and the geometric properties of a scene, which is exactly the job here. Taken from an existing vocabulary for the same reason the predicates were taken from Visual Genome.
Deliberately not the leaf names. COCO-Stuff’s actual classes are
building-other,sky-other,wall-brick,water-otherand so on, where the-othersuffix marks the catch-all inside a supercategory.building-otheris not a word anyone should have to type.Seven are outdoor –
building,ground,plant,sky,solid,structural,water– and five indoor:ceiling,floor,furniture,wall,window. COCO-Stuff’s own indoor/outdoor split is where that distinction comes from, so it did not have to be invented either. Itstextile,foodandrawmaterialsupercategories are left out: drapery and objects, not scene-defining masses.A kind decides the shape a mass takes, never its value. Value comes from the plane, which is what keeps the notan reading honest – see
- class:
Plane <scenet.ir.Plane>.
.. py:attribute:: MassKind.BUILDING
- module:
scenet.ir
- value:
‘building’
.. py:attribute:: MassKind.CEILING
- module:
scenet.ir
- value:
‘ceiling’
.. py:attribute:: MassKind.FLOOR
- module:
scenet.ir
- value:
‘floor’
.. py:attribute:: MassKind.FURNITURE
- module:
scenet.ir
- value:
‘furniture’
.. py:attribute:: MassKind.GROUND
- module:
scenet.ir
- value:
‘ground’
.. py:attribute:: MassKind.PLANT
- module:
scenet.ir
- value:
‘plant’
.. py:attribute:: MassKind.SKY
- module:
scenet.ir
- value:
‘sky’
.. py:attribute:: MassKind.SOLID
- module:
scenet.ir
- value:
‘solid’
.. py:attribute:: MassKind.STRUCTURAL
- module:
scenet.ir
- value:
‘structural’
.. py:attribute:: MassKind.WALL
- module:
scenet.ir
- value:
‘wall’
.. py:attribute:: MassKind.WATER
- module:
scenet.ir
- value:
‘water’
.. py:attribute:: MassKind.WINDOW
- module:
scenet.ir
- value:
‘window’
.. py:method:: MassKind.new(value)
- module:
scenet.ir
.. py:class:: PageFormat
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictThe page every panel on it is laid out on.
In the same abstract units a panel uses: a page is not yet a printed size. Millimetres, trim and bleed belong to print, which is a separate piece of work.
.. attribute:: size
(width, height). The default is 1 : 1.5, close to a US comic’s 6.625 x 10.25 inches... attribute:: margin
The blank border inside the page edge, on all four sides.
.. attribute:: gutter
The gap between two panels side by side in a tier.
.. attribute:: tier_gutter
The gap between two tiers. Wider than
gutterby default, as it usually is in print: a narrower gap within a tier binds its panels into one row, which is the direction they are read in... admonition:: Example
from scenet import PageFormat PageFormat().size (2000.0, 3000.0)
.. py:attribute:: PageFormat.size
- module:
scenet.ir
- type:
tuple[float, float]
.. py:attribute:: PageFormat.margin
- module:
scenet.ir
- type:
float
.. py:attribute:: PageFormat.gutter
- module:
scenet.ir
- type:
float
.. py:attribute:: PageFormat.tier_gutter
- module:
scenet.ir
- type:
float
.. py:property:: PageFormat.width
- module:
scenet.ir
- type:
float
Page width.
.. py:property:: PageFormat.height
- module:
scenet.ir
- type:
float
Page height.
.. py:method:: PageFormat.check_positive()
- module:
scenet.ir
Reject a page with no area inside its margin.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``
.. py:class:: PageLayout
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictEvery page of a scene, and the format they share.
.. attribute:: page
The format.
.. attribute:: pages
The pages, in order.
The panels themselves are not part of it: a page names them, and
- func:
check_placements <scenet.ir.check_placements>checks the names against the panels the document defines.
.. py:attribute:: PageLayout.page
- module:
scenet.ir
- type:
~scenet.ir.PageFormat
.. py:attribute:: PageLayout.pages
- module:
scenet.ir
- type:
tuple[~scenet.ir.PageSpec, …]
.. py:method:: PageLayout.check_room()
- module:
scenet.ir
Every tier must have room for its panels and every page for its tiers.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``
.. py:class:: PageSpec
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne page: tiers, top to bottom.
A page is read tier by tier, left to right within a tier and down each column of a tier of columns, so the order panels are written in is the order they are read in. That is the page’s version of the rule a balloon obeys, and it holds by construction: columns that readers would not read down are refused by
- class:
PageLayout <scenet.ir.PageLayout>.
.. attribute:: tiers
The tiers, top to bottom.
.. py:attribute:: PageSpec.tiers
- module:
scenet.ir
- type:
tuple[~scenet.ir.Tier, …]
.. py:class:: PanelIR
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictA complete, validated panel: the language’s real definition.
Every frontend produces one of these and nothing else, which is what lets the YAML syntax and the comic-script syntax coexist without the solver knowing either exists. Nothing here carries a coordinate – computing those is the solver’s job, and keeping them out is what makes a panel reusable at any size.
.. attribute:: panel
Dimensions and margin.
.. attribute:: camera
Framing and angle.
.. attribute:: cast
Actor id to character. Declaration order is not significant;
stagingdecides left-to-right order... attribute:: staging
Spatial and attentional relations between actors.
.. attribute:: script
Dialogue and captions, in reading order.
.. attribute:: lettering
How the lettering is set: its type size, when the author chooses one.
Validation is strict and total: unknown keys are rejected, every actor id mentioned in
stagingorscriptmust exist incast, and the ordering relations must not contain a cycle. A misspelled key that was silently ignored would produce a panel that is subtly wrong with no indication of why, which for a language meant to be precise is the worst possible failure... admonition:: Example
from scenet import parse_panel panel = parse_panel(“panel: {size: [800.0, 600.0]}”) panel.panel.width, panel.camera.shot.value (800.0, ‘medium_shot’)
.. seealso:: :func:
compile_ir <scenet.pipeline.compile_ir>, to turn one of these into geometry... py:attribute:: PanelIR.panel
- module:
scenet.ir
- type:
~scenet.ir.PanelSpec
.. py:attribute:: PanelIR.camera
- module:
scenet.ir
- type:
~scenet.ir.CameraSpec
.. py:attribute:: PanelIR.setting
- module:
scenet.ir
- type:
~scenet.ir.SettingSpec
.. py:attribute:: PanelIR.lettering
- module:
scenet.ir
- type:
~scenet.ir.LetteringSpec
.. py:attribute:: PanelIR.cast
- module:
scenet.ir
- type:
dict[~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable)], ~scenet.ir.CastMember]
.. py:attribute:: PanelIR.staging
- module:
scenet.ir
- type:
tuple[~scenet.ir.Relation, …]
.. py:attribute:: PanelIR.script
- module:
scenet.ir
- type:
tuple[~typing.Annotated[~typing.Annotated[~scenet.ir.SayEvent, ~pydantic.types.Tag(tag=say)] | ~typing.Annotated[~scenet.ir.CaptionEvent, ~pydantic.types.Tag(tag=caption)] | ~typing.Annotated[~scenet.ir.SfxEvent, ~pydantic.types.Tag(tag=sfx)] | ~typing.Annotated[~scenet.ir.SayEvent | ~scenet.ir.CaptionEvent | ~scenet.ir.SfxEvent, ~pydantic.json_schema.SkipJsonSchema(), ~pydantic.types.Tag(tag=untagged)], ~pydantic.types.Discriminator(discriminator=~scenet.ir.tag_by.
.tag_of, custom_error_type=None, custom_error_message=None, custom_error_context=None)], …]
.. py:method:: PanelIR.check_references_resolve()
- module:
scenet.ir
Every actor id mentioned anywhere must exist in the cast.
Caught here rather than in the solver so the error names the offending identifier while the source is still in view.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``
.. py:method:: PanelIR.check_ordering_is_consistent()
- module:
scenet.ir
Horizontal ordering must not contain a cycle.
The layout engine is a linear constraint solver, so ordering has to be decided before it runs – see docs/reference/language.md. A cycle such as ‘a left_of b, b left_of a’ has no solution, and detecting it here produces a comprehensible message instead of an opaque solver failure.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``
.. py:method:: PanelIR.ordering_constraints()
- module:
scenet.ir
Normalised (left, right) pairs from both left_of and right_of relations.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`tuple`\ \[:py:class:`str`, :py:class:`str`], :py:data:`…<Ellipsis>`]`
.. py:method:: PanelIR.gaze_targets()
- module:
scenet.ir
Who is looking at whom.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`str`]`
- returns:
A mapping from each looking actor to the actor they are looking at. An actor may look at only one target, so a later
looking_atrelation for the same subject replaces an earlier one.
.. admonition:: Example
from scenet import parse_panel panel = parse_panel( … “{cast: {a: {reference: alice}, b: {reference: bob}},” … “ staging: [a looking_at b]}” … ) panel.gaze_targets() {‘a’: ‘b’}
.. py:method:: PanelIR.off_panel_speakers()
- module:
scenet.ir
Who is heard from off panel, and the side each is heard from, if any line names one.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.Side` | :py:obj:`None`]`
- returns:
Speaker to the first side a line of theirs names, or None when every line of theirs says only
off_panel: true, in the order they first speak.
.. admonition:: Example
from scenet import parse_panel panel = parse_panel( … “{script: [{say: {by: carol, text: Hi, off_panel: true}},” … “ {say: {by: carol, text: Here, off_panel: left}}]}” … ) panel.off_panel_speakers() {‘carol’: <Side.LEFT: ‘left’>}
.. py:method:: PanelIR.ground_groups()
- module:
scenet.ir
Actors joined by ground_shared_with, as connected components.
Union-find rather than pairwise handling, so that ‘a with b’ plus ‘b with c’ puts all three on one ground line without the author saying ‘a with c’.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`frozenset`\ \[:py:class:`str`], :py:data:`…<Ellipsis>`]`
.. py:class:: PanelPlacement
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne panel in a tier.
Written as the panel’s name alone, or as
{use: name, width: 2}to give it a larger share of the tier... attribute:: use
The name of a panel under
panels:... attribute:: width
Its share of the tier’s width, relative to the other panels in the tier.
.. attribute:: insets
Panels set into its corners.
.. py:attribute:: PanelPlacement.use
- module:
scenet.ir
- type:
str
.. py:attribute:: PanelPlacement.width
- module:
scenet.ir
- type:
float
.. py:attribute:: PanelPlacement.insets
- module:
scenet.ir
- type:
tuple[~scenet.ir.Inset, …]
.. py:class:: PanelSpec
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictThe panel’s own dimensions.
.. attribute:: size
(width, height)in panel units. Everything else in the language is expressed relative to these, so they set what a unit means... attribute:: margin
Inset on all four sides. Balloons are kept inside it; actors may bleed past it, which is ordinary comics practice.
.. admonition:: Example
from scenet import PanelSpec PanelSpec(size=(1200.0, 600.0)).width 1200.0
.. py:attribute:: PanelSpec.size
- module:
scenet.ir
- type:
tuple[float, float]
.. py:attribute:: PanelSpec.margin
- module:
scenet.ir
- type:
float
.. py:property:: PanelSpec.width
- module:
scenet.ir
- type:
float
Panel width in panel units.
.. py:property:: PanelSpec.height
- module:
scenet.ir
- type:
float
Panel height in panel units.
.. py:method:: PanelSpec.check_positive()
- module:
scenet.ir
Reject a panel with no usable area.
- rtype:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``- returns:
The validated spec.
- raises ValueError:
A dimension is zero or negative, or the margins meet in the middle leaving nothing to compose in.
.. py:class:: PlacementZone
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhere in the panel a balloon would prefer to sit.
Two-dimensional, unlike
AnchorX: an actor is placed along the ground line and so only needs a horizontal anchor, whereas a balloon floats and needs both axes. These are hints of the weakest priority – occlusion and reading order override them freely... py:attribute:: PlacementZone.TOP_LEFT
- module:
scenet.ir
- value:
‘top_left’
.. py:attribute:: PlacementZone.TOP_CENTRE
- module:
scenet.ir
- value:
‘top_center’
.. py:attribute:: PlacementZone.TOP_RIGHT
- module:
scenet.ir
- value:
‘top_right’
.. py:attribute:: PlacementZone.MIDDLE_LEFT
- module:
scenet.ir
- value:
‘middle_left’
.. py:attribute:: PlacementZone.MIDDLE_CENTRE
- module:
scenet.ir
- value:
‘middle_center’
.. py:attribute:: PlacementZone.MIDDLE_RIGHT
- module:
scenet.ir
- value:
‘middle_right’
.. py:attribute:: PlacementZone.BOTTOM_LEFT
- module:
scenet.ir
- value:
‘bottom_left’
.. py:attribute:: PlacementZone.BOTTOM_CENTRE
- module:
scenet.ir
- value:
‘bottom_center’
.. py:attribute:: PlacementZone.BOTTOM_RIGHT
- module:
scenet.ir
- value:
‘bottom_right’
.. py:property:: PlacementZone.fractions
- module:
scenet.ir
- type:
tuple[float, float]
The zone’s centre as a fraction of panel width and height.
.. py:method:: PlacementZone.new(value)
- module:
scenet.ir
.. py:class:: Plane
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumHow far back a mass sits, which decides both its draw order and its value.
Four planes, ordered from the back of the panel forward. They map onto the existing integer :attr:
CoreActor.depth <scenet.core.CoreActor.depth>painter’s order rather than introducing a second ordering mechanism: the three backdrop planes take negative depths, andforegroundtakes one above the frontmost actor, so a foreground mass draws over the cast the way a silhouetted doorway does.Value follows from the plane and from nothing else, which is what makes the aerial perspective rule parametric: with distance, contrast drops toward the atmosphere. Reading front to back, a mass never gets darker. See
- func:
tone_for <scenet.solve.backdrop.tone_for>.
.. py:attribute:: Plane.FOREGROUND
- module:
scenet.ir
- value:
‘foreground’
.. py:attribute:: Plane.NEAR
- module:
scenet.ir
- value:
‘near’
.. py:attribute:: Plane.MID
- module:
scenet.ir
- value:
‘mid’
.. py:attribute:: Plane.FAR
- module:
scenet.ir
- value:
‘far’
.. py:method:: Plane.new(value)
- module:
scenet.ir
.. py:class:: Predicate
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumHow one actor stands in relation to another.
Drawn from the spatial subset of the Visual Genome vocabulary rather than invented, so a scene stays convertible to and from the scene-graph representations used elsewhere in computer vision.
left_ofandright_ofare the load-bearing ones: they are resolved at parse time into a linear ordering, because Cassowary cannot express the disjunction “A left of B or B left of A”... py:attribute:: Predicate.LEFT_OF
- module:
scenet.ir
- value:
‘left_of’
.. py:attribute:: Predicate.RIGHT_OF
- module:
scenet.ir
- value:
‘right_of’
.. py:attribute:: Predicate.IN_FRONT_OF
- module:
scenet.ir
- value:
‘in_front_of’
.. py:attribute:: Predicate.BEHIND
- module:
scenet.ir
- value:
‘behind’
.. py:attribute:: Predicate.LOOKING_AT
- module:
scenet.ir
- value:
‘looking_at’
.. py:attribute:: Predicate.GROUND_SHARED_WITH
- module:
scenet.ir
- value:
‘ground_shared_with’
.. py:method:: Predicate.new(value)
- module:
scenet.ir
.. py:class:: Relation
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne staging fact, written as a sentence.
.. attribute:: subject
Actor id the sentence is about.
.. attribute:: predicate
What relation holds.
.. attribute:: object
The other actor id.
Authored as
alice left_of bobrather than a three-key mapping because staging is read far more often than it is written, and a sentence is legible at a glance.- raises pydantic.ValidationError:
The subject and object are the same actor. No predicate here is meaningful reflexively.
.. py:attribute:: Relation.subject
- module:
scenet.ir
- type:
str
.. py:attribute:: Relation.predicate
- module:
scenet.ir
- type:
~scenet.ir.Predicate
.. py:attribute:: Relation.object
- module:
scenet.ir
- type:
str
.. py:method:: Relation.check_not_reflexive()
- module:
scenet.ir
Reject a relation between an actor and itself.
- rtype:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``- returns:
The validated relation.
- raises ValueError:
Subject and object are the same actor id. No predicate in the language means anything reflexively, so this is always a typo.
.. py:class:: SayEvent
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne line of dialogue.
.. attribute:: verb
Always
say. The tag the surface syntax writes as- say: {...}, carried into the model so that a script entry knows which sort of event it is without the frontend having to remember... attribute:: by
Actor id of the speaker; must be in the cast, unless they speak from off panel, when it is the name of somebody who is not drawn.
.. attribute:: text
What is said. Line breaking is the compiler’s job, so write it as one string and do not insert newlines yourself. A word between underscores is stressed, and lettered in bold italic:
I _told_ you... attribute:: prefer
Optional hint about where the balloon should sit. The weakest of all the placement terms – face avoidance and reading order override it.
.. attribute:: kind
Which sort of balloon carries it.
.. attribute:: off_panel
Whether the speaker is off panel:
true, or the side of the frame they are on. The tail then ends on the frame – on that side, or, with none named, on the nearer of left and right to where the balloon is put... attribute:: size
smallfor a line muttered, said under the breath or weakly: smaller type, in a balloon with the room it would have had.Script order is reading order, and reading order is a hard constraint. Reorder these and you reorder the panel.
.. py:attribute:: SayEvent.verb
- module:
scenet.ir
- type:
~typing.Literal[‘say’]
.. py:attribute:: SayEvent.by
- module:
scenet.ir
- type:
~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable)]
.. py:attribute:: SayEvent.text
- module:
scenet.ir
- type:
~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable), ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._balanced)]
.. py:attribute:: SayEvent.prefer
- module:
scenet.ir
- type:
~scenet.ir.PlacementZone | None
.. py:attribute:: SayEvent.kind
- module:
scenet.ir
- type:
~scenet.ir.BalloonKind
.. py:attribute:: SayEvent.off_panel
- module:
scenet.ir
- type:
bool | ~scenet.ir.Side
.. py:attribute:: SayEvent.size
- module:
scenet.ir
- type:
~scenet.ir.TypeSize
.. py:method:: SayEvent.check_off_panel(value)
- module:
scenet.ir
- classmethod:
`true`, `false` or a side, and one finding for anything else. Validated as a plain union, a wrong value failed both members and was reported twice, once as not a boolean and once as not a side, when it is one mistake. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`object\``
.. py:class:: SettingSpec
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictWhere and when the panel happens, as tonal masses rather than drawn geometry.
.. attribute:: horizon
Where the ground meets what is behind it.
.. attribute:: masses
The backdrop, back to front. Written directly, or produced by naming a place in the surface syntax.
.. attribute:: time
When it happens, which shifts the value ladder.
.. attribute:: weather
What the air is doing.
There is no
placefield here, deliberately.place: docksis surface syntax that the frontend expands into exactly the mass list an author could have written themselves – the same treatmentalice left_of bobgets, which reaches the IR as a- class:
Relation <scenet.ir.Relation>and never as text. That is what keeps a preset a library for convenience rather than a second, opaque format: by the time anything downstream sees a backdrop, there is one representation of it.
A panel with no masses and clear weather has no backdrop at all, which is what every panel written before this block existed still gets.
.. admonition:: Example
from scenet import parse_panel panel = parse_panel(“setting: {place: docks, time: night}”) panel.setting.time.value, len(panel.setting.masses) > 0 (‘night’, True)
.. py:attribute:: SettingSpec.horizon
- module:
scenet.ir
- type:
~scenet.ir.Horizon
.. py:attribute:: SettingSpec.masses
- module:
scenet.ir
- type:
tuple[~scenet.ir.Mass, …]
.. py:attribute:: SettingSpec.time
- module:
scenet.ir
- type:
~scenet.ir.TimeOfDay
.. py:attribute:: SettingSpec.weather
- module:
scenet.ir
- type:
~scenet.ir.Weather
.. py:property:: SettingSpec.is_bare
- module:
scenet.ir
- type:
bool
no masses, and nothing in the air.
- type:
Whether there is nothing to draw
.. py:class:: SfxEvent
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictA sound effect: letters that are part of the picture.
BLAMis not dialogue. Comics letter sound as art – big, angled, outlined, near where the sound is – in a display face, not in the balloon face, and with no balloon... attribute:: verb
Always
sfx, written as- sfx: {...}... attribute:: text
The sound, lettered exactly as written. No exclamation mark is added – Comicraft’s glossary: sound effects are not exclamations – and an underscore is not emphasis here, just an underscore.
.. attribute:: source
Written
from:. The actor the sound comes from; the effect is placed near them. Must be in the cast... attribute:: prefer
Where it would like to sit, for an effect with no source – or as a pull on one that has.
.. attribute:: size
How loud:
small,mediumorlarge... attribute:: rotate
Degrees, clockwise, -45 to 45. Comics angle their sound effects; the default is level, and the angle is the author’s to choose.
.. attribute:: arc
Degrees the line of letters bends through, -120 to 120. Positive bows the middle up, negative bows it down.
.. attribute:: hollow
Outline only, no fill, so the art shows through the letters – what letterers call an open effect.
Placed by candidates and cost, never at a coordinate. It never covers a face, and balloons pay to cover it, as they pay to cover emanata. It takes its number in the script’s one reading order, which is what a reader of the text follows, but it is exempt from the geometric reading-order rule: a sound sits where the sound is.
.. admonition:: Example
from scenet.ir import SfxEvent SfxEvent.model_validate({“text”: “BLAM”, “from”: “bob”}).source ‘bob’
.. py:attribute:: SfxEvent.verb
- module:
scenet.ir
- type:
~typing.Literal[‘sfx’]
.. py:attribute:: SfxEvent.text
- module:
scenet.ir
- type:
~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable)]
.. py:attribute:: SfxEvent.source
- module:
scenet.ir
- type:
str | None
.. py:attribute:: SfxEvent.prefer
- module:
scenet.ir
- type:
~scenet.ir.PlacementZone | None
.. py:attribute:: SfxEvent.size
- module:
scenet.ir
- type:
~scenet.ir.SfxSize
.. py:attribute:: SfxEvent.rotate
- module:
scenet.ir
- type:
float
.. py:attribute:: SfxEvent.arc
- module:
scenet.ir
- type:
float
.. py:attribute:: SfxEvent.hollow
- module:
scenet.ir
- type:
bool
.. py:class:: SfxSize
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumHow big a sound effect is lettered, as a multiple of the dialogue type size.
Size
Times the dialogue size
small1.6
medium2.6
large4
A multiple of the type size rather than of the figure, so an effect reads at
long_shotas well as atclose_up: a sound does not get quieter because the camera stepped back. Three steps, not a number, for the reason every other size in the language is named – the author says how loud, the compiler says how big... py:attribute:: SfxSize.SMALL
- module:
scenet.ir
- value:
‘small’
.. py:attribute:: SfxSize.MEDIUM
- module:
scenet.ir
- value:
‘medium’
.. py:attribute:: SfxSize.LARGE
- module:
scenet.ir
- value:
‘large’
.. py:method:: SfxSize.new(value)
- module:
scenet.ir
.. py:class:: ShotType
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumHow tightly the camera frames the cast.
Ordered from widest to tightest, and the order is enforced by a test: reading down the ladder, the figure never gets smaller.
A shot type is defined by two things in two different units. The crop landmark is anatomical – the waist, the chest, the shoulders – which is what stops a shot type baking in one body and one pose; naming a fraction of panel height instead would do exactly that. The headroom is a plain fraction of panel height, because it is about composition within the frame rather than anatomy.
docs/reference/shot_types.mdis normative.The requested shot is an upper bound on tightness, not a promise. If the cast cannot fit across the panel at that framing the camera retreats, and says so in
- attr:
CompileResult.notes <scenet.pipeline.CompileResult.notes>.
.. admonition:: Example
from scenet import ShotType ShotType(“close_up”) <ShotType.CLOSE_UP: ‘close_up’>
.. py:attribute:: ShotType.LONG_SHOT
- module:
scenet.ir
- value:
‘long_shot’
.. py:attribute:: ShotType.WIDE
- module:
scenet.ir
- value:
‘wide’
.. py:attribute:: ShotType.FULL_SHOT
- module:
scenet.ir
- value:
‘full_shot’
.. py:attribute:: ShotType.MEDIUM_FULL
- module:
scenet.ir
- value:
‘medium_full’
.. py:attribute:: ShotType.COWBOY
- module:
scenet.ir
- value:
‘cowboy’
.. py:attribute:: ShotType.MEDIUM_SHOT
- module:
scenet.ir
- value:
‘medium_shot’
.. py:attribute:: ShotType.MEDIUM_CLOSE_UP
- module:
scenet.ir
- value:
‘medium_close_up’
.. py:attribute:: ShotType.CLOSE_UP
- module:
scenet.ir
- value:
‘close_up’
.. py:attribute:: ShotType.BIG_CLOSE_UP
- module:
scenet.ir
- value:
‘big_close_up’
.. py:attribute:: ShotType.EXTREME_CLOSE_UP
- module:
scenet.ir
- value:
‘extreme_close_up’
.. py:method:: ShotType.new(value)
- module:
scenet.ir
.. py:class:: Spans
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumHow much of the panel’s width a mass covers.
Resolved to an extent in the frontend, and that is not cosmetic.
CLAUDE.mdrequires any construct that would reintroduce a left/right disjunction to resolve it before the solver, because Cassowary cannot express “A left of B or B left of A”. A span is an absolute extent rather than a relation, which is what stops masses becoming an unorderedbeside... py:attribute:: Spans.FULL
- module:
scenet.ir
- value:
‘full’
.. py:attribute:: Spans.LEFT
- module:
scenet.ir
- value:
‘left’
.. py:attribute:: Spans.CENTRE
- module:
scenet.ir
- value:
‘center’
.. py:attribute:: Spans.RIGHT
- module:
scenet.ir
- value:
‘right’
.. py:property:: Spans.fractions
- module:
scenet.ir
- type:
tuple[float, float]
The extent as
(start, end)fractions of panel width.leftandrightoverlap slightly in the middle. Butting them exactly would leave a seam down the centre of the panel wherever both are used at the same plane, which reads as a mistake rather than as two masses... admonition:: Example
from scenet.ir import Spans Spans.FULL.fractions (0.0, 1.0)
.. py:method:: Spans.new(value)
- module:
scenet.ir
.. py:class:: StackedPanel
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictOne panel in a column.
Written as the panel’s name alone, or as
{use: name, height: 2}to give it a larger share of the column... attribute:: use
The name of a panel under
panels:... attribute:: height
Its share of the column’s height, relative to the other panels in it.
.. attribute:: insets
Panels set into its corners.
.. py:attribute:: StackedPanel.use
- module:
scenet.ir
- type:
str
.. py:attribute:: StackedPanel.height
- module:
scenet.ir
- type:
float
.. py:attribute:: StackedPanel.insets
- module:
scenet.ir
- type:
tuple[~scenet.ir.Inset, …]
.. py:class:: Strict
- module:
scenet.ir
Bases: :py:class:
~pydantic.main.BaseModelReject unknown keys everywhere.
A misspelled key that is silently ignored produces a panel that is subtly wrong with no indication of why, which is the worst possible failure for a language meant to be precise.
Non-finite numbers are refused for the same reason.
.infand.nanare valid YAML floats, but every number in a document is a length, a weight or a fraction, and an infinite one reached the solver – where kiwisolver ended the interpreter without an exception to report.
.. py:class:: Tier
- module:
scenet.ir
Bases: :py:class:
~scenet.ir.StrictA row of panels read left to right, or of columns each read top to bottom.
Columns are how a tall panel beside a stack of short ones is written. The stack is read down before the page is read across, which is what readers do when a panel spanning the tier blocks the way across (Cohn, Navigating Comics, 2013).
A tier of panels can lean the gutters between them by
slantdegrees, for a beat that should not sit square: each gutter tilts about its centre at the tier’s mid-height, neighbours share the cut, and the tier’s outer edges stay upright... attribute:: height
Its share of the page’s height, relative to the other tiers.
.. attribute:: panels
The panels in it, in reading order.
.. attribute:: columns
The columns in it, left to right. A tier has
panelsorcolumns... attribute:: slant
How far the gutters between its panels lean from upright, in degrees, from -30 to 30. Positive leans the top of each gutter to the right.
.. py:attribute:: Tier.height
- module:
scenet.ir
- type:
float
.. py:attribute:: Tier.panels
- module:
scenet.ir
- type:
tuple[~scenet.ir.PanelPlacement, …]
.. py:attribute:: Tier.columns
- module:
scenet.ir
- type:
tuple[~scenet.ir.Column, …]
.. py:attribute:: Tier.slant
- module:
scenet.ir
- type:
float
.. py:method:: Tier.check_one_kind()
- module:
scenet.ir
A tier is a row of panels or a row of columns: never both, never neither.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``
.. py:method:: Tier.check_slant()
- module:
scenet.ir
A slant leans the gutters between panels, so it needs some to lean.
Refused rather than ignored where it would do nothing, or something undefined: a column’s gutters run across it, and an inset is set into a rectangular corner.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~typing.Self``
.. py:property:: Tier.placed
- module:
scenet.ir
- type:
tuple[tuple[str, tuple[str | int, …]], …]
Each panel’s name and path within the tier, insets included, in reading order.
.. py:class:: TimeOfDay
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhen the panel happens, which shifts the whole value ladder.
Each time supplies two numbers – the value of the foreground and the value of the atmosphere – and the planes are spaced evenly between them. So
nightis not a blue filter over a daytime panel: it is a darker, more compressed ladder, which is what night actually does to a drawn scene. The ladder stays monotonic in depth at every time of day, by construction rather than by tuning... py:attribute:: TimeOfDay.DAWN
- module:
scenet.ir
- value:
‘dawn’
.. py:attribute:: TimeOfDay.DAY
- module:
scenet.ir
- value:
‘day’
.. py:attribute:: TimeOfDay.DUSK
- module:
scenet.ir
- value:
‘dusk’
.. py:attribute:: TimeOfDay.NIGHT
- module:
scenet.ir
- value:
‘night’
.. py:method:: TimeOfDay.new(value)
- module:
scenet.ir
.. py:class:: Weather
- module:
scenet.ir
Bases: :py:class:
~enum.StrEnumWhat the air is doing between the reader and the panel.
cloudsandfogare first-class stuff in COCO-Stuff, so this vocabulary did not have to be invented either.fogrenders as a turbulence veil over the backdrop;rainandsnowadd that veil as cloud and put falling marks over everything, because weather is between the reader and the figures rather than behind them... py:attribute:: Weather.CLEAR
- module:
scenet.ir
- value:
‘clear’
.. py:attribute:: Weather.RAIN
- module:
scenet.ir
- value:
‘rain’
.. py:attribute:: Weather.FOG
- module:
scenet.ir
- value:
‘fog’
.. py:attribute:: Weather.SNOW
- module:
scenet.ir
- value:
‘snow’
.. py:method:: Weather.new(value)
- module:
scenet.ir
.. py:function:: check_placements(layout, panels)
- module:
scenet.ir
Check that every placement names a panel, and that none is placed twice.
A panel that is on no page is allowed: it may exist only to be inherited from.
- type layout:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.PageLayout``
- param layout:
The validated pages.
- type panels:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`str`]`
- param panels:
The names the document’s
panels:defines.- raises RuleViolationError:
Rule
page-layout, located at the placement at fault.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:obj\:\None``
scenet.places#
The named-place library. A preset expands into a mass list an author could have written
themselves, which is what keeps it a library rather than a second, opaque format – and
the expansion happens in the frontend, so nothing downstream ever sees a place.
.. py:module:: scenet.places
The place library: named settings, and what each expands into.
The thing an author wants to write is where the scene is, not a list of shapes. So the headline surface is a named place:
setting:
place: docks
The rule that keeps that honest: a preset expands into a mass list the author could
have written themselves, and is never a second opaque format. A library for
convenience, not a parallel language. The expansion happens in the frontend, so by the
time anything downstream sees a backdrop there is exactly one representation of it –
the same treatment alice left_of bob gets on its way to a
- class:
Relation <scenet.ir.Relation>.Free prose is deliberately not offered.
setting: "a rainy street corner at midnight"needs language understanding, andfrontends/script_front.pyalready refuses to interpret prose on the grounds that guessing produces panels that are confidently wrong. A named place is the honest middle: it reads like a description and resolves deterministically.Within a place, masses are listed back to front. Draw order comes from the plane, so the listing order only decides ties within one plane – but reading the list in the order it will be painted is what makes a preset reviewable.
.. py:data:: PLACES
- module:
scenet.places
- type:
dict[~scenet.places.Place, tuple[~scenet.ir.Mass, …]]
- value:
{Place.ALLEY: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.BUILDING: ‘building’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.LEFT: ‘left’>), Mass(kind=<MassKind.BUILDING: ‘building’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.RIGHT: ‘right’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.BUILDING: ‘building’>, plane=<Plane.FOREGROUND: ‘foreground’>, spans=<Spans.LEFT: ‘left’>)), Place.DESERT: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.SOLID: ‘solid’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.RIGHT: ‘right’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>)), Place.DOCKS: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.BUILDING: ‘building’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.LEFT: ‘left’>), Mass(kind=<MassKind.WATER: ‘water’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.STRUCTURAL: ‘structural’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.RIGHT: ‘right’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>)), Place.FIELD: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.PLANT: ‘plant’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>)), Place.FOREST: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.PLANT: ‘plant’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.PLANT: ‘plant’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.LEFT: ‘left’>), Mass(kind=<MassKind.PLANT: ‘plant’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.RIGHT: ‘right’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>)), Place.MOUNTAIN: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.SOLID: ‘solid’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.SOLID: ‘solid’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.LEFT: ‘left’>), Mass(kind=<MassKind.PLANT: ‘plant’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.RIGHT: ‘right’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>)), Place.OFFICE: (Mass(kind=<MassKind.WALL: ‘wall’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.WINDOW: ‘window’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.CENTRE: ‘center’>), Mass(kind=<MassKind.CEILING: ‘ceiling’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.FLOOR: ‘floor’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.FURNITURE: ‘furniture’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>)), Place.ROOM: (Mass(kind=<MassKind.WALL: ‘wall’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.WINDOW: ‘window’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.RIGHT: ‘right’>), Mass(kind=<MassKind.CEILING: ‘ceiling’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.FLOOR: ‘floor’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.FURNITURE: ‘furniture’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.LEFT: ‘left’>)), Place.SHORE: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.WATER: ‘water’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>)), Place.STREET: (Mass(kind=<MassKind.SKY: ‘sky’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.BUILDING: ‘building’>, plane=<Plane.FAR: ‘far’>, spans=<Spans.FULL: ‘full’>), Mass(kind=<MassKind.BUILDING: ‘building’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.LEFT: ‘left’>), Mass(kind=<MassKind.BUILDING: ‘building’>, plane=<Plane.MID: ‘mid’>, spans=<Spans.RIGHT: ‘right’>), Mass(kind=<MassKind.GROUND: ‘ground’>, plane=<Plane.NEAR: ‘near’>, spans=<Spans.FULL: ‘full’>))}
What each place is made of. Every entry here is a plain mass list, and a test proves it: whatever a preset produces, an author could have typed.
.. py:class:: Place
- module:
scenet.places
Bases: :py:class:
~enum.StrEnumA named setting, expanded into masses by the frontend.
Ten to start with, chosen to span the distinctions that change how a backdrop is built rather than to be a catalogue: exterior and interior, built and natural, open and enclosed.
alleyis the one with a foreground mass, which is what makes it read as a place you are standing in rather than looking at... admonition:: Example
from scenet.places import PLACES, Place [mass.kind.value for mass in PLACES[Place.SHORE]] [‘sky’, ‘water’, ‘ground’]
.. py:attribute:: Place.ALLEY
- module:
scenet.places
- value:
‘alley’
.. py:attribute:: Place.DESERT
- module:
scenet.places
- value:
‘desert’
.. py:attribute:: Place.DOCKS
- module:
scenet.places
- value:
‘docks’
.. py:attribute:: Place.FIELD
- module:
scenet.places
- value:
‘field’
.. py:attribute:: Place.FOREST
- module:
scenet.places
- value:
‘forest’
.. py:attribute:: Place.MOUNTAIN
- module:
scenet.places
- value:
‘mountain’
.. py:attribute:: Place.OFFICE
- module:
scenet.places
- value:
‘office’
.. py:attribute:: Place.ROOM
- module:
scenet.places
- value:
‘room’
.. py:attribute:: Place.SHORE
- module:
scenet.places
- value:
‘shore’
.. py:attribute:: Place.STREET
- module:
scenet.places
- value:
‘street’
.. py:method:: Place.new(value)
- module:
scenet.places
scenet.emphasis#
How a stressed word is written: between underscores, by Markdown’s rules for them. Used by the IR to refuse emphasis that is never closed, and by the solver to decide which face each character is measured and drawn in – one function, so the two cannot disagree.
.. py:module:: scenet.emphasis
Emphasis in lettering: the words a script underlines, and a letterer sets in bold italic.
Blambot’s Comic Book Grammar & Tradition: “There’s almost no plain bold in comics
dialogue. Typically, bold italic is used when emphasis is placed on a word.” Dark Horse’s
script format asks writers to underline the words they want stressed. Plain text has no
underline, so an author writes the word between underscores – I _told_ you – which is
what this module reads.
Underscores, and only underscores. Markdown’s other marker, *, starts an alias in
YAML when it opens a plain value (text: *told* you does not parse), and it is one of the
characters a typed grawlix is made of. An underscore has neither problem.
The rules are Markdown’s for an underscore, which is what keeps snake_case literal:
an underscore opens a span when nothing alphanumeric is before it and something other than a space is after it;
inside a span, an underscore closes it when something other than a space is before it and nothing alphanumeric is after it;
any other underscore is just an underscore – so is one beside another, as in
__init__– and\_writes one anywhere;spans do not nest, and may run across words:
_told you_.
A span opened and never closed is refused rather than guessed at. It is almost always a missing underscore, and setting the rest of the line in bold italic would be a confident wrong answer.
Pure and dependency-free on purpose: the IR uses it to refuse an unclosed span while the source is still in view, and the solver uses it to decide which face each character is measured and drawn in. The two cannot disagree, because they call the same function.
.. py:data:: MARKER
- module:
scenet.emphasis
- value:
‘_’
What opens and closes a span.
.. py:exception:: EmphasisError
- module:
scenet.emphasis
Bases: :py:class:
ValueErrorA span was opened and never closed.
.. attribute:: position
Index of the opening underscore in the text as written.
.. py:method:: EmphasisError.init(text, position)
- module:
scenet.emphasis
Build the error, naming where the span opened.
- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
The text as written.
- type position:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- param position:
Index of the opening underscore.
.. py:class:: Span
- module:
scenet.emphasis
Bases: :py:class:
objectA stretch of text, emphasised or not.
.. attribute:: text
What is lettered, markers and escapes already removed.
.. attribute:: emphasised
Whether it is set in the emphasis face.
.. py:attribute:: Span.text
- module:
scenet.emphasis
- type:
str
.. py:attribute:: Span.emphasised
- module:
scenet.emphasis
- type:
bool
.. py:method:: Span.init(text, emphasised)
- module:
scenet.emphasis
.. py:function:: parse(text)
- module:
scenet.emphasis
Split text into emphasised and plain spans.
- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
A line of dialogue or a caption, as the author wrote it.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`~scenet.emphasis.Span`, :py:data:`…<Ellipsis>`]`
- returns:
The spans in order, each non-empty, adjacent ones never alike. Text with no marker in it is one plain span.
- raises EmphasisError:
A span was opened and never closed.
.. admonition:: Example
from scenet.emphasis import parse [(span.text, span.emphasised) for span in parse(“I told you”)] [(‘I ‘, False), (‘told’, True), (’ you’, False)]
.. py:function:: plain(text)
- module:
scenet.emphasis
The text as it is read: markers and escapes removed.
- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
As the author wrote it.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
What is lettered.
- raises EmphasisError:
A span was opened and never closed.
.. admonition:: Example
from scenet.emphasis import plain plain(“I told you”) ‘I told you’
scenet.lettering#
An author’s lettering face: reading the font files a document declares, and what stands in for a face it does not name.
.. py:module:: scenet.lettering
An author’s lettering face, read from the font files a document declares.
The shipped face is Source Sans Pro, which THIRD_PARTY_NOTICES.md already calls a
placeholder. The faces letterers actually use – Blambot’s, Comicraft’s – are commercial
or free only on their own terms, so the project can never ship one; an author can declare
one. lettering: {font: ...} names the files, and this module reads them.
Two choices are made here and nowhere else:
A font is known by its bytes. Files are cached by the digest of what is in them, not by where they are, so a file replaced in place – the playground does it on every upload – is read again; and Panel Core records the digest, so a drawing can refuse a file that merely shares a name with the one that was measured.
A face the document does not name stands in from one it does. Italic captions fall back to the regular face, emphasis to the italic and then the regular: a family drawn from one file is a whole family, which a mix of the author’s face and the shipped one would not be. The compiler says so when a stand-in is actually used. The display face is the exception: sound effects are not text, so an author’s text faces never stand in for it, and it stays Bangers unless the document names one of its own.
Every failure – a path that is absolute or has no folder to be read from, a file that is
missing, a file that is not a font – is rule font-file, located at the face it names.
.. py:data:: FONT_RULE
- module:
scenet.lettering
- value:
‘font-file’
The rule every font fault is reported under.
.. py:class:: Lettering
- module:
scenet.lettering
Bases: :py:class:
objectA panel’s lettering family, read.
.. attribute:: typeface
Every face, the author’s where they named one.
.. attribute:: declared
The faces the document named a file for. Empty when it named none and letters in the shipped family.
.. py:attribute:: Lettering.typeface
- module:
scenet.lettering
- type:
~scenet.solve.text.Typeface
.. py:attribute:: Lettering.declared
- module:
scenet.lettering
- type:
frozenset[~scenet.ir.Face]
.. py:method:: Lettering.stands_in(face)
- module:
scenet.lettering
Whether
faceis set in another face, because the document named no file for it.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
.. py:method:: Lettering.init(typeface, declared=frozenset({}))
- module:
scenet.lettering
.. py:function:: load_font(declared, base, *, loc)
- module:
scenet.lettering
Read one declared font file.
- type declared:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param declared:
The path as the document wrote it.
- type base:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path` | :py:obj:`None``
- param base:
The document’s folder.
- type loc:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`str` | :py:class:`int`, :py:data:`…<Ellipsis>`]`
- param loc:
Where in the document it was written, for the finding.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics``
- returns:
Its metrics, shared with every other document declaring the same bytes.
- raises PanelSyntaxError:
Rule
font-file. The message names the path as written, never as resolved: findings are output too, and an absolute path in one would make it differ between two checkouts.
.. py:function:: typeface_for(spec, base)
- module:
scenet.lettering
The family a panel letters in: the shipped one, or the files it declares.
- type spec:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.LetteringSpec``
- param spec:
The panel’s
letteringblock.- type base:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path` | :py:obj:`None``
- param base:
The document’s folder, or
Nonefor text with no file behind it.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.lettering.Lettering``
- returns:
The family, and which faces were named.
- raises PanelSyntaxError:
Rule
font-file, for the first face that cannot be read.
.. admonition:: Example
from scenet.ir import LetteringSpec from scenet.lettering import typeface_for typeface_for(LetteringSpec(), None).declared frozenset()
scenet.paths#
Files a document names, found beside the document – never by an absolute path.
.. py:module:: scenet.paths
Files a document names, found beside the document.
A document may point at a file it does not contain – a lettering face now, an image to letter over later (#70). Every such path is read relative to the folder the document is in, the way a link in a web page is, and never as an absolute path. That is what lets a document and the files it names travel together and compile the same anywhere, and what stops a server compiling documents it was sent from being steered at files of its own.
The folder is the document’s, not the working directory’s: scenet build comics/one.panel.yaml reads fonts/x.ttf from comics/fonts/, wherever it was run
from. Text compiled with no file behind it has no folder, and can name no file unless
the caller says which folder it belongs to.
Nothing here reaches the output. A resolved path is used to open a file and is then forgotten; what a Core records about a font is what is in it.
.. py:function:: resolve_relative(declared, base, *, what, rule, loc=())
- module:
scenet.paths
Resolve a path a document wrote against the folder the document is in.
- type declared:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param declared:
The path as written, with
/between folders.- type base:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path` | :py:obj:`None``
- param base:
The document’s folder, or
Nonewhen the text has no file behind it.- type what:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param what:
What the file is, for the message:
font, say.- type rule:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param rule:
The rule a bad path breaks, for the finding.
- type loc:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`str` | :py:class:`int`, :py:data:`…<Ellipsis>`]`
- param loc:
Where in the document the path was written.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path``
- returns:
The file’s path. Not checked to exist – whoever opens it says what it found.
- raises PanelSyntaxError:
The path is empty or absolute, or there is no folder to read it from.
.. admonition:: Example
from pathlib import Path from scenet.paths import resolve_relative found = resolve_relative(“fonts/a.ttf”, Path(“comic”), what=”font”, rule=”font-file”) found.as_posix() ‘comic/fonts/a.ttf’