Describing a panel: the values#

The enumerations and values of this group, each the word an author writes.

AnchorX#

Import

from scenet import AnchorX

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.1

Stability

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

class scenet.ir.AnchorX[source]#

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

Example

>>> from scenet import AnchorX, compile_source
>>> core = compile_source("cast: {a: {reference: alice, at: left_third}}").core
>>> AnchorX("left_third") is AnchorX.LEFT_THIRD
True
>>> core.actors[0].bounds.centre.x < core.width / 2
True

See also

CastMember, whose at takes one. Predicate, to stage two actors against each other instead.

LEFT_EDGE = 'left_edge'#
LEFT_THIRD = 'left_third'#
CENTRE = 'center'#
RIGHT_THIRD = 'right_third'#
RIGHT_EDGE = 'right_edge'#

BalloonKind#

Import

from scenet import BalloonKind

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.1

Stability

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

class scenet.ir.BalloonKind[source]#

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

Example

>>> from scenet import BalloonKind, compile_source
>>> core = compile_source(
...     "cast: {a: {reference: alice}}\n"
...     "script: [{say: {by: a, text: Psst., kind: whisper}}]"
... ).core
>>> core.balloons[0].kind is BalloonKind.WHISPER
True

See also

SayEvent, whose kind takes one.

SPEECH = 'speech'#
THOUGHT = 'thought'#
WHISPER = 'whisper'#
SHOUT = 'shout'#

CameraAngle#

Import

from scenet import CameraAngle

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.1

Stability

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

class scenet.ir.CameraAngle[source]#

Bases: 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 headroom_for for the exact factors.

Example

>>> from scenet import CameraAngle, compile_source
>>> core = compile_source("camera: {angle: low}\ncast: {a: {reference: alice}}").core
>>> core.camera.angle is CameraAngle.LOW
True

See also

CameraSpec, whose angle takes one. ShotType, the other half of the camera.

LOW = 'low'#
EYE_LEVEL = 'eye_level'#
HIGH = 'high'#

CaptionKind#

Import

from scenet import CaptionKind

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.4

Stability

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

class scenet.ir.CaptionKind[source]#

Bases: 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 BalloonKind.THOUGHT. Both are correct. They are different eras of the same convention, not a duplication.

Example

>>> from scenet import CaptionKind
>>> CaptionKind.LOCALE.is_italic, CaptionKind.SPOKEN.is_italic
(True, False)

See also

CaptionEvent, whose kind takes one. CaptionTone, the box a caption is lettered on.

LOCALE = 'locale'#
MONOLOGUE = 'monologue'#
SPOKEN = 'spoken'#
EDITORIAL = 'editorial'#
property is_italic: bool#

Whether this kind is set in italic. Everything except spoken.

property is_quoted: bool#

Whether this kind takes quotation marks.

spoken only, because it is the one kind where somebody is talking.

CaptionTone#

Import

from scenet import CaptionTone

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.6

Stability

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

class scenet.ir.CaptionTone[source]#

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

warm

#eeeeee

the day row of the value ladder, atmosphere

ink

Drawn from the ladder in `solve/backdrop.py`, not from a second palette. Three of the four 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 CoreCaption.ink – exactly as falling rain’s is.

warm is the classic yellow locale caption, under the colour policy: its value is the grey above, and in a palette with colour it is drawn in that grey’s twin, a pale yellow of the same lightness. In mono it is the grey, which is what a black-and-white reprint does to a yellow caption. The other three are neutral in every palette.

There is no free-form colour here. A fill: taking any string would be the language’s one open vocabulary, and would let an author produce an unreadable box.

Example

>>> from scenet import CaptionEvent, CaptionTone
>>> CaptionEvent(text="Later.", tone="ink").tone is CaptionTone.INK
True

See also

CaptionEvent, whose tone takes one. Palette, which decides what warm is printed in.

PAPER = 'paper'#
PALE = 'pale'#
INK = 'ink'#
WARM = 'warm'#

Direction#

Import

from scenet import Direction

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.12

Stability

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

class scenet.ir.Direction[source]#

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

Example

>>> from scenet import Direction, compile_source
>>> core = compile_source("direction: rtl\ncast: {a: {reference: alice}}").core
>>> core.direction is Direction.RTL
True

See also

render_strip and render_pages, which lay panels out in it.

LTR = 'ltr'#
RTL = 'rtl'#

Facing#

Import

from scenet import Facing

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.1

Stability

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

class scenet.ir.Facing[source]#

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

Example

>>> from scenet import Facing, compile_source
>>> core = compile_source("cast: {a: {reference: alice, facing: left}}").core
>>> Facing("left") is Facing.LEFT, core.actors[0].transform.mirrored
(True, True)

See also

CastMember, whose facing takes one.

LEFT = 'left'#
RIGHT = 'right'#

Mark#

Import

from scenet import Mark

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.8

Stability

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

class scenet.ir.Mark[source]#

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

Example

>>> from scenet import Mark, compile_source
>>> core = compile_source("cast: {a: {reference: alice, marks: [plewds]}}").core
>>> core.actors[0].marks == (Mark.PLEWDS,)
True

See also

CastMember, whose marks lists them.

PLEWDS = 'plewds'#
SQUEANS = 'squeans'#
GRAWLIXES = 'grawlixes'#
BRIFFITS = 'briffits'#

Palette#

Import

from scenet import Palette

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.13

Stability

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

class scenet.ir.Palette[source]#

Bases: StrEnum

What a panel is drawn in: the value ladder in grey, or its twin in colour.

Palette

What it draws

mono

Every value as the grey it is – the default, and what every panel was

tinted

Every value on the ladder in its twin colour: same rung, same hour

Colour is a twin of value, never a replacement. A tinted colour has the OKLab lightness of the grey it stands for, so in monochrome a tinted panel is the mono one, and every decision the compiler makes from a value – which rung a mass takes, whether rain is inked or papered, how a caption is lettered – is made on the grey. Panel Core keeps the grey where it always did and adds the colour beside it.

Only the ladder is tinted: the masses of a setting, the veil and the falling rain. Snow, the paper, the figures and all lettering stay as they are in every palette.

A closed set of names, not a colour field, for the reason CaptionTone is one: an open colour would be the language’s one open vocabulary, and would let a value break the ladder. See colour_for.

Example

>>> from scenet import Palette, compile_source
>>> core = compile_source("palette: tinted\ncast: {a: {reference: alice}}").core
>>> core.palette is Palette.TINTED, core.as_mono().palette is Palette.MONO
(True, True)

See also

PanelCore.as_mono, the same panel in greys. CaptionTone, whose warm a palette colours.

MONO = 'mono'#
TINTED = 'tinted'#

PlacementZone#

Import

from scenet import PlacementZone

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.1

Stability

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

class scenet.ir.PlacementZone[source]#

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

Example

>>> from scenet import PlacementZone, compile_source
>>> core = compile_source(
...     "cast: {a: {reference: alice}}\n"
...     "script: [{say: {by: a, text: Up here., prefer: top_right}}]"
... ).core
>>> PlacementZone("top_right").value
'top_right'
>>> core.balloons[0].box.x > core.width / 2
True

See also

SayEvent, whose prefer takes one: a preference, which a hard rule such as reading order may overrule.

TOP_LEFT = 'top_left'#
TOP_CENTRE = 'top_center'#
TOP_RIGHT = 'top_right'#
MIDDLE_LEFT = 'middle_left'#
MIDDLE_CENTRE = 'middle_center'#
MIDDLE_RIGHT = 'middle_right'#
BOTTOM_LEFT = 'bottom_left'#
BOTTOM_CENTRE = 'bottom_center'#
BOTTOM_RIGHT = 'bottom_right'#
property fractions: tuple[float, float]#

The zone’s centre as a fraction of panel width and height.

Predicate#

Import

from scenet import Predicate

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.1

Stability

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

class scenet.ir.Predicate[source]#

Bases: 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”.

Example

>>> from scenet import Predicate, compile_source
>>> core = compile_source(
...     "cast: {a: {reference: alice}, b: {reference: bob}}\nstaging: [b left_of a]"
... ).core
>>> Predicate("left_of") is Predicate.LEFT_OF
True
>>> core.actor("b").bounds.centre.x < core.actor("a").bounds.centre.x
True

See also

Relation, one predicate between two actors.

LEFT_OF = 'left_of'#
RIGHT_OF = 'right_of'#
IN_FRONT_OF = 'in_front_of'#
BEHIND = 'behind'#
LOOKING_AT = 'looking_at'#
GROUND_SHARED_WITH = 'ground_shared_with'#

SfxSize#

Import

from scenet import SfxSize

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.11

Stability

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

class scenet.ir.SfxSize[source]#

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

Example

>>> from scenet import SfxEvent, SfxSize
>>> SfxEvent(text="BAM", size="large").size is SfxSize.LARGE
True

See also

SfxEvent, whose size takes one.

SMALL = 'small'#
MEDIUM = 'medium'#
LARGE = 'large'#

ShotType#

Import

from scenet import ShotType

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.1

Stability

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

class scenet.ir.ShotType[source]#

Bases: 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 CompileResult.notes.

Example

>>> from scenet import ShotType
>>> ShotType("close_up")
<ShotType.CLOSE_UP: 'close_up'>

See also

CameraSpec, whose shot takes one. Landmark, the crop lines a shot names.

LONG_SHOT = 'long_shot'#
WIDE = 'wide'#
FULL_SHOT = 'full_shot'#
MEDIUM_FULL = 'medium_full'#
COWBOY = 'cowboy'#
MEDIUM_SHOT = 'medium_shot'#
MEDIUM_CLOSE_UP = 'medium_close_up'#
CLOSE_UP = 'close_up'#
BIG_CLOSE_UP = 'big_close_up'#
EXTREME_CLOSE_UP = 'extreme_close_up'#

Side#

Import

from scenet import Side

Defined in

scenet.ir (source)

Install

pip install scenet

Since

0.11

Stability

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

class scenet.ir.Side[source]#

Bases: StrEnum

A side of the panel’s frame: where an off-panel speaker is, or where it bleeds.

An off-panel balloon’s tail ends on the frame on this side – Blambot, Off-Panel Dialogue: “the tail of the balloon generally butts against the panel border”. A panel on a page bleeds past the trim on the sides its placement lists.

Example

>>> from scenet import Side, compile_source
>>> core = compile_source(
...     "cast: {a: {reference: alice}}\n"
...     "script: [{say: {by: z, text: Over here!, off_panel: right}}]"
... ).core
>>> core.balloons[0].off_panel is Side.RIGHT
True

See also

SayEvent, whose off_panel takes one. PanelPlacement, whose bleed lists them.

LEFT = 'left'#
RIGHT = 'right'#
TOP = 'top'#
BOTTOM = 'bottom'#