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

The 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

.. 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.fonts names them by. Hand them to the renderer.

.. 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 notes only 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=, lettering_notes=())

module:

scenet.pipeline

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

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

param panel:

The validated panel.

type library:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :py:obj:`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` | :py:obj:`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:obj:`None``

param base:

The folder the panel’s document is in, which the font files it declares are read from. Without one, a panel that declares a font is refused.

type lettering_height:
sphinx_autodoc_typehints_type:

\:py\:class\:\float` | :py:obj:`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.size letters 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`]] | :py:obj:`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:

\:py\:class\:\~scenet.pipeline.CompileResult``

returns:

The compiled panel, with the fonts it was lettered in.

raises PanelSyntaxError:

Rule font-file, for a declared font that cannot be read.

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

param base:

The folder files the document names are read from, when it is not the one source is in – or when there is no source at all.

type library:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :py:obj:`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` | :py:obj:`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:

\:py\:class\:\~scenet.pipeline.CompileResult``

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:

\:py\:class\:\~pathlib.Path``

param path:

A *.panel.yaml document.

type library:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :py:obj:`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` | :py:obj:`None``

param metrics:

Font to measure lettering against.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.pipeline.CompileResult``

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

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

.. attribute:: pages

One Page Core per page, in order. Empty for a scene with no pages:.

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

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

param base:

The folder files the document names are read from, in place of the one source is in.

type library:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :py:obj:`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` | :py:obj:`None``

param metrics:

Font to measure lettering against.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.pipeline.Book``

returns:

The compiled panels and pages.

raises PanelSyntaxError:

A panel or the layout is malformed, including rule page-layout for 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.

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:

\:py\:class\:\~pathlib.Path``

param path:

A *.scene.yaml document. A single-panel document also works and comes back as one entry named panel.

type library:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :py:obj:`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` | :py:obj:`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` | :py:obj:`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:obj:`None``

param base:

The folder files the script names are read from, in place of the one source is in.

type library:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :py:obj:`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` | :py:obj:`None``

param metrics:

Font to measure lettering against.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.pipeline.Book``

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:

\:py\:class\:\~pathlib.Path``

param path:

A *.panel.yaml, *.scene.yaml or *.script file.

type library:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.assets.contract.PuppetLibrary` | :py:obj:`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` | :py:obj:`None``

param metrics:

Font to measure lettering against.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.pipeline.Book``

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.

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

A staging relation that named somebody a panel left out.

.. attribute:: index

Where it stood in the panel’s staging, as inherited.

.. attribute:: relation

The relation, as written.

.. attribute:: actor

Who it named that is not in the panel.

.. 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 override onto base, with override winning.

Mappings merge recursively so that changing one actor’s pose leaves the rest of the cast alone. Lists replace wholesale rather than concatenating: script and staging are 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 null is 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 is settle, once the document is whole, that takes it out.

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.

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.

rtype:
sphinx_autodoc_typehints_type:

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

.. py:function:: resolve_overrides(panels)

module:

scenet.compose

Resolve every panel’s over chain 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.

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 null goes, 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’])