Use Scenet as a library#
The scenet command is a thin wrapper over the same functions you can call yourself.
This page covers the public API: what is in it, what is not, and how to reach the parts
the command line does not expose. To learn it step by step, with every example’s output,
follow Learn Scenet from Python.
The one function you probably want#
from scenet import compile_source, render
result = compile_source("""
panel: {size: [900, 600]}
cast:
alice: {reference: alice}
script:
- say: {by: alice, text: "Compiled from a string."}
""")
svg = render(result.core)
assert svg.lstrip().startswith("<?xml")
Choosing an entry point#
You have |
Call |
|---|---|
A panel as a string |
|
A |
|
A multi-panel string |
|
A |
|
Any supported file, unknown type |
|
A scene with pages, as a string |
|
A comic script, as a string |
|
Any supported file, and its pages |
|
Any supported file, its panels alone |
|
An already-validated |
compile_book_file dispatches on the file
extension, which is what the CLI uses. It is the right choice when the syntax is the
user’s decision rather than yours. Each parse_* and load_* function stops at the IR,
without compiling: everything an author can get wrong is found there.
Seven renderers#
Every renderer reads a Core and makes no layout decision of its own: what it draws is what the compiler decided.
Renderer |
Draws |
Returns |
|---|---|---|
One panel |
SVG text |
|
One panel’s geometry: hulls, face zones, anchors, gaze, tail routes |
SVG text |
|
Several panels side by side, in reading order |
SVG text |
|
One page, each panel at its frame |
SVG text |
|
Every page, side by side |
SVG text |
|
Every page, for print |
PDF bytes |
|
The staging, for image models: pose, boxes, depth, mask, semantics |
from scenet import compile_scene, render, render_debug, render_strip
panels = compile_scene("""
panels:
wide: {cast: {a: {reference: alice}}, camera: {shot: full_shot}}
close: {over: wide, camera: {shot: close_up}}
""")
# One SVG per panel.
each = {name: render(result.core) for name, result in panels.items()}
assert set(each) == {"wide", "close"}
# The diagnostic overlay: hulls, face zones, anchors, gaze vectors, tail routes.
overlay = render_debug(panels["wide"].core)
# All panels laid out side by side, in reading order.
strip = render_strip([(name, result.core) for name, result in panels.items()])
render takes live_text=True if you want selectable <text> elements instead of
glyph outlines. The default emits outlines, which makes the file self-contained — no
font to embed and none to be missing — at the cost of a larger file and text you cannot
select.
What a renderer must be handed back#
A Core names its fonts and pictures by the digest of their bytes, and holds neither. What the compile read, it returns, and a renderer is handed it back:
fonts=— every font a document declared, fromresult.fontsorbook.fonts. A Core lettered in a font of its own, drawn without it, raisesRenderError: drawing the lettering in another face would draw text that does not fit the balloons measured for it.embed=— a supplied picture’s bytes, fromresult.imagesorbook.images, to write into the SVG as adata:URL. Left out, the SVG links the picture by the path the document wrote, which a viewer must then find beside it. The print PDF takes them asimages=and always carries them.
Both are shown in your own font below.
Pages, and books#
A scene with pages: lays its panels out on pages. compile_book returns a Book: every
panel, compiled at its frame’s shape, and a Page Core per page.
from scenet import compile_book, render_page, render_pages, render_pdf
book = compile_book("""
cast: {a: {reference: alice}, b: {reference: bob, at: right_third, facing: left}}
pages:
- tiers:
- panels: [{use: wide, width: 2}, close]
panels:
wide: {camera: {shot: full_shot}}
close: {over: wide, camera: {shot: close_up}, script: [{say: {by: a, text: "Hello."}}]}
""")
cores = {name: result.core for name, result in book.panels.items()}
first = render_page(book.pages[0], cores, fonts=book.fonts)
spread = render_pages(book.pages, cores, fonts=book.fonts)
pdf = render_pdf(book.pages, cores, fonts=book.fonts, images=book.images)
assert pdf.startswith(b"%PDF-")
A page unit prints as 0.1 mm, and lettering is on the black plate. live_text=True letters
the PDF in its embedded faces rather than outlines, and mono=True prints the greys rather
than the tinted palette’s CMYK twins. See Print a comic.
compile_book_file reads any document and its
pages, choosing the frontend by extension — what scenet build calls. A comic script has
no pages; compile_script returns its panels as a
book.
Exports for image models#
import json
from scenet import compile_source, render_conditioning
exports = render_conditioning(compile_source("cast: {a: {reference: alice}}").core)
pose = json.loads(exports.pose) # OpenPose COCO-18 keypoints
semantics = json.loads(exports.semantics) # what the panel holds, as structure
assert exports.depth.lstrip().startswith("<")
Each is drawn from the Core alone. See Export for image models.
Handling errors#
Everything the compiler can object to inherits ScenetError:
from scenet import ScenetError, compile_source
try:
compile_source("cast: {ghost: {reference: nobody}}")
except ScenetError as exc:
message = str(exc.args[0])
assert "nobody" in message
The middle tier of the hierarchy answers the question you usually have, which is whose fault it is:
from scenet import ScenetError, SolverError, SourceError, compile_source
# A malformed document: the person who wrote the panel needs to fix it.
try:
compile_source("panel: {size: [0, 100]}")
except SourceError as exc:
assert "must be positive" in str(exc)
# Both branches are catchable as one thing when you do not care which.
assert issubclass(SourceError, ScenetError)
assert issubclass(SolverError, ScenetError)
Every concrete error also keeps the built-in base you would have reached for before this
hierarchy existed — SourceError is a ValueError, UnknownPuppetError is a KeyError,
MissingFileError is a FileNotFoundError — so existing handlers keep working. Beyond the
document’s own faults:
Error |
Raised when |
Also a |
|---|---|---|
|
A file a call names cannot be read, or is not there |
|
|
A puppet or font file is there and is not one |
|
|
A renderer is not handed a font, a picture’s bytes, or a panel a page places |
|
|
|
|
|
|
|
A model you build yourself, such as PanelIR(...), raises pydantic’s ValidationError, as
pydantic does. Every function’s entry in the reference lists exactly what it raises.
See scenet.errors for the full tree.
Reading the layout instead of drawing it#
The interesting information is in result.core, not in the SVG. Panel Core is fully
resolved and entirely numeric, but every name you wrote survives:
from scenet import PanelCore, compile_source
result = compile_source("""
cast:
alice: {reference: alice, at: left_third}
bob: {reference: bob, at: right_third}
staging: [alice left_of bob]
script:
- say: {by: alice, text: "Look over there."}
""")
alice = result.core.actor("alice")
# Named attachment points, in panel coordinates.
mouth_x, mouth_y = alice.anchors["mouth"]
# The region no balloon may cover.
face = alice.face_exclusion
# Painter's order: higher values are drawn in front.
assert alice.depth >= 0
# And it serialises to something you can diff, edit, and read back.
document = result.core.to_json()
restored = PanelCore.from_json(document)
assert restored == result.core
That round trip is the point of the tier. A layout can leave the compiler, be adjusted by hand or by another tool, and come back for emission without ever touching the source.
Supplying your own characters#
Both the puppet library and the font are injectable:
from scenet import PuppetLibrary, compile_source, default_library
library = default_library()
assert library.names() == ("alice", "bob")
# A library built by hand takes the same shape.
just_alice = PuppetLibrary({"alice": library.get("alice")})
result = compile_source("cast: {a: {reference: alice}}", library=just_alice)
assert result.core.actors[0].reference == "alice"
A document can also name a puppet file of its own, reference: puppets/pip.puppet.yaml, read
beside it — or, for text, from the files passed as base= — with no library to build. See
add your own character for both, and for the file format.
Your own font#
A document names its font as a file beside it, lettering: {font: fonts/neue.ttf}. From
Python, the files a document names can be handed over as a mapping with base=, so
nothing is read from disk:
from pathlib import Path
from scenet import compile_source, render
neue = Path("examples/gallery/fonts/ComicNeue-Regular.ttf").read_bytes()
result = compile_source(
"lettering: {font: fonts/neue.ttf}\n"
"cast: {a: {reference: alice}}\n"
"script: [{say: {by: a, text: In my own face.}}]",
base={"fonts/neue.ttf": neue},
)
svg = render(result.core, fonts=result.fonts)
To measure every panel against one font without a document naming it, pass a
FontMetrics as metrics= to the compile, and the
same one to the renderer:
from pathlib import Path
from scenet import FontMetrics, compile_source, render
font = FontMetrics(Path("examples/gallery/fonts/ComicNeue-Regular.ttf"))
result = compile_source("cast: {a: {reference: alice}}", metrics=font)
svg = render(result.core, metrics=font)
A font is always a file, never a system font: what is measured has to be what is drawn, everywhere. See Letter in your own font.
Building a panel in Python#
The language is the IR’s models, and each validates as it is built. Build one by hand and
compile it with compile_ir:
from scenet import CameraSpec, CastMember, PanelIR, Relation, SayEvent, compile_ir
panel = PanelIR(
camera=CameraSpec(shot="medium_shot"),
cast={
"alice": CastMember(reference="alice", at="left_third"),
"bob": CastMember(reference="bob", at="right_third", facing="left"),
},
staging=[Relation(subject="alice", predicate="left_of", object="bob")],
script=[SayEvent(by="alice", text="Built, not written.")],
)
result = compile_ir(panel)
assert result.core.balloons[0].speaker == "alice"
A model built by hand raises pydantic’s ValidationError for a bad value, as pydantic
does; the frontends turn the same fault into a PanelSyntaxError that says where it is.
The Core object model#
A Panel Core is a tree of plain, frozen models. What you will read most:
Read |
Type |
What it holds |
|---|---|---|
|
|
The panel’s size, in panel units |
|
|
Each character: transform, anchors, face, hull, pose, depth |
|
|
Each figure a supplied picture draws |
|
|
Each balloon: box, lines as broken, font size, tail |
|
|
Each caption box |
|
|
Each sound effect, its glyphs placed |
|
|
The setting, resolved: masses, atmosphere, a picture |
|
|
The shot asked for, and what the camera made of it |
Every type is on the Panel Core types page, and
every field of a Panel Core is in the format’s reference.
Import a type from scenet.core to annotate with it. A layout read off the Core is the
compiler’s own: change it and write it back with to_json, and the renderers draw what you
wrote.
Threads, caches, and the files a compile reads#
Threads. Compiles may run in parallel threads; they share only caches of parsed fonts. Call
default_libraryonce and pass the library on: it reads the shipped puppets on every call.Files. A compile reads only the files the document names, from
baseor the folder ofsource. Compiling documents you do not trust, hand their files over as a mapping: a path a document writes may climb out of a folder with../.Dependencies.
compile_book_file(path, dependencies=set())fills the set with every file the compile read, which is howscenet build --watchknows what to watch.
The Guarantees page has the details, and timings.
What is public#
scenet.__all__ is the contract, and the reference has an
entry for each name in it, with the release it appeared in. Names outside it are internal
and may change in any minor release:
import scenet
assert "compile_source" in scenet.__all__
assert "render" in scenet.__all__
# Reachable, but not promised. Import from these at your own risk.
import scenet.solve.balloons # noqa: F401
If you find yourself needing something that is not exported, that is worth raising as an issue — it usually means the public surface has a gap.
Determinism, and what it buys you#
The same input always produces byte-identical output: see Determinism for what that covers.
from scenet import compile_source, render
source = "cast: {a: {reference: alice}}"
assert render(compile_source(source).core) == render(compile_source(source).core)
That is what makes golden-file testing possible, and it is why a Scenet panel can live in version control as a source file rather than as a binary blob.