Compile a sequence of panels#

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 tedious, and it is where continuity errors come from: the ones readers notice.

So a panel can state only what differs from another one.

over: — sparse override#

panels:
  establishing:
    camera: {shot: full_shot}
    cast:
      alice: {reference: alice, at: left_third}
      bob:   {reference: bob,   at: right_third, facing: left}
    staging:
      - alice left_of bob

  reaction:
    over: establishing        # same cast, same staging
    camera: {shot: close_up}  # move in

The keyword is borrowed from OpenUSD’s composition arcs, where over means exactly this: name a parent, then state the difference. A comic script writes the same thing as an @over: directive; see Write a panel as a comic script.

from scenet import compile_scene

panels = compile_scene("""
panels:
  establishing:
    camera: {shot: full_shot}
    cast:
      alice: {reference: alice, at: left_third}
      bob:   {reference: bob,   at: right_third, facing: left}
    staging: [alice left_of bob]
  reaction:
    over: establishing
    camera: {shot: close_up}
""")

# The cast came through untouched.
assert len(panels["reaction"].core.actors) == 2

# The camera did not: a close-up draws everybody larger.
establishing = panels["establishing"].core.actor("alice").transform.scale
reaction = panels["reaction"].core.actor("alice").transform.scale
assert reaction > establishing

Merge rules#

Two rules, and they are worth knowing precisely:

  • Mappings merge recursively. Overriding one actor’s pose leaves the rest of that actor, and every other actor, alone.

  • Lists replace wholesale. Give a panel its own staging: and you replace the parent’s entirely — there is no appending. A list has no keys to merge on, and guessing at identity by position would be worse than a clear rule.

from scenet import compile_scene

panels = compile_scene("""
panels:
  base:
    cast:
      alice: {reference: alice, pose: pointing, at: left_third}
      bob:   {reference: bob,   at: right_third}
    staging: [alice left_of bob]
  changed:
    over: base
    cast:
      alice: {pose: arms_crossed}
""")

alice = panels["changed"].core.actor("alice")

# `pose` was overridden; `reference` and `at` survived the merge.
assert alice.pose == "arms_crossed"
assert alice.reference == "alice"

Leaving something out#

A third rule takes something away: null removes what it would have inherited, as JSON Merge Patch (RFC 7386) has it — “If the value is null, remove”. It reaches whatever lies beneath, the panel it is over: and the scene’s defaults alike. A cast member who goes takes every staging relation that names them along, since none can hold in a panel they are not in; scenet check notes each one as dropped-relation.

from scenet import compile_scene

panels = compile_scene("""
cast:
  alice: {reference: alice, at: left_third}
  bob:   {reference: bob,   at: right_third}
staging: [alice left_of bob]
panels:
  both: {}
  alone:
    cast: {bob: null}
""")

assert [actor.id for actor in panels["alone"].core.actors] == ["alice"]

All but one, while the member left out is heard from off panel: bob looking_at carol still holds when Carol speaks off_panel in that panel, and Bob turns toward her side of the frame. Her line ends on the side she was written to stand on, as a comic script’s CAROL (OP) does.

from scenet import compile_scene

panels = compile_scene("""
cast:
  bob:   {reference: bob,   at: right_third}
  carol: {reference: alice, at: left_third}
staging: [bob looking_at carol]
panels:
  both:
    script: [{say: {by: carol, text: Hello.}}]
  heard:
    cast: {carol: null}
    script: [{say: {by: carol, text: Over here!, off_panel: true}}]
""")

(bob,) = panels["heard"].core.actors
assert bob.gaze_aim[0] < 0  # toward the left, where she stood

A null inside a list is left as it is: a list is replaced whole, never merged into.

Shared defaults#

Anything alongside panels: is a default every panel inherits, which saves restating the panel size on each one:

from scenet import compile_scene

panels = compile_scene("""
panel: {size: [1200, 500]}
camera: {shot: medium_shot}

panels:
  first:  {cast: {a: {reference: alice}}}
  second: {cast: {a: {reference: bob}}}
""")

assert all(result.core.width == 1200.0 for result in panels.values())

One key is never inherited: a description says what one picture shows, to a reader who cannot see it. Beside panels: it is refused, and a panel drawn over: another does not take its parent’s, since it is a different picture — it writes its own, or has one generated:

from scenet import parse_scene

panels = parse_scene("""
cast: {a: {reference: alice}}
panels:
  first:  {description: Alice waits in the rain.}
  second: {over: first}
""")

assert panels["first"].description == "Alice waits in the rain."
assert panels["second"].description is None

And one key is only ever the document’s: direction, which way the comic is read. Written beside panels:, every panel reads that way; written on a panel, it is refused as panel-direction, since a sequence is read one way throughout:

from scenet import Direction, parse_scene

panels = parse_scene("""
direction: rtl
cast: {a: {reference: alice}}
panels:
  first: {}
  second: {over: first}
""")

assert {panel.direction for panel in panels.values()} == {Direction.RTL}

Chains and cycles#

over: chains as deep as you like. A cycle is a compile error rather than a hang:

from scenet import CompositionError, compile_scene

try:
    compile_scene("panels: {a: {over: b}, b: {over: a}}")
except CompositionError as exc:
    assert "cyclic" in str(exc)

Panels are compiled independently#

Each panel is compiled on its own, and nothing about its composition depends on what sits beside it. That is deliberate: if a panel laid out differently in a sequence than it did alone, panels would not be reusable and golden-file tests would mean nothing.

Rendering the whole thing#

scenet build examples/gallery/12-sequence.scene.yaml --strip

--strip writes one extra file laying every panel out side by side in reading order, on top of the individual SVGs — from the right, for a sequence read right to left. From Python that is render_strip:

from scenet import compile_scene, render_strip

panels = compile_scene("""
panels:
  one: {cast: {a: {reference: alice}}}
  two: {over: one, camera: {shot: close_up}}
""")

strip = render_strip([(name, result.core) for name, result in panels.items()])
assert strip.lstrip().startswith("<?xml")

Panel order in the output follows declaration order in the source, which is reading order. Each panel in the strip looks exactly as it does on its own: it is clipped to its frame, so a figure cropped by the shot stops at the panel’s edge rather than running into the gutter.

What this is not#

over: is composition, not animation. There is no interpolation between panels and no notion of time — a sequence is a set of independent panels that happen to share most of their description. To lay the same panels out on a page, in tiers and at varying sizes, see compose a page.