PanelCore#
Import |
|
Defined in |
|
Install |
|
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:
CoreModelA 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
alicesits 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.
- 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).
- balloons#
Resolved balloons, in reading order.
- Type:
- captions#
Resolved caption boxes, in reading order. Balloons and captions share one
ordersequence, since the reader takes them in one sequence.- Type:
- backdrop#
Where the panel is, or None when it says nothing about that – which is every panel written before the setting layer existed.
- Type:
- 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.
- 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.
- sfx#
Sound effects, in script order. Left out of the JSON when there are none.
- 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.
- 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.
- 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:
- 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:
- 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:
- 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:
- 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.
- 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.
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_jsonandPanelCore.from_json, the format on disk.render, to draw it.- 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
- 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 itsspeaker.- Return type:
- 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:
- Returns:
A copy whose
paletteismonoand whose everycolourandfall_colouris empty: the masses’, the air’s, and awarmcaption’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:
- 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:
- 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:
- Returns:
The parsed panel.
- Raises:
CoreSyntaxError – The text is not JSON, or not a Panel Core. Also a
ValueError.