Repository navigation
v0.6.0
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 nosettingblock at all. Captions (0.4.0) shipped the
cheap half of establishing place — alocalebox can sayMIDNIGHT. 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,wateroutdoors,ceiling,floor,furniture,wall,
windowindoors. 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 arebuilding-otherandsky-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 noplacefield at all — the same treatmentalice left_of bobgets. -
planereuses the existing painter's order rather than introducing a second one.
The three backdrop planes take negative depths;foregroundtakes 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. -
timeandweather.timesupplies the two ends of the value ladder rather than
tinting a daytime panel, sonightis a darker, narrower ladder — and the ladder stays
monotonic in depth at every hour by construction.weatheraddsfogas a
feTurbulenceveil, andrainandsnowas that veil plus falling marks. -
CoreBackdropon Panel Core, carrying fully resolved numeric polygons and tone
values — the same discipline ascapsules,blobsandface_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 noformat_versionbump. -
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 checkreportsunknown-placeandconflicting-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.mdsection 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
tonekey 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 thedayrow by index rather than
restated, so lettering and backdrop cannot drift apart as either is tuned.paperis
the default, so no existing panel moves. No free-formfill:, and no yellow: an open
colour field would be this language's one open vocabulary, and the classic yellow
localebox would be the first non-neutral value in the codebase. -
inkinverts the lettering to paper — reversed type — chosen by contrast in the
solver and carried onCoreCaptionasfillandink. 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 noformat_versionbump was needed. -
The lettering floor is enforced rather than asserted.
contrast_ratioin
solve/backdrop.pymeasures 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
tonerow and section indocs/reference/language.md, and
fill/inkindocs/reference/panel_core.md. -
scenet check --deep. Runs the full compiler on any document that passes the
cheap checks, to additionally catchlayoutandballoon-placementfailures — the
two rules in the catalogue that were in the catalogue but unreachable fromcheck.
Off by default: it costs a real compile, including font metrics, andcheckstays
the cheap pass it is documented as unless asked otherwise.
Changed
-
long_shotreframes noticeably wider, andwidewith it — headroom0.14→0.28,
footroom0.06→0.10.solve/camera.pyadmitted the problem in a comment: with no
environment to show,long_shotandfull_shotcrop 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 forlong_shotorwiderenders smaller than it did. The comment is gone and
docs/reference/shot_types.mdis updated. -
PanelSyntaxErrorcarries an optionalruleandloc, 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.feTurbulenceis 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_anglesand.expression_statesraiseUnknownPoseErrorand
UnknownExpressionErroron a name the puppet does not declare, rather than a bare
KeyError. Both are alsoKeyError— following the precedentUnknownPuppetError
already set — soexcept KeyErrorand the documentedRaises: KeyErroron both
methods keep working unchanged.
Fixed
extreme_close_upframed 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_upnow
carriesfootroom: 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.mdexplains why in the Resolution
section, and the table now shows the footroom instead of—.scenet checksaid nothing about an unknownpose:orexpression:, thenscenet buildcrashed with a bareKeyError. The IR validates syntax and structure
without knowing the puppet library exists, sopose: smirkingpassed every check and
only failed once the solver tried to look it up.checknow resolves every cast
member'sreference,poseandexpressionagainst the puppet library — reading it
once per document, only when there is a cast to check — and reportsunknown-pose,
unknown-expressionand (newly reachable fromcheck)unknown-puppet, each with a
ruleIdand a location naming the field. This closes thecheck/buildgap
entirely rather than for two known bad field names:--deep(below) extends the same
guarantee tolayoutandballoon-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_shotorwiderenders 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_upframes 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.
CoreCaptiongained
fillandink, andPanelCoregainedbackdrop. All three are defaulted or
optional, so a 0.5.0 document still parses andformat_versiondid 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,PlaceandCaptionTone.
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
localebox 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 meanplace: docksgives you the docks in the way a
thumbnail does, not in the way a background artist would.
Install
pip install scenet==0.6.0The VS Code extension is the attached scenet.vsix:
Extensions -> ... -> Install from VSIX...