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.00 prints as 100, 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 id the 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 – quoteattr picks whichever one avoids the most escaping.

This exists because xml.sax.saxutils.escape does 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 with innerHTML by 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 id the 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 a clipPath, 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, because userSpaceOnUse is defined against the referencing element’s user space, which is ambiguous on an element that also carries a transform. The overlay is clipped too: alone, its viewBox clips 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 inside url(#...). Position is unique, safe and the same on every run. The panel’s group keeps its name, as panel-<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_text does 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 panels does 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 panels does not hold.