PanelCore#

Import

from scenet import PanelCore

Defined in

scenet.core (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.core.PanelCore[source]#

Bases: CoreModel

A fully resolved panel: numeric, named, and ready to emit.

The middle tier, and the architectural idea of the project. Every position here is absolute and final, but identifiers survive – which is exactly what separates this from SVG. You can read a Core document, see that alice sits at x=280 with her balloon top-left of her head, change one number, and emit it again.

The approach is borrowed from Vega-Lite, which compiles a high-level grammar into a lower-level one before emitting anything drawable.

format_version#

Bumped when the shape of this document changes incompatibly.

Type:

int

width#

Panel width in panel units.

Type:

float

height#

Panel height in panel units.

Type:

float

actors#

Resolved characters, back to front by depth, and at one depth left to right as staged. The SVG draws them back to front too, but breaks a tie at one depth by id (in_painters_order).

Type:

tuple[CoreActor, ...]

balloons#

Resolved balloons, in reading order.

Type:

tuple[CoreBalloon, ...]

captions#

Resolved caption boxes, in reading order. Balloons and captions share one order sequence, since the reader takes them in one sequence.

Type:

tuple[CoreCaption, ...]

backdrop#

Where the panel is, or None when it says nothing about that – which is every panel written before the setting layer existed.

Type:

CoreBackdrop | None

exclusions#

Areas the lettering kept clear of because something is drawn over them: on a page, the insets set into this panel, ringed by a gutter. The art under them is drawn as if they were not there. Left out of the JSON when empty, so a panel with no inset reads and writes exactly as it always did.

Type:

tuple[Box, ...]

outline#

For a panel in a slanted tier, the shape of its border: four corners, clockwise from the top left, in panel units. The panel is drawn clipped to it, and its lettering stays inside it. Left out of the JSON for a rectangle.

Type:

tuple[tuple[float, float], ...] | None

sfx#

Sound effects, in script order. Left out of the JSON when there are none.

Type:

tuple[CoreSfx, ...]

fonts#

The faces lettered in a font other than the shipped one, by face. A face not listed is the shipped family’s. Left out of the JSON when every face is the shipped one.

Type:

dict[Face, CoreFont]

description#

What the panel shows, in words, for a reader who cannot see it: the author’s, or generated from what it holds. With the labels in order, it is what accessible output reads. Left out of the JSON when unset.

Type:

str | None

figures#

The figures a supplied picture draws, as its artwork contract declares them, whether cast or not. Left out of the JSON when there are none, so every panel without them reads and writes as it always did.

Type:

tuple[CoreFigure, ...]

direction#

Which way the panel is read, which is why its lettering is where it is. Left out of the JSON for ltr, so every panel written before it reads and writes as it always did.

Type:

Direction

camera#

What framed the panel, or None when a supplied picture draws the cast: the artist framed it, and the camera did not run. Left out of the JSON when None.

Type:

CoreCamera | None

palette#

What the panel is drawn in. Each value it tints keeps its grey, and gains its colour beside it. Left out of the JSON for mono, so every panel written before it reads and writes as it always did.

Type:

Palette

open#

For a panel that bleeds past the trim, the sides its frame runs out to the bleed line on: no border is drawn there. Left out of the JSON when empty.

Type:

tuple[Side, ...]

lettering#

For a panel that bleeds, the box its balloons, captions and sound effects keep inside: its frame as it was before bleeding, inset by its margin, so the page’s margin stays the live area. Left out of the JSON otherwise.

Type:

Box | None

Golden-file tests target this tier rather than the SVG, because it changes only when the layout genuinely changes. Diffing SVG text is brittle – a reordered attribute or a different path-rounding convention produces an enormous diff that means nothing.

Example

>>> from scenet import PanelCore, compile_source
>>> core = compile_source("{cast: {a: {reference: alice}}}").core
>>> isinstance(core, PanelCore), core.width, core.height
(True, 1000.0, 1000.0)
>>> core.actor("a").reference
'alice'
>>> core.to_json().splitlines()[0]
'{'

See also

PanelCore.to_json and PanelCore.from_json, the format on disk. render, to draw it.

property bounds: BBox#

The panel rectangle, origin at (0, 0).

face_exclusions()[source]#

Every face lettering kept clear of: the actors’, then the figures’.

Example

>>> from scenet import compile_source
>>> len(compile_source("{cast: {a: {reference: alice}}}").core.face_exclusions())
1
Return type:

tuple[Disc, ...]

speaker(actor_id)[source]#

Who speaks a balloon, wherever they are drawn: a puppet, or a figure a picture draws.

Parameters:

actor_id (str) – The id a balloon names as its speaker.

Return type:

Speaking

Returns:

Their face, and where a tail to them aims – the mouth, or the face’s centre when there is none.

Raises:

UnknownActorError – Nobody in this panel plays that part. Also a KeyError.

as_mono()[source]#

The same panel in monochrome: every colour its palette added, taken back out.

Every value was decided on the grey and its colour only added beside it, so this is exactly the panel compiled with palette: mono. It is what lets a tinted panel be drawn in grey – a black-and-white edition – without the emitter choosing anything.

Return type:

PanelCore

Returns:

A copy whose palette is mono and whose every colour and fall_colour is empty: the masses’, the air’s, and a warm caption’s.

Example

>>> from scenet import compile_source
>>> grey = "{setting: {place: street}, cast: {a: {reference: alice}}}"
>>> tinted = compile_source("{palette: tinted, " + grey[1:]).core
>>> tinted.as_mono() == compile_source(grey).core
True
actor(actor_id)[source]#

Look up one actor by id.

Parameters:

actor_id (str) – The id used in the panel source.

Return type:

CoreActor

Returns:

That actor.

Raises:

UnknownActorError – No actor in this panel has that id. Also a KeyError.

to_json()[source]#

Serialise deterministically.

Keys are sorted and floats already rounded at construction, so the same input yields byte-identical output on any platform. A trailing newline keeps the file well-formed for line-oriented tools like git diff.

Return type:

str

classmethod from_json(text)[source]#

Read a Core document back in.

The inverse of to_json, and the reason Panel Core is a real format rather than a private data structure: a layout can be exported, adjusted by hand or by another tool, and read back for emission.

Parameters:

text (str) – A Core document.

Return type:

Self

Returns:

The parsed panel.

Raises:

CoreSyntaxError – The text is not JSON, or not a Panel Core. Also a ValueError.