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
.. 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: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)
- module:
scenet.pipeline
.. py:function:: compile_ir(panel, *, library=None, metrics=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:
Font to measure lettering against.
- 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.
- 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.
.. py:function:: compile_source(text, *, source=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 only to prefix error messages. Pass it when you have one; the diagnostics are much more useful with it.
- 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.yamldocument.- 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:
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.
.. attribute:: pages
One Page Core per page, in order. Empty for a scene with no
pages:... 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:method:: Book.init(panels, pages)
- module:
scenet.pipeline
.. py:function:: compile_book(text, *, source=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 only to prefix error messages.
- 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-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, 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.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` | :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: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.yamlor*.scriptfile.- 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
.. 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.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]`
.. 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.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]]`