Emitting#
Panel Core to SVG. The emitter makes no layout decisions: everything it draws was already decided.
scenet.emit.svg#
.. py:module:: scenet.emit.svg
Panel Core into SVG.
Purely mechanical: every position here was decided by the solver. The emitter makes no layout decisions, which is what keeps rendering swappable and golden tests meaningful.
Numbers are formatted through one helper at fixed precision so that output is byte-identical across platforms, whose float repr differs in the last digit.
.. py:data:: GLYPH_SCALE_PLACES
- module:
scenet.emit.svg
- value:
6
Decimal places for a glyph’s scale. The scale is size/unitsPerEm, and a font’s units are a thousand or more to the em, so two places – right for a coordinate – wrote 0.035 as 0.04 and drew every letter 14% larger than it was measured. Six keep the drawn size within a millionth of an em of the measured one.
.. py:function:: fmt(value, places=2)
- module:
scenet.emit.svg
Format a number for SVG output.
Trailing zeros are stripped so
100.00prints as100, which keeps files small and diffs readable without making them any less exact.Two places is a hundredth of a panel unit, which is exact for a coordinate. It is not for a factor: a glyph’s scale multiplies a thousand font units, so it takes
places=6.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
.. py:function:: render(core, *, metrics=None, live_text=False, id_prefix=’’)
- module:
scenet.emit.svg
Render a compiled panel as a standalone SVG document.
- type core:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.core.PanelCore``
- param core:
The compiled panel.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :py:obj:`None``
- param metrics:
The font the lettering was measured in. Defaults to the shipped one.
- type live_text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param live_text:
Emit lettering as
<text>rather than glyph outlines.- type id_prefix:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param id_prefix:
Put in front of every
idthe panel writes, and every reference to one. Nothing a single panel needs; it is what lets a strip hold several panels in one document, where ids must be unique. Empty by default, so a panel on its own is byte-identical to what it always was.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
.. py:function:: attr(value)
- module:
scenet.emit.svg
Quote a string for use as an XML attribute value, delimiters included.
Returns the value with its surrounding quotes, because choosing the quote character is part of escaping correctly –
quoteattrpicks whichever one avoids the most escaping.This exists because
xml.sax.saxutils.escapedoes not escape quotation marks. That is fine for element content and wrong for an attribute: identifiers here come from user documents – a cast key, a panel name – and one containing a double quote would close the attribute early and let the rest of it be read as markup. The output is injected withinnerHTMLby the browser playground, so that is a scripting vector, not merely malformed XML.- type value:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param value:
Any string, trusted or not.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
The value, escaped and wrapped in quotes.
.. admonition:: Example
from scenet.emit.svg import attr attr(“alice”) ‘“alice”’ attr(‘a” onload=x’) ‘’a” onload=x’’
scenet.emit.debug_svg#
.. py:module:: scenet.emit.debug_svg
Diagnostic overlay: what the solver was actually looking at.
Building a geometric solver without this is guesswork. When a balloon lands somewhere surprising, the question is always “what did the solver think was there?” – and the answer is invisible in the finished panel. This draws the hidden geometry: silhouette hulls, face exclusion circles, anchors, gaze vectors, tail routes, and what an inset covers.
.. py:function:: render_debug(core, *, id_prefix=’’)
- module:
scenet.emit.debug_svg
Render the solver’s working geometry over a faint copy of the panel.
- type core:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.core.PanelCore``
- param core:
The compiled panel.
- type id_prefix:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param id_prefix:
Put in front of every
idthe overlay writes, so a strip can hold several overlays in one document. Empty by default, as in- func:
render <scenet.emit.svg.render>.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
scenet.emit.strip#
.. py:module:: scenet.emit.strip
Several panels laid out as a strip.
Deliberately minimal. Real page composition – tiers, panels of varying size, the page-level reading path, bleeds – is a substantial design problem in its own right and is explicitly out of scope. This is the smallest thing that lets a sequence be read as a sequence: panels in a row, separated by a gutter, in declaration order.
The gutter is not decoration. It is where the reader performs what Scott McCloud calls closure – inferring what happened between two panels – and it is the one formal element that distinguishes comics from a series of illustrations.
A panel in a strip looks exactly as it does alone. Two things make that true, and both used to be missing:
Each panel is clipped to its frame. A shot crops the body at the frame, so most of a figure usually lies outside it. A panel on its own hides that behind its
viewBox; here the same rectangle is aclipPath, or the rest of the figure would draw into the gutter – and, once panels stack, into the tier below. The clip sits on an inner group with no transform of its own, becauseuserSpaceOnUseis defined against the referencing element’s user space, which is ambiguous on an element that also carries atransform. The overlay is clipped too: alone, itsviewBoxclips it just the same.Every id is unique. Each panel’s ids, and the references to them, are prefixed by the panel’s position –
p1-,p2-– rather than its name. A name is whatever the document said, and while attribute escaping keeps one inside its quotes, nothing would keep it insideurl(#...). Position is unique, safe and the same on every run. The panel’s group keeps its name, aspanel-<name>.
.. py:function:: render_strip(panels, *, live_text=False, debug=False)
- module:
scenet.emit.strip
Lay panels left to right in reading order.
Each panel is rendered independently and then placed, rather than being re-solved: a panel’s composition must not depend on what sits beside it, or the same source would compile differently in isolation.
- type panels:
- sphinx_autodoc_typehints_type:
\:py\:class\:\list`\ \[:py:class:`tuple`\ \[:py:class:`str`, :py:class:`~scenet.core.PanelCore`]]`
- param panels:
Panel name and compiled core, in reading order.
- type live_text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param live_text:
Emit lettering as
<text>rather than glyph outlines.- type debug:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param debug:
Place each panel’s diagnostic overlay instead of the panel itself, in exactly the same positions, so a sequence can be debugged as a sequence.
live_textdoes not apply: the overlay labels in plain text already.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
One SVG document holding every panel.
.. py:function:: placed_panel(name, core, position, x, y, *, live_text=False, debug=False)
- module:
scenet.emit.strip
One panel, rendered on its own and put at
(x, y)in a larger document.Shared by the strip and the page, so both place a panel the same way: clipped to its frame, and with every id prefixed by the panel’s position in the document – see the module docstring for why position and not name.
- type name:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param name:
The panel’s name, kept as the group’s id.
- type core:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.core.PanelCore``
- param core:
The compiled panel.
- type position:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- param position:
Its one-based position in the document, unique within it.
- type x:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param x:
Where its left edge goes.
- type y:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param y:
Where its top edge goes.
- type live_text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param live_text:
Emit lettering as
<text>rather than glyph outlines.- type debug:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param debug:
Place the panel’s diagnostic overlay instead of the panel.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\list`\ \[:py:class:`str`]`
- returns:
The lines of SVG, indented for the document’s top level.
scenet.emit.page#
.. py:module:: scenet.emit.page
Pages into SVG: every panel at its frame.
Mechanical, like every emitter: the frames were resolved into Page Core and each panel into
its own Panel Core, so this only places one inside the other. Each panel is placed exactly
as the strip places one (:func:placed_panel <scenet.emit.strip.placed_panel>): rendered on
its own, clipped to its frame, its ids prefixed by its position so they stay unique in the
page.
.. py:function:: render_page(page, panels, *, live_text=False, debug=False)
- module:
scenet.emit.page
Render one page as a standalone SVG document.
- type page:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.core.PageCore``
- param page:
The page: its size and where each panel’s frame is.
- type panels:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`~scenet.core.PanelCore`]`
- param panels:
Every panel’s compiled Core, by name. Each one named by a frame must be here, compiled at that frame’s size.
- type live_text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param live_text:
Emit lettering as
<text>rather than glyph outlines.- type debug:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param debug:
Place each panel’s diagnostic overlay instead of the panel.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
The page, as SVG.
- raises ValueError:
A frame names a panel that
panelsdoes not hold.
.. admonition:: Example
from scenet import compile_book, render_page book = compile_book( … “cast: {a: {reference: alice}}\n” … “pages: [{tiers: [{panels: [one]}]}]\npanels: {one: {}}” … ) cores = {name: result.core for name, result in book.panels.items()} ‘viewBox=”0 0 2000 3000”’ in render_page(book.pages[0], cores) True
.. py:function:: render_pages(pages, panels, *, live_text=False, debug=False)
- module:
scenet.emit.page
Render every page side by side, as one SVG document.
What a single view shows – the playground’s, for one. Each page sits in a group
page-<n>, and panel positions count on across pages, so every id in the document stays unique.- type pages:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`~scenet.core.PageCore`]`
- param pages:
The pages, in order.
- type panels:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`~scenet.core.PanelCore`]`
- param panels:
Every panel’s compiled Core, by name.
- type live_text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param live_text:
Emit lettering as
<text>rather than glyph outlines.- type debug:
- sphinx_autodoc_typehints_type:
\:py\:class\:\bool``
- param debug:
Place each panel’s diagnostic overlay instead of the panel.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
Every page, left to right, as SVG.
- raises ValueError:
There are no pages, or a frame names a panel
panelsdoes not hold.