Compiling#
The compiler itself. Source or IR in, Panel Core out.
Every entry point takes the same two optional keyword arguments – library and
metrics – so the character set and the font are both injectable, and neither is
read from the environment.
scenet.pipeline#
.. py:module:: scenet.pipeline
The compiler: source through IR to Panel Core.
Each stage is separable and independently testable, which is the point of having tiers at all. The frontend never computes a coordinate, the solver never touches artwork, and the emitter never makes a layout decision.
.. py:class:: CompileResult
- module:
scenet.pipeline
Bases: :py:class:
objectThe compiled panel, with the intermediate results kept for inspection.
Diagnostics – notably whether the camera had to retreat to fit the cast – are part of the result rather than log output, so tooling can surface them.
.. py:attribute:: CompileResult.core
- module:
scenet.pipeline
- type:
~scenet.core.PanelCore
.. py:attribute:: CompileResult.camera
- module:
scenet.pipeline
- type:
~scenet.solve.camera.CameraSolution | None
The framing the camera chose, or None for a panel whose cast a supplied picture draws (#71): the artist framed it, and the camera does not run.
.. py:attribute:: CompileResult.placements
- module:
scenet.pipeline
- type:
tuple[~scenet.solve.staging.Placement, …]
.. py:attribute:: CompileResult.posed
- module:
scenet.pipeline
- type:
dict[str, ~scenet.assets.kinematics.ResolvedPuppet]
.. py:attribute:: CompileResult.fonts
- module:
scenet.pipeline
- type:
dict[str, ~scenet.solve.text.FontMetrics]
The fonts the lettering was measured in, other than the shipped family’s, by the digest
PanelCore.fontsnames them by. Hand them to the renderer.
.. py:attribute:: CompileResult.images
- module:
scenet.pipeline
- type:
dict[str, bytes]
The supplied pictures it was drawn over, by the digest
PanelCorenames them by: their bytes, for a renderer asked to embed them rather than link them.
.. py:attribute:: CompileResult.lettering_notes
- module:
scenet.pipeline
- type:
tuple[str, …]
Faces the document named no file for, and what was used instead – reported in
notesonly when something was actually set in one.
.. py:property:: CompileResult.notes
- module:
scenet.pipeline
- type:
tuple[str, …]
Human-readable diagnostics about how this panel was compiled.
- returns:
Zero or more sentences describing decisions the compiler had to make that were not literally what the source asked for – a camera that retreated to fit the cast, a balloon tail that had to bend around a face, a mark drawn partly outside the panel.
These are returned rather than logged so that tooling can put them in front of the person who wrote the panel. A camera that silently retreats leaves you with a panel that is quietly not the shot you asked for, which you would eventually notice and have no way to explain.
.. admonition:: Example
from scenet import compile_source crowded = compile_source( … “{panel: {size: [600.0, 400.0]}, camera: {shot: close_up},” … “ cast: {a: {reference: alice}, b: {reference: bob}},” … “ staging: [a left_of b]}” … ) any(“camera retreated” in note for note in crowded.notes) True
.. py:method:: CompileResult.init(core, camera, placements, posed, fonts=
, images= , lettering_notes=()) - module:
scenet.pipeline
.. py:data:: PRESERVE_ASPECT_RATIO
- module:
scenet.pipeline
- type:
dict[~scenet.ir.Fit, ~typing.Literal[‘xMidYMid slice’, ‘xMidYMid meet’]]
- value:
{Fit.CONTAIN: ‘xMidYMid meet’, Fit.COVER: ‘xMidYMid slice’}
A fit, as SVG’s
preserveAspectRatiosays it.
.. py:function:: compile_ir(panel, *, library=None, metrics=None, base=None, lettering_height=None, exclusions=(), outline=None)
- module:
scenet.pipeline
Compile validated IR into Panel Core.
- type panel:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\583f399c2c86395a``
- param panel:
The validated panel.
- type library:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :sphinx_autodoc_typehints_constant:`None``
- param library:
Characters to draw from. Defaults to the two shipped puppets.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :sphinx_autodoc_typehints_constant:`None``
- param metrics:
A regular face to measure lettering against, in place of the one the panel declares or the shipped one.
- 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 folder the panel’s document is in, which the font files and the picture it declares are read from – or those files themselves, by the path it writes. Without one, a panel that names a file is refused.
- type lettering_height:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float` | :sphinx_autodoc_typehints_constant:`None``
- param lettering_height:
The height type sizes are a fraction of, instead of the panel’s own. A page passes the same value to every panel on it; a panel compiled on its own leaves it out. A panel that sets
lettering.sizeletters at that size instead, and this is not consulted.- type exclusions:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`~scenet.geom.BBox`]`
- param exclusions:
Areas no balloon or caption may touch, in panel units, because something is drawn over them – on a page, the insets set into this panel. Nothing else moves for them: the art under an inset is drawn as usual.
- type outline:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`tuple`\ \[:py:class:`float`, :py:class:`float`]] | :sphinx_autodoc_typehints_constant:`None``
- param outline:
The panel’s border when it is not a rectangle – on a page, a panel in a slanted tier – in panel units. The panel is staged and framed in its bounding box as usual, and cropped to this; lettering stays inside it, a margin in.
- rtype:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\378b4cdc2f68a05c``
- returns:
The compiled panel, with the fonts it was lettered in.
- raises PanelSyntaxError:
Rule
font-file, for a declared font that cannot be read,image-file, for a picture,artwork-contract, for the contract beside a picture whose figures the panel casts, orunknown-figure, for a figure the picture does not draw.
.. py:function:: compile_source(text, *, source=None, base=None, library=None, metrics=None)
- module:
scenet.pipeline
Compile one panel from a source string.
The usual entry point, and the one to reach for first.
- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
A single-panel document in the YAML surface syntax.
- type source:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path` | :sphinx_autodoc_typehints_constant:`None``
- param source:
Path the text came from, used to prefix error messages and to find the files it names beside it. Pass it when you have one; the diagnostics are much more useful with 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 folder files the document names are read from, when it is not the one
sourceis in – or when there is nosourceat all.- type library:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :sphinx_autodoc_typehints_constant:`None``
- param library:
Characters to draw from. Defaults to the two shipped puppets.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :sphinx_autodoc_typehints_constant:`None``
- param metrics:
Font to measure lettering against. Defaults to the font that ships as a dependency of this package.
- rtype:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\378b4cdc2f68a05c``
- returns:
The compiled panel, with the intermediate results kept for inspection.
- raises PanelSyntaxError:
The document is malformed or invalid.
- raises UnknownPuppetError:
A cast member references a character the library lacks.
- raises LayoutError:
The required constraints cannot all be satisfied.
- raises BalloonPlacementError:
A balloon has no legal position.
.. admonition:: Example
from scenet import compile_source, render result = compile_source( … “{cast: {alice: {reference: alice}}, script: [{say: {by: alice, text: Hello.}}]}” … ) len(result.core.balloons) 1 result.core.balloons[0].lines (‘Hello.’,) svg = render(result.core)
.. seealso::
- func:
compile_file <scenet.pipeline.compile_file>, to read from disk.- func:
compile_scene <scenet.pipeline.compile_scene>, for multi-panel documents.- func:
compile_document <scenet.pipeline.compile_document>, to dispatch on extension and accept any supported syntax.
.. py:function:: compile_file(path, *, library=None, metrics=None)
- module:
scenet.pipeline
Compile one panel from a file.
- type path:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\e90600ab622545d5``
- param path:
A
*.panel.yamldocument.- type library:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :sphinx_autodoc_typehints_constant:`None``
- param library:
Characters to draw from. Defaults to the two shipped puppets.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :sphinx_autodoc_typehints_constant:`None``
- param metrics:
Font to measure lettering against.
- rtype:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\378b4cdc2f68a05c``
- returns:
The compiled panel.
- raises OSError:
The file cannot be read.
- raises PanelSyntaxError:
The document is malformed or invalid. The path is included in the message.
.. py:class:: Book
- module:
scenet.pipeline
Bases: :py:class:
objectA scene compiled: every panel, and the pages they are laid out on.
.. attribute:: panels
Panel name to compiled panel, in reading order. A panel on a page was compiled at its frame’s size and the page’s type size; one on no page, as it would have been alone.
- type:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.pipeline.CompileResult`]`
.. attribute:: pages
One Page Core per page, in order. Empty for a scene with no
pages:.- type:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`~scenet.core.PageCore`, :py:data:`…<Ellipsis>`]`
.. attribute:: notes
What reading the document noticed that is worth saying but is no fault – in a comic script, a cue with nothing said under it, or a page whose stated count its panels do not match. Each names its line. A panel’s own notes, on what the compiler decided, are on its
CompileResult.- type:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]`
.. py:attribute:: Book.panels
- module:
scenet.pipeline
- type:
dict[str, ~scenet.pipeline.CompileResult]
.. py:attribute:: Book.pages
- module:
scenet.pipeline
- type:
tuple[~scenet.core.PageCore, …]
.. py:attribute:: Book.notes
- module:
scenet.pipeline
- type:
tuple[str, …]
.. py:property:: Book.fonts
- module:
scenet.pipeline
- type:
dict[str, ~scenet.solve.text.FontMetrics]
what to render with.
- type:
Every declared font any panel was lettered in, by digest
.. py:property:: Book.images
- module:
scenet.pipeline
- type:
dict[str, bytes]
what to embed.
- type:
Every supplied picture any panel was drawn over, once, by digest
.. py:method:: Book.init(panels, pages, notes=())
- module:
scenet.pipeline
.. py:function:: compile_book(text, *, source=None, base=None, library=None, metrics=None)
- module:
scenet.pipeline
Compile a scene and lay its panels out on pages.
A page decides two things about each panel on it – the size of its frame, and the height its type size is a fraction of – and nothing else. Each panel is still compiled on its own, so a panel on a page is exactly that panel compiled alone at that size, and a panel’s composition never depends on what sits beside it.
- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
A scene document. One with no
pages:compiles exactly as- func:
compile_scene <scenet.pipeline.compile_scene>always has.
- type source:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path` | :sphinx_autodoc_typehints_constant:`None``
- param source:
Path it came from, used to prefix error messages and to find the files it names beside 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 folder files the document names are read from, in place of the one
sourceis in.- type library:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :sphinx_autodoc_typehints_constant:`None``
- param library:
Characters to draw from. Defaults to the two shipped puppets.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :sphinx_autodoc_typehints_constant:`None``
- param metrics:
Font to measure lettering against.
- rtype:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\2754cc7649e58eee``
- returns:
The compiled panels and pages.
- raises PanelSyntaxError:
A panel or the layout is malformed, including rule
page-layoutfor a placement naming no panel, or a panel placed twice.- raises CompositionError:
An
over:chain is unresolvable or cyclic.
.. admonition:: Example
from scenet import compile_book book = compile_book( … “pages: [{tiers: [{panels: [a, b]}]}]\n” … “panels: {a: {cast: {x: {reference: alice}}}, b: {over: a}}” … ) [(frame.panel, frame.width) for frame in book.pages[0].frames] [(‘a’, 880.0), (‘b’, 880.0)] book.panels[“a”].core.width 880.0
.. py:function:: compile_scene(text, *, source=None, base=None, library=None, metrics=None)
- module:
scenet.pipeline
Compile every panel in a multi-panel document.
Each panel is compiled independently. A panel’s composition must not depend on what sits beside it, or the same source would compile differently in isolation – which would make panels non-reusable and golden tests meaningless. A panel that a page lays out is compiled at its frame’s size; see
- func:
compile_book <scenet.pipeline.compile_book>, which also returns the pages.- sphinx_autodoc_typehints_rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.pipeline.CompileResult`]`
.. py:function:: compile_scene_file(path, *, library=None, metrics=None)
- module:
scenet.pipeline
Compile every panel in a multi-panel file.
- type path:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\e90600ab622545d5``
- param path:
A
*.scene.yamldocument. A single-panel document also works and comes back as one entry namedpanel.- type library:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :sphinx_autodoc_typehints_constant:`None``
- param library:
Characters to draw from. Defaults to the two shipped puppets.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :sphinx_autodoc_typehints_constant:`None``
- param metrics:
Font to measure lettering against.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.pipeline.CompileResult`]`
- returns:
Panel name to compiled panel, in declaration order – which is reading order.
- raises OSError:
The file cannot be read.
- raises PanelSyntaxError:
A panel is malformed or invalid.
- raises CompositionError:
An
over:chain refers to a panel that does not exist, or forms a cycle.
.. py:function:: compile_script(text, *, source=None, base=None, library=None, metrics=None)
- module:
scenet.pipeline
Compile a comic script, every panel and page of it.
The one way a script is compiled, whoever asks:
scenet build,scenet check --deep, the MCP server and the playground used to each assemble one by hand, and would have drifted apart the day a script laid out pages.- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
The script.
- type source:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path` | :sphinx_autodoc_typehints_constant:`None``
- param source:
Path it came from, used to prefix error messages and to find the files it names beside 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 folder files the script names are read from, in place of the one
sourceis in.- type library:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :sphinx_autodoc_typehints_constant:`None``
- param library:
Characters to draw from. Defaults to the two shipped puppets.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :sphinx_autodoc_typehints_constant:`None``
- param metrics:
Font to measure lettering against.
- rtype:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\2754cc7649e58eee``
- returns:
Every panel, and the pages they are laid out on – none yet, for a script.
- raises ScriptSyntaxError:
The script cannot be read, or a panel does not validate.
.. admonition:: Example
from scenet import compile_script book = compile_script(”—\ncast: {A: {reference: alice}}\n—\nPANEL 1\nA\nHi.\n”) list(book.panels) [‘1’]
.. py:data:: DOCUMENT_LOADERS
- module:
scenet.pipeline
- value:
{‘.script’:
, ‘.yaml’: , ‘.yml’: }
The same extensions, read as whole documents – panels and the pages they go on.
.. py:function:: compile_book_file(path, *, library=None, metrics=None)
- module:
scenet.pipeline
Compile any supported document and its pages, choosing the frontend by extension.
- type path:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\e90600ab622545d5``
- param path:
A
*.panel.yaml,*.scene.yamlor*.scriptfile.- type library:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :sphinx_autodoc_typehints_constant:`None``
- param library:
Characters to draw from. Defaults to the two shipped puppets.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :sphinx_autodoc_typehints_constant:`None``
- param metrics:
Font to measure lettering against.
- rtype:
- sphinx_autodoc_typehints_type:
\:sphinx\_autodoc\_typehints\_alias\:\2754cc7649e58eee``
- returns:
Every panel, and the pages they are laid out on – none for a single panel or a comic script.
- raises ValueError:
The extension is not one any frontend reads.
- raises OSError:
The file cannot be read.
- raises PanelSyntaxError:
The document is malformed or invalid.
.. py:function:: compile_document(path, *, library=None, metrics=None)
- module:
scenet.pipeline
Compile any supported document, choosing the frontend by extension.
- sphinx_autodoc_typehints_rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.pipeline.CompileResult`]`
scenet.compose#
.. py:module:: scenet.compose
Sparse override between panels.
Borrowed from OpenUSD’s composition arcs, and specifically from over: a panel names
a parent and states only what differs from it.
This matters more for comics than it might look. Consecutive panels in a scene are mostly identical – the same cast, the same staging, the same camera – with one thing changed. Restating all of it per panel is both tedious and a place for inconsistencies to creep in, which is exactly the continuity error comics readers notice.
panels:
p1:
camera: {shot: medium_shot}
cast:
alice: {reference: alice, at: left_third}
p2:
over: p1 # everything from p1...
camera: {shot: close_up} # ...except the framing
Taking something away is JSON Merge Patch’s rule (RFC 7386): “If the value is null,
remove”. cast: {bob: null} leaves Bob out of a panel that would otherwise inherit him.
.. py:class:: Dropped
- module:
scenet.compose
Bases: :py:class:
objectA staging relation that named somebody a panel left out.
.. attribute:: index
Where it stood in the panel’s staging, as inherited.
- type:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
.. attribute:: relation
The relation, as written.
- type:
- sphinx_autodoc_typehints_type:
\:py\:class\:\object``
.. attribute:: actor
Who it named that is not in the panel.
- type:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
.. py:attribute:: Dropped.index
- module:
scenet.compose
- type:
int
.. py:attribute:: Dropped.relation
- module:
scenet.compose
- type:
object
.. py:attribute:: Dropped.actor
- module:
scenet.compose
- type:
str
.. py:method:: Dropped.init(index, relation, actor)
- module:
scenet.compose
.. py:function:: merge(base, override)
- module:
scenet.compose
Deep-merge
overrideontobase, withoverridewinning.Mappings merge recursively so that changing one actor’s pose leaves the rest of the cast alone. Lists replace wholesale rather than concatenating:
scriptandstagingare ordered wholes, and appending to an inherited script would make it impossible to write a panel where somebody says less than in the panel before.A
nullis kept, not applied: it has to remove the key from whatever the document is merged over next as well – a scene’s defaults come last – so it issettle, once the document is whole, that takes it out.- sphinx_autodoc_typehints_rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]`
.. py:function:: names(relation, actor)
- module:
scenet.compose
Whether a staging relation, as written, names an actor as subject or object.
- sphinx_autodoc_typehints_rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
.. py:function:: relation_text(relation)
- module:
scenet.compose
A staging relation as a sentence, however it was written.
- sphinx_autodoc_typehints_rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
.. py:function:: resolve_overrides(panels)
- module:
scenet.compose
Resolve every panel’s
overchain into a self-contained document.Panels are resolved lazily with memoisation, so a chain is walked once however many panels hang off it, and declaration order does not matter – a panel may inherit from one declared later.
- sphinx_autodoc_typehints_rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]]`
.. py:function:: settle(document)
- module:
scenet.compose
Apply the removals a complete document’s
nulls ask for.Every key whose value is
nullgoes, in mappings at any depth – not inside lists, which Merge Patch treats as values. A cast member who goes takes with them every staging relation that names them, since none can hold in a panel they are not in.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`dict`\ \[:py:class:`str`, :py:data:`~typing.Any`], :py:class:`tuple`\ \[:py:class:`~scenet.compose.Dropped`, :py:data:`…<Ellipsis>`]]`
- returns:
The document, and the relations dropped, in the order they were written.
.. admonition:: Example
settled, dropped = settle({“cast”: {“a”: {}, “b”: None}, “staging”: [“a left_of b”]}) settled, [item.actor for item in dropped] ({‘cast’: {‘a’: {}}, ‘staging’: []}, [‘b’])