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.StrEnum

Where 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 center will 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.StrEnum

What 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

speech

rounded rectangle

tapered pointer

thought

ellipse

trail of bubbles

whisper

dashed rounded rectangle

tapered pointer

shout

jagged 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.StrEnum

The 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.Strict

How the panel is framed.

.. attribute:: shot

Requested framing; an upper bound on tightness, see

class:

ShotType <scenet.ir.ShotType>.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.ShotType``

.. attribute:: angle

Camera height, see :class:CameraAngle <scenet.ir.CameraAngle>.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~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.Strict

One 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: {...}.

type:
sphinx_autodoc_typehints_type:

\:py\:data\:\~typing.Literal`\ \[:sphinx_autodoc_typehints_value:`’caption’`]`

.. attribute:: text

What the box says. As with dialogue, line breaking is computed, and a word between underscores is stressed.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: kind

What the box is doing, which decides how it is set.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.CaptionKind``

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.CaptionTone``

.. attribute:: prefer

Where it would like to sit, a place on the panel. Unwritten, it is None, and the caption sits where a locale caption conventionally goes: where reading starts, top_left, or top_right in a comic read right to left.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.PlacementZone` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: by

Who is speaking, for a spoken caption only.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

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.

by is 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 | None

.. 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 by rather than on the whole caption, so the finding points at the by: to delete. Fields are validated in the order they are declared, so kind has been by now; if it failed, there is no kind to hold by to, and the finding about kind is the one to report.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

returns:

The speaker, unchanged.

raises ValueError:

by was 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.StrEnum

What 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

locale

Location and time – “Midnight. The docks.”

Italic

monologue

A character’s inner voice

Italic

spoken

Off-panel dialogue

Roman, in quotation marks

editorial

The voice of the writer or editor

Italic

monologue has 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.

spoken only, 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.StrEnum

The 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 #eeeeee and 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

#ffffff

the paper the panel is printed on

ink

pale

#adadad

the day row of the value ladder, far plane

ink

ink

#090909

the day row of the value ladder, foreground

paper

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. The day row 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 time would make the contrast table a function of the panel and the legibility floor unenforceable.

ink produces 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 yellow locale caption 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.Strict

One character present in the panel: a puppet Scenet poses, or a figure a picture draws.

.. attribute:: reference

Name of a puppet in the library. This is what gets drawn; the key this member is filed under in cast is the actor id used everywhere else. None for a figure.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: pose

Named pose from that puppet’s declared set.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Mark`, :py:data:`…<Ellipsis>`]`

.. attribute:: at

Preferred horizontal anchor.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.AnchorX``

.. attribute:: facing

Which way the figure is turned.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Facing``

.. attribute:: figure

Instead of reference: a figure the panel’s supplied picture draws, by the name its artwork contract gives it (#71). Nobody poses or places it – the artist did – so none of the keys above applies to it, and every one is refused beside it.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

The split between actor id and reference is 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 | None

.. 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:attribute:: CastMember.figure

module:

scenet.ir

type:

~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable)] | None

.. py:method:: CastMember.names_a_puppet_or_a_figure(data, handler)

module:

scenet.ir

classmethod:
Require one of `reference` and `figure`, reported as `reference` missing.

Both are optional to the model, so pydantic alone would accept a member that
names neither. Saying so as `reference` being missing -- pydantic's own error, at
the place it always was -- keeps every finding a puppet's member gave before
figures existed exactly as it was, and lets a misspelt `referecne` still be
folded into "did you mean 'reference'?".

:sphinx_autodoc_typehints_rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~scenet.ir.CastMember\``

.. py:property:: CastMember.is_figure :module: scenet.ir :type: bool

Whether this member is a figure a picture draws, rather than a puppet.

.. 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.Strict

Panels 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: panels

The panels in it, top to bottom.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.StackedPanel`, :py:data:`…<Ellipsis>`]`

.. 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.StrEnum

Which 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:: Direction

module:

scenet.ir

Bases: :py:class:~enum.StrEnum

Which way a comic is read: its progression, not the direction of its text.

ltr reads from the top left, as Western comics do; rtl from the top right, as manga do – the panels on a page and in a strip, the pages side by side, and the balloons and captions in a panel. The words in a balloon are not touched: a manga translated into English still reads right to left while each line reads left to right.

It is the whole document’s, written once, as EPUB’s page-progression-direction is per book, whose words these are. Only what reading decides follows it. The scene is never mirrored: figures, gaze, staging, tails and sound effects stay as staged, and every word that names a place on the panel – at:, left_of, facing:, prefer:, a side for off_panel, an inset’s corner – means the same place either way.

.. py:attribute:: Direction.LTR

module:

scenet.ir

value:

‘ltr’

.. py:attribute:: Direction.RTL

module:

scenet.ir

value:

‘rtl’

.. py:method:: Direction.new(value)

module:

scenet.ir

.. py:class:: Face

module:

scenet.ir

Bases: :py:class:~enum.StrEnum

Which 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

regular

Dialogue, and spoken captions

italic

Every other caption kind

bold_italic

Emphasis, in either – Blambot’s rule for a stressed word

display

Sound 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.StrEnum

Which 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:: Fit

module:

scenet.ir

Bases: :py:class:~enum.StrEnum

How a supplied picture fills the panel, keeping its own proportions.

Fit

The picture

SVG’s word

cover

Fills the panel; what overhangs it is cropped, equally on both sides

slice

contain

Is shown whole; the panel shows round it where their shapes differ

meet

Centred either way. A picture is never stretched: its shape is a fact about it, and a figure drawn into it would be stretched with it.

.. py:attribute:: Fit.COVER

module:

scenet.ir

value:

‘cover’

.. py:attribute:: Fit.CONTAIN

module:

scenet.ir

value:

‘contain’

.. py:method:: Fit.new(value)

module:

scenet.ir

.. py:class:: FontSpec

module:

scenet.ir

Bases: :py:class:~scenet.ir.Strict

The font files a panel is lettered in, each a path relative to the document.

.. attribute:: regular

Dialogue, and spoken captions. Written alone – font: path – it is the only face, and stands in for the others.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: italic

Every other caption kind. Left out, captions are set in regular.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: bold_italic

Emphasis. Left out, emphasis is set in italic when there is one, in regular when there is not – and a note says so when it happens.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

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.StrEnum

Where 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.Strict

A 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:.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: at

The corner of its parent it sits in, a gutter in from both edges.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Corner``

.. attribute:: size

Its width and height, as a fraction of its parent’s: more than 0, at most 0.5.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: read

Whether it is read before its parent or after it.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.InsetOrder``

.. 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.StrEnum

Whether 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.Strict

How a panel is lettered.

.. attribute:: size

The dialogue type size, in panel units – the units panel.size is 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: font

The font files to letter in, in place of the shipped Source Sans Pro.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.FontSpec` | :sphinx_autodoc_typehints_constant:`None``

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 --deep reports as balloon-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.StrEnum

Something 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

plewds

Droplets flying off the head

sweating: effort, heat, nerves

squeans

Little starbursts and circles over the head

dizzy, drunk, or sick

grawlixes

Symbols over the head standing in for words

swearing

briffits

A 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.Strict

One 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.MassKind``

.. attribute:: plane

How far back it sits, which decides its value and its draw order.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Plane``

.. attribute:: spans

How much of the panel’s width it covers.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Spans``

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.StrEnum

What 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-other and so on, where the -other suffix marks the catch-all inside a supercategory. building-other is 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. Its textile, food and rawmaterial supercategories 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.Strict

The 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`float`, :py:class:`float`]`

.. attribute:: margin

The blank border inside the page edge, on all four sides.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: gutter

The gap between two panels side by side in a tier.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: tier_gutter

The gap between two tiers. Wider than gutter by 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. 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.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

.. py:class:: PageLayout

module:

scenet.ir

Bases: :py:class:~scenet.ir.Strict

Every page of a scene, and the format they share.

.. attribute:: page

The format.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.PageFormat``

.. attribute:: pages

The pages, in order.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.PageSpec`, :py:data:`…<Ellipsis>`]`

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.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

.. py:class:: PageSpec

module:

scenet.ir

Bases: :py:class:~scenet.ir.Strict

One page: tiers, top to bottom.

A page is read tier by tier, left to right within a tier – right to left, for a document whose direction is rtl – 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Tier`, :py:data:`…<Ellipsis>`]`

.. py:attribute:: PageSpec.tiers

module:

scenet.ir

type:

tuple[~scenet.ir.Tier, …]

.. py:class:: PanelIR

module:

scenet.ir

Bases: :py:class:~scenet.ir.Strict

A 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.PanelSpec``

.. attribute:: camera

Framing and angle.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.CameraSpec``

.. attribute:: cast

Actor id to character. Declaration order is not significant; staging decides left-to-right order.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.CastMember`]`

.. attribute:: staging

Spatial and attentional relations between actors.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Relation`, :py:data:`…<Ellipsis>`]`

.. attribute:: script

Dialogue and captions, in reading order.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.SayEvent` | :py:class:`~scenet.ir.CaptionEvent` | :py:class:`~scenet.ir.SfxEvent` | :py:class:`~scenet.ir.SayEvent` | :py:class:`~scenet.ir.CaptionEvent` | :py:class:`~scenet.ir.SfxEvent`, :py:data:`…<Ellipsis>`]`

.. attribute:: lettering

How the lettering is set: its type size, when the author chooses one.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.LetteringSpec``

.. attribute:: description

What the panel shows, in words, for a reader who cannot see it: the author’s, or a comic script’s prose. Carried and never interpreted – nothing is drawn from it. Without one, accessible output says what the panel holds.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: direction

Which way the comic is read. The whole document’s: a scene’s panels and a comic script’s take it from the document, and none may write its own.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Direction``

Validation is strict and total: unknown keys are rejected, every actor id mentioned in staging or script must exist in cast, 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:attribute:: PanelIR.description

module:

scenet.ir

type:

~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable), ~pydantic.functional_validators.BeforeValidator(func=~scenet.ir.as_one_line, json_schema_input_type=PydanticUndefined), ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._said)] | None

.. py:attribute:: PanelIR.direction

module:

scenet.ir

type:

~scenet.ir.Direction

.. 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.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

.. 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.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

.. py:method:: PanelIR.check_figures()

module:

scenet.ir

A figure a picture draws is not posed, placed or staged, and plays one part.

The frontend refuses a puppet’s key written beside figure, since a written default and an absent key look the same here; this is the backstop for an IR built in Python, and the place the rest is decided:

  • a cast is all puppets or all figures (conflicting-cast): staging and the camera place puppets, and would place them over painted faces they cannot see;

  • one figure plays one part (conflicting-cast);

  • no staging relation names a figure (figure-staging): the artist staged them.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

.. py:method:: PanelIR.figures()

module:

scenet.ir

The cast members a supplied picture draws, and the figure each plays.

.. admonition:: Example

from scenet import parse_panel parse_panel(“cast: {ana: {figure: ana_in_red}}”).figures() {‘ana’: ‘ana_in_red’}

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`str`]`

.. py:method:: PanelIR.puppets()

module:

scenet.ir

The cast members Scenet poses, and the puppet each is drawn by.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`str`]`

.. py:property:: PanelIR.drawn_by_its_picture

module:

scenet.ir

type:

bool

Whether everybody in the cast is a figure the panel’s picture draws.

Then nothing is staged, the camera does not run, and the shot is whatever the artist drew.

.. py:method:: PanelIR.ordering_constraints()

module:

scenet.ir

Normalised (left, right) pairs from both left_of and right_of relations.

sphinx_autodoc_typehints_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_at relation 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` | :sphinx_autodoc_typehints_constant:`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’.

sphinx_autodoc_typehints_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.Strict

One 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:.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: width

Its share of the tier’s width, relative to the other panels in the tier.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: insets

Panels set into its corners.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Inset`, :py:data:`…<Ellipsis>`]`

.. 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.Strict

The 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`float`, :py:class:`float`]`

.. attribute:: margin

Inset on all four sides. Balloons are kept inside it; actors may bleed past it, which is ordinary comics practice.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. 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:\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

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.StrEnum

Where 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.StrEnum

How 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, and foreground takes 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.StrEnum

How 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_of and right_of are 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.Strict

One staging fact, written as a sentence.

.. attribute:: subject

Actor id the sentence is about.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: predicate

What relation holds.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Predicate``

.. attribute:: object

The other actor id.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

Authored as alice left_of bob rather 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:\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

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.Strict

One 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.

type:
sphinx_autodoc_typehints_type:

\:py\:data\:\~typing.Literal`\ \[:sphinx_autodoc_typehints_value:`’say’`]`

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: prefer

Optional hint about where the balloon should sit. The weakest of all the placement terms – face avoidance and reading order override it.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.PlacementZone` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: kind

Which sort of balloon carries it.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.BalloonKind``

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\bool` | :py:class:`~scenet.ir.Side``

.. attribute:: size

small for a line muttered, said under the breath or weakly: smaller type, in a balloon with the room it would have had.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.TypeSize``

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.

:sphinx_autodoc_typehints_rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`object\``

.. py:class:: SettingSpec

module:

scenet.ir

Bases: :py:class:~scenet.ir.Strict

Where and when the panel happens: tonal masses, or a picture drawn elsewhere.

.. attribute:: horizon

Where the ground meets what is behind it.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Horizon``

.. attribute:: masses

The backdrop, back to front. Written directly, or produced by naming a place in the surface syntax.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Mass`, :py:data:`…<Ellipsis>`]`

.. attribute:: time

When it happens, which shifts the value ladder.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.TimeOfDay``

.. attribute:: weather

What the air is doing.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Weather``

.. attribute:: image

A picture to draw behind the cast instead of masses: a PNG or JPEG file, relative to the folder the document is in, as a font is. The compiler reads how many pixels it has and nothing else; see :mod:scenet.images.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: fit

How the picture fills the panel. Left out, it is cover.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.Fit` | :sphinx_autodoc_typehints_constant:`None``

There is no place field here, deliberately. place: docks is surface syntax that the frontend expands into exactly the mass list an author could have written themselves – the same treatment alice left_of bob gets, 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:attribute:: SettingSpec.image

module:

scenet.ir

type:

~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~scenet.ir._holdable)] | None

.. py:attribute:: SettingSpec.fit

module:

scenet.ir

type:

~scenet.ir.Fit | None

.. py:method:: SettingSpec.check_backdrop()

module:

scenet.ir

Refuse a picture beside masses, and a fit with no picture to fit.

The frontend says so first, at the line that was written; this holds the same rule for a setting built in Python. A horizon beside a picture is the frontend’s alone to refuse: here its default and a written one look the same.

rtype:

:sphinx_autodoc_typehints_type:\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

returns:

The validated setting.

raises RuleViolationError:

conflicting-setting for masses and a picture, and invalid-field for a fit with nothing to fit.

.. py:property:: SettingSpec.is_bare

module:

scenet.ir

type:

bool

no masses, no picture, nothing in the air.

type:

Whether there is nothing to draw

.. py:class:: SfxEvent

module:

scenet.ir

Bases: :py:class:~scenet.ir.Strict

A sound effect: letters that are part of the picture.

BLAM is 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: {...}.

type:
sphinx_autodoc_typehints_type:

\:py\:data\:\~typing.Literal`\ \[:sphinx_autodoc_typehints_value:`’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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: source

Written from:. The actor the sound comes from; the effect is placed near them. Must be in the cast.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: prefer

Where it would like to sit, for an effect with no source – or as a pull on one that has.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.PlacementZone` | :sphinx_autodoc_typehints_constant:`None``

.. attribute:: size

How loud: small, medium or large.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.SfxSize``

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: arc

Degrees the line of letters bends through, -120 to 120. Positive bows the middle up, negative bows it down.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: hollow

Outline only, no fill, so the art shows through the letters – what letterers call an open effect.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\bool``

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.StrEnum

How big a sound effect is lettered, as a multiple of the dialogue type size.

Size

Times the dialogue size

small

1.6

medium

2.6

large

4

A multiple of the type size rather than of the figure, so an effect reads at long_shot as well as at close_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.StrEnum

How 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.md is 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.StrEnum

How much of the panel’s width a mass covers.

Resolved to an extent in the frontend, and that is not cosmetic. CLAUDE.md requires 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 unordered beside.

.. 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.

left and right overlap 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.Strict

One 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:.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: height

Its share of the column’s height, relative to the other panels in it.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: insets

Panels set into its corners.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Inset`, :py:data:`…<Ellipsis>`]`

.. 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.BaseModel

Reject 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. .inf and .nan are 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.Strict

A row of panels read in turn, 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 slant degrees, 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. attribute:: panels

The panels in it, in reading order: left to right, or right to left for a document read that way.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.PanelPlacement`, :py:data:`…<Ellipsis>`]`

.. attribute:: columns

The columns in it, in reading order, as panels are. A tier has panels or columns.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:class:`~scenet.ir.Column`, :py:data:`…<Ellipsis>`]`

.. 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.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\float``

.. 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.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

.. 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.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\0e5b48c87d846b7f``

.. 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.StrEnum

When 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 night is 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.StrEnum

What the air is doing between the reader and the panel.

clouds and fog are first-class stuff in COCO-Stuff, so this vocabulary did not have to be invented either. fog renders as a turbulence veil over the backdrop; rain and snow add 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:

\:sphinx\_autodoc\_typehints\_alias\:\b93dc045edcaac20``

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.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_constant\:\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, and frontends/script_front.py already 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.StrEnum

A 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. alley is 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

.. py:function:: place_of(masses)

module:

scenet.places

The named place a list of masses is, or None for a list no place expands into.

A place reaches the IR as its masses and nothing else, so this is how a place is named again afterwards: by its masses, whether place: wrote them or an author wrote the same list out by hand. The description reads it, and Panel Core records it.

.. admonition:: Example

place_of(PLACES[Place.DOCKS]) <Place.DOCKS: ‘docks’> place_of(()) is None True

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.places.Place` | :sphinx_autodoc_typehints_constant:`None``

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:ValueError

A 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:object

A stretch of text, emphasised or not.

.. attribute:: text

What is lettered, markers and escapes already removed.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: emphasised

Whether it is set in the emphasis face.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\bool``

.. 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:object

A panel’s lettering family, read.

.. attribute:: typeface

Every face, the author’s where they named one.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.solve.text.Typeface``

.. attribute:: declared

The faces the document named a file for. Empty when it named none and letters in the shipped family.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\frozenset`\ \[:py:class:`~scenet.ir.Face`]`

.. 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 face is set in another face, because the document named no file for it.

sphinx_autodoc_typehints_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:class:`~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`bytes`] | :sphinx_autodoc_typehints_constant:`None``

param base:

The document’s folder, or the files sent with it.

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:

\:sphinx\_autodoc\_typehints\_alias\:\ea93dfc0344fb601``

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:

\:sphinx\_autodoc\_typehints\_alias\:\549df3927f19b525``

param spec:

The panel’s lettering block.

type base:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path` | :py:class:`~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`bytes`] | :sphinx_autodoc_typehints_constant:`None``

param base:

The document’s folder, the files sent with it, or None for text with neither.

rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\1749c300757d1c95``

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, or a picture to letter over (#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 – or hands over the files themselves, by the path the document writes, which is how a server is sent them: it never reads a folder of its own. Both are read the same way, ./art/a.png and art/a.png alike.

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:data:: Folder

module:

scenet.paths

value:

pathlib.Path | collections.abc.Mapping[str, bytes]

the folder it is in, or the files themselves, by the path the document writes.

type:

Where the files a document names are

.. py:function:: check_relative(declared, *, what, rule, loc=())

module:

scenet.paths

Refuse a path that could not be read the same way on every system, or at all.

Everything :func:resolve_relative refuses but the want of a folder: for a path that is kept rather than opened, as Panel Core keeps a picture’s.

raises PanelSyntaxError:

The path is empty or absolute, or has a backslash or a control character in it.

sphinx_autodoc_typehints_rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_constant\:\None``

.. py:function:: read_relative(declared, base, *, what, rule, loc=())

module:

scenet.paths

Read a file a document names, from its folder or from the files sent with it.

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:class:`~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`bytes`] | :sphinx_autodoc_typehints_constant:`None``

param base:

The document’s folder; or the files beside it, by the path the document writes, when it was sent as text; or None when it has neither.

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 every failure is reported under.

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\:\bytes``

returns:

The file’s bytes.

raises PanelSyntaxError:

Anything :func:resolve_relative refuses, or the file is not there, or cannot be read. The message names the path as written, never as resolved: a finding is output too, and a folder in it would differ between two checkouts.

.. admonition:: Example

from scenet.paths import read_relative read_relative(“./art/a.png”, {“art/a.png”: b”…”}, what=”image”, rule=”image-file”) b’…’

.. 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` | :sphinx_autodoc_typehints_constant:`None``

param base:

The document’s folder, or None when 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:

\:sphinx\_autodoc\_typehints\_alias\:\5703ef5fac8d7993``

returns:

The file’s path. Not checked to exist – whoever opens it says what it found.

raises PanelSyntaxError:

The path is empty or absolute, has a backslash or a control character in it, 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’

scenet.images#

A picture to letter over: how big it is, read from its PNG or JPEG header, and nothing else.

.. py:module:: scenet.images

A picture to letter over, read from a file the document names (#70).

setting: {image: art/p01.png} puts a picture drawn elsewhere behind the cast. The solver never sees artwork, so what this module takes from the file is a fact about it, not its content: how many pixels across and how many down, read from the header. The pixels are never decoded.

Two formats, PNG and JPEG, because they are what SVG 2 requires every viewer to draw. They are told apart by their first bytes, never by the file’s name. Both headers take a few lines to read, so no imaging library is involved: one would have to pass the licence gate, and ship in the playground’s Pyodide, to answer two questions.

One more fact is read, and refused rather than used: an EXIF orientation saying the picture is to be shown turned. Renderers disagree on obeying it – Chromium turns an SVG <image> by it, gdk-pixbuf does not unless asked – so a picture carrying one would be upright in one viewer and on its side in the next. EXIF that cannot be read is ignored, as every renderer ignores it.

Every failure – the path, the file, the header, the orientation – is rule image-file, located where the image is named.

.. py:data:: IMAGE_RULE

module:

scenet.images

value:

‘image-file’

The rule every image fault is reported under.

.. py:data:: MediaType

module:

scenet.images

` URI names them.

type:

The two media types, as a `data

alias of :py:obj:~typing.Literal\ [‘image/png’, ‘image/jpeg’]

.. py:class:: SuppliedImage

module:

scenet.images

Bases: :py:class:object

A picture a document names, read.

.. attribute:: href

The path exactly as the document wrote it. A linked SVG points at it by this, so it reaches the output as written and nothing else about the file’s location does.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: media_type

image/png or image/jpeg, from the file’s own first bytes.

type:
sphinx_autodoc_typehints_type:

\:py\:data\:\~typing.Literal`\ \[:sphinx_autodoc_typehints_value:`’image/png’`, :sphinx_autodoc_typehints_value:`’image/jpeg’`]`

.. attribute:: sha256

The digest of its bytes, which is what it is known by – as a font is.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

.. attribute:: width

Pixels across.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\int``

.. attribute:: height

Pixels down.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\int``

.. attribute:: data

The bytes, for a renderer asked to embed them.

type:
sphinx_autodoc_typehints_type:

\:py\:class\:\bytes``

.. py:attribute:: SuppliedImage.href

module:

scenet.images

type:

str

.. py:attribute:: SuppliedImage.media_type

module:

scenet.images

type:

~typing.Literal[‘image/png’, ‘image/jpeg’]

.. py:attribute:: SuppliedImage.sha256

module:

scenet.images

type:

str

.. py:attribute:: SuppliedImage.width

module:

scenet.images

type:

int

.. py:attribute:: SuppliedImage.height

module:

scenet.images

type:

int

.. py:attribute:: SuppliedImage.data

module:

scenet.images

type:

bytes

.. py:method:: SuppliedImage.init(href, media_type, sha256, width, height, data)

module:

scenet.images

.. py:function:: load_image(declared, base, *, loc)

module:

scenet.images

Read the picture a document names, and how big it is.

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:class:`~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`bytes`] | :sphinx_autodoc_typehints_constant:`None``

param base:

The document’s folder, the files sent with it, or None for text with neither.

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 named, for the finding.

rtype:
sphinx_autodoc_typehints_type:

\:sphinx\_autodoc\_typehints\_alias\:\ae70cfb1a12f2eaa``

returns:

The picture, with its size.

raises PanelSyntaxError:

Rule image-file, naming the path as written.

.. admonition:: Example

from scenet.images import load_image photo = bytes.fromhex(“ffd8 ffc0000b080bb80fa001011100 ffd9”) image = load_image(“art/photo.jpg”, {“art/photo.jpg”: photo}, loc=()) image.media_type, image.width, image.height (‘image/jpeg’, 4000, 3000)

.. py:function:: measure(data)

module:

scenet.images

A picture’s media type and size in pixels, from its header.

type data:
sphinx_autodoc_typehints_type:

\:py\:class\:\bytes``

param data:

The file’s bytes.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\tuple`\ \[:py:data:`~typing.Literal`\ \[:sphinx_autodoc_typehints_value:`’image/png’`, :sphinx_autodoc_typehints_value:`’image/jpeg’`], :py:class:`int`, :py:class:`int`]`

returns:

(media_type, width, height).

raises ValueError:

The bytes are not a PNG or JPEG whose size its header gives, or the picture is turned by its EXIF orientation. The message finishes a sentence that begins with the file’s name.

.. admonition:: Example

from scenet.images import measure measure(bytes.fromhex(“ffd8 ffc0000b080bb80fa001011100 ffd9”)) (‘image/jpeg’, 4000, 3000)