Skip to content

v0.6.0

Choose a tag to compare

@github-actions github-actions released this 27 Aug 20:46
· 266 commits to main since this release
1a487e9

Setting: a panel can now show where and when it happens — and a caption box can be
tinted to read against it.

Added

  • The setting layer: a panel can show where and when it happens. Every panel rendered
    figures on white; there was no setting block at all. Captions (0.4.0) shipped the
    cheap half of establishing place — a locale box can say MIDNIGHT. THE DOCKS. —
    and this is the expensive half.

    setting:
      place: docks
      horizon: mid
      time: night
      weather: rain
  • Backdrops are described tonal masses, never drawn geometry. Crisp architecture needs
    a vanishing point and this is deliberately a flat, orthographic compiler, so drawn
    buildings would fight the compiler's own model — soft masses have no perspective to get
    wrong. It is also how comics actually establish place: notan (Dow, Composition,
    1899) says place is read from the arrangement of masses rather than from rendered
    detail, and aerial perspective supplies the parametric rule — with distance, value
    contrast drops toward the atmosphere.

  • Twelve mass kinds, from COCO-Stuff supercategories — building, ground, plant,
    sky, solid, structural, water outdoors, ceiling, floor, furniture, wall,
    window indoors. Taken from an existing taxonomy of stuff rather than invented, for
    the same reason the predicates came from Visual Genome. Not its leaf names: the real
    classes are building-other and sky-other, and nobody should have to type that.

  • Ten named places — alley, desert, docks, field, forest, mountain,
    office, room, shore, street — each expanding into a mass list the author could
    have written themselves. That rule is what keeps a preset a library rather than a second
    opaque format, and it is enforced by a test. The expansion happens in the frontend, so
    the IR has no place field at all — the same treatment alice left_of bob gets.

  • plane reuses the existing painter's order rather than introducing a second one.
    The three backdrop planes take negative depths; foreground takes one above the
    frontmost actor, so a foreground mass draws over the cast the way a silhouetted doorway
    does. Value follows from the plane and from nothing else, which is what keeps the notan
    reading literal.

  • time and weather. time supplies the two ends of the value ladder rather than
    tinting a daytime panel, so night is a darker, narrower ladder — and the ladder stays
    monotonic in depth at every hour by construction. weather adds fog as a
    feTurbulence veil, and rain and snow as that veil plus falling marks.

  • CoreBackdrop on Panel Core, carrying fully resolved numeric polygons and tone
    values — the same discipline as capsules, blobs and face_marks, so the emitter
    still makes no layout decision. Absent on a panel that says nothing about where it is,
    which is why this needed no format_version bump.

  • Masses are a soft cost for balloon placement, never an exclusion. Balloons sit over
    backgrounds routinely; that is what a background is for. Covering one costs an order of
    magnitude less than covering a face, weighted so a foreground silhouette costs more than
    empty sky.

  • scenet check reports unknown-place and conflicting-setting, each naming the
    field. A place and a mass list together is rejected rather than guessed at: a place is
    a mass list.

  • scripts/setting_sheet.py, the calibration instrument — every place against every
    hour on one sheet, every weather on another. Whether three greys read as depth is not a
    question a test can answer, and four things moved because of what the first sheet showed.

  • Gallery examples 19, 20 and 21, and a docs/reference/language.md section for the block.

  • Caption boxes can be tinted. Captions shipped in 0.4.0 with four kinds and the
    typography that goes with them, and one value: #ffffff, hardcoded in the emitter. A
    tone key now chooses from a three-value palette.

    - caption: {text: "Noon. Nothing for miles.", kind: locale, tone: ink}

    The failing case is the pale end, not the dark one. A caption box is opaque, so its
    lettering was never at risk — the text sits on the fill whatever is behind it. The
    box is what stops reading: against the ladder above, a white box on a noon sky is
    1.16:1, and only the stroke separates it at all.

  • The palette is rungs of the backdrop's own value ladder — paper #ffffff, pale
    #adadad, ink #090909, the last two taken from the day row by index rather than
    restated, so lettering and backdrop cannot drift apart as either is tuned. paper is
    the default, so no existing panel moves. No free-form fill:, and no yellow: an open
    colour field would be this language's one open vocabulary, and the classic yellow
    locale box would be the first non-neutral value in the codebase.

  • ink inverts the lettering to paper — reversed type — chosen by contrast in the
    solver and carried on CoreCaption as fill and ink. The same rule and the same
    reason as falling rain, and it leaves the emitter with no decision about which mark
    reads. Both fields are defaulted, so a Core document written before this still parses
    and no format_version bump was needed.

  • The lettering floor is enforced rather than asserted. contrast_ratio in
    solve/backdrop.py measures WCAG relative luminance — the ladder is spaced in OKLab
    because that predicts even perceived steps, but legibility is checked against the
    published threshold. Every tone clears 4.5:1 against its own lettering, and every rung
    of every hour has at least one tone above 3:1 to sit on. This is the one visual rule in
    the compiler with an objective answer, so it is a test rather than a taste.

  • Gallery example 22, a tone row and section in docs/reference/language.md, and
    fill / ink in docs/reference/panel_core.md.

  • scenet check --deep. Runs the full compiler on any document that passes the
    cheap checks, to additionally catch layout and balloon-placement failures — the
    two rules in the catalogue that were in the catalogue but unreachable from check.
    Off by default: it costs a real compile, including font metrics, and check stays
    the cheap pass it is documented as unless asked otherwise.

Changed

  • long_shot reframes noticeably wider, and wide with it — headroom 0.14 → 0.28,
    footroom 0.06 → 0.10. solve/camera.py admitted the problem in a comment: with no
    environment to show, long_shot and full_shot crop at the same landmark and could
    differ only by a little headroom, so two rungs at the widest end of the ladder stayed
    degenerate. There is an environment now, so a long shot can mean what it says — the
    figure fills roughly two thirds of what a full shot does. Every existing panel that
    asks for long_shot or wide renders smaller than it did.
    The comment is gone and
    docs/reference/shot_types.md is updated.

  • PanelSyntaxError carries an optional rule and loc, so a check the frontend
    performs itself can name a catalogue rule and a field instead of arriving as a generic
    invalid-field. Both default to nothing, so every existing raise is unchanged.

  • The determinism boundary is written down in docs/reference/language.md: the
    contract is on the emitted SVG text, which stays byte-identical, and has never been on
    pixels. feTurbulence is reproducible by specification and browsers still agree only
    approximately on what to paint from it. Stated now, while adding the first feature that
    depends on it, rather than left for somebody to rediscover when a screenshot test flakes.

  • docs/explanation/prior_art.md: shape grammars move from future to load-bearing,
    with the finding that no open-source Python CGA implementation exists — the reference one
    is commercial, inside Esri CityEngine — so the formalism is reused rather than a library.
    Notan, aerial perspective and COCO-Stuff are added as load-bearing; physically based sky
    models (Preetham, Hosek-Wilkie) are recorded as examined and rejected, since they solve a
    radiometric problem this compiler does not have.

  • PuppetSpec.pose_angles and .expression_states raise UnknownPoseError and
    UnknownExpressionError
    on a name the puppet does not declare, rather than a bare
    KeyError. Both are also KeyError — following the precedent UnknownPuppetError
    already set — so except KeyError and the documented Raises: KeyError on both
    methods keep working unchanged.

Fixed

  • extreme_close_up framed the forehead, not the eyes. Its crop landmark (eyes)
    sits inside the face rather than at its edge, and the anchoring rule bottom-anchors
    every crop line — which put the eyes exactly on the panel's bottom edge and the rest
    of the eye region, and the whole face centre, below it. extreme_close_up now
    carries footroom: 0.45, the only lever that can move a crop line off the bottom
    edge; headroom cannot, because it shifts the figure down and shrinks it by exactly
    the same amount. docs/reference/shot_types.md explains why in the Resolution
    section, and the table now shows the footroom instead of —.
  • scenet check said nothing about an unknown pose: or expression:, then scenet build crashed with a bare KeyError. The IR validates syntax and structure
    without knowing the puppet library exists, so pose: smirking passed every check and
    only failed once the solver tried to look it up. check now resolves every cast
    member's reference, pose and expression against the puppet library — reading it
    once per document, only when there is a cast to check — and reports unknown-pose,
    unknown-expression and (newly reachable from check) unknown-puppet, each with a
    ruleId and a location naming the field. This closes the check/build gap
    entirely rather than for two known bad field names: --deep (below) extends the same
    guarantee to layout and balloon-placement.

Upgrading

Nothing was removed and no document stops compiling. Four things a caller should expect
to see move:

  • Every panel that asks for long_shot or wide renders smaller. The two rungs at
    the wide end of the ladder were degenerate with no environment to show, and now that
    there is one they are not. This is the change most likely to be visible in your own
    panels.
  • extreme_close_up frames the eyes rather than the forehead. Any panel using it
    renders differently, and correctly, for the first time.
  • Panel Core output has changed for any panel with a caption. CoreCaption gained
    fill and ink, and PanelCore gained backdrop. All three are defaulted or
    optional, so a 0.5.0 document still parses and format_version did not move — but a
    golden file captured against 0.5.0 will differ.
  • Eleven names joined scenet.__all__ — SettingSpec, Mass, MassKind, Plane,
    Spans, Horizon, TimeOfDay, Weather, PLACES, Place and CaptionTone.
    Additions only; nothing was removed or renamed.

Known limitations

  • A caption's tone is checked against the palette, not against the panel it lands in.
    The contrast floors hold between every tone and every rung of the ladder, which is what
    makes them enforceable — but nothing warns you that this caption was placed over a
    foreground mass it barely separates from. The information is all present by the time
    the box is placed; the check is not written.
  • No yellow caption box. The classic yellow locale box would be the first
    non-neutral value in the codebase, and the language has no colour policy to put it
    under yet. The three tones that shipped are neutral greys from an existing ladder.
  • A caption tone is per caption, with no panel-level default. A letterer would set
    one once for a page; here you write it on each box that wants it.
  • A backdrop is tonal masses, and will not draw a specific building. That is the
    design, not a gap — but it does mean place: docks gives you the docks in the way a
    thumbnail does, not in the way a background artist would.

Install

pip install scenet==0.6.0

The VS Code extension is the attached scenet.vsix:
Extensions -> ... -> Install from VSIX...

Documentation |
Playground