Solving#
Framing, placement, lettering and balloons. These modules are internal – they are documented because the decisions in them are the interesting part of the project, not because their signatures are promised to stay put.
scenet.solve.camera#
.. py:module:: scenet.solve.camera
Camera framing: shot type into scale and vertical placement.
The central rule, and the one most easily got wrong: a shot type names where the frame cuts the body, not what fraction of the panel a figure fills. Encoding the fraction instead bakes in one body and one pose, so a child and an adult would come out the same height. See docs/reference/shot_types.md, which is normative.
The second rule: one camera, one scale. A camera has a single focal length, so every actor at the same distance is scaled identically and a taller character is taller in frame. Scaling each actor to fit its own crop would silently erase height differences, which is precisely what a comic uses to characterise people.
.. py:class:: ShotSpec
- module:
scenet.solve.camera
Bases: :py:class:
objectA crop landmark, and the empty space left above the head and below the feet.
.. py:attribute:: ShotSpec.crop
- module:
scenet.solve.camera
- type:
~scenet.assets.contract.Landmark
.. py:attribute:: ShotSpec.headroom
- module:
scenet.solve.camera
- type:
float
.. py:attribute:: ShotSpec.footroom
- module:
scenet.solve.camera
- type:
float
.. py:method:: ShotSpec.init(crop, headroom, footroom=0.0)
- module:
scenet.solve.camera
.. py:class:: CameraSolution
- module:
scenet.solve.camera
Bases: :py:class:
objectThe camera’s verdict for a panel: one scale, shared by every actor.
.. py:attribute:: CameraSolution.scale
- module:
scenet.solve.camera
- type:
float
.. py:attribute:: CameraSolution.headroom
- module:
scenet.solve.camera
- type:
float
.. py:attribute:: CameraSolution.footroom
- module:
scenet.solve.camera
- type:
float
.. py:attribute:: CameraSolution.panel_height
- module:
scenet.solve.camera
- type:
float
.. py:attribute:: CameraSolution.shot
- module:
scenet.solve.camera
- type:
~scenet.ir.ShotType
.. py:attribute:: CameraSolution.reference
- module:
scenet.solve.camera
- type:
str
.. py:attribute:: CameraSolution.pullback
- module:
scenet.solve.camera
- type:
float
.. py:property:: CameraSolution.was_pulled_back
- module:
scenet.solve.camera
- type:
bool
Whether the camera had to retreat from the requested framing.
Surfaced to the user through
- attr:
CompileResult.notes <scenet.pipeline.CompileResult.notes>. Retreating silently would leave a panel that quietly is not the shot that was asked for.
.. py:method:: CameraSolution.pulled_back_to(scale)
- module:
scenet.solve.camera
Retreat the camera until the cast fits across the frame.
A shot type is a statement about vertical framing – where the frame cuts the body. When several actors cannot fit side by side at that scale, a real camera moves back: everyone gets smaller and more of the body comes into view. So the requested shot behaves as an upper bound on tightness rather than an exact contract, and the amount of retreat is recorded here so the result stays inspectable rather than mysterious.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.camera.CameraSolution``
.. py:property:: CameraSolution.head_top_y
- module:
scenet.solve.camera
- type:
float
Where the reference actor’s head-top lands.
.. py:method:: CameraSolution.root_y_framed(puppet)
- module:
scenet.solve.camera
Place this puppet by its own head, as if framed alone.
Used for actors that share no ground line with anyone: each is composed independently within the frame.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
.. py:method:: CameraSolution.root_y_on_ground(puppet, ground_y)
- module:
scenet.solve.camera
Place this puppet so its feet meet a given ground line.
This is what makes two characters of different heights stand together convincingly: feet align, heads do not.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
.. py:method:: CameraSolution.feet_below_root(puppet)
- module:
scenet.solve.camera
How far below the root joint this puppet’s feet sit, at this camera scale.
- type puppet:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetSpec``
- param puppet:
The character being placed.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- returns:
Distance in panel units.
.. py:method:: CameraSolution.ground_y_of(puppet, root_y)
- module:
scenet.solve.camera
The ground line a puppet stands on, given where its root joint is.
The inverse of
- meth:
root_y_on_ground <scenet.solve.camera.CameraSolution.root_y_on_ground>, and howground_shared_withgets its target: take one actor’s ground line, then place the other so their feet meet it.- type puppet:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.assets.contract.PuppetSpec``
- param puppet:
The character.
- type root_y:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param root_y:
Where its root joint sits vertically.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- returns:
The y coordinate of its feet.
.. py:method:: CameraSolution.init(scale, headroom, footroom, panel_height, shot, reference, pullback=1.0)
- module:
scenet.solve.camera
.. py:function:: headroom_for(shot, angle)
- module:
scenet.solve.camera
Empty space to leave above the head, as a fraction of panel height.
A shot type has two halves and they use different units. The crop landmark is anatomical – the waist, the chest, the shoulders – which is what stops a shot type baking in one body and one pose. The headroom is a plain fraction of panel height, because it is about composition within the frame rather than about anatomy. See
docs/reference/shot_types.md, which is normative.Angle changes headroom rather than perspective. This compiler is orthographic, so a tilted camera cannot foreshorten anything – but the amount of air above the head is the compositional cue readers actually take from an angle, and it is one that survives being drawn flat.
A low camera looks up and the subject looms, so headroom tightens; a high camera looks down and it opens out.
- type shot:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.ShotType``
- param shot:
The requested framing.
- type angle:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.CameraAngle``
- param angle:
The camera height.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- returns:
Headroom as a fraction of panel height, never below
MINIMUM_ANGLE_HEADROOMfor a tilted camera – so thatextreme_close_up, whose base headroom is zero, still shifts under an angle instead of staying flush against the top edge.
.. admonition:: Example
from scenet import CameraAngle, ShotType from scenet.solve.camera import headroom_for [ … headroom_for(ShotType.MEDIUM_SHOT, angle) … for angle in (CameraAngle.LOW, CameraAngle.EYE_LEVEL, CameraAngle.HIGH) … ] [0.05, 0.1, 0.16000000000000003]
.. py:function:: visible_height(puppet, shot)
- module:
scenet.solve.camera
Native height of the portion of the body the frame will show.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
.. py:function:: solve_camera(reference, *, shot, angle, panel_height, footroom=None)
- module:
scenet.solve.camera
Resolve the camera against a reference actor.
Everything else in the panel inherits this scale. The reference is the actor the shot is composed on – by convention the first in the cast, which is the one the author wrote first and therefore the one the panel is about.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.camera.CameraSolution``
scenet.solve.staging#
.. py:module:: scenet.solve.staging
Horizontal placement, vertical grounding and draw order.
This is where Cassowary earns its place. The arithmetic is trivial – centring a figure on a third is one division – but the conflicts are not. Two actors both asked to stand centre must be pushed apart; a crowded panel must let figures bleed off the edge rather than overlap. Expressed as priorities, that resolves itself. Written by hand it becomes an ever-growing cascade of special cases.
Priorities used:
required actors never overlap, and keep their declared left-to-right order
strong actors stay inside the panel
weak actors sit on their requested anchor
Bounds are deliberately strong rather than required. Letting a figure bleed past the panel edge is ordinary comics practice, and far better than refusing to compile a crowded panel.
.. py:class:: Placement
- module:
scenet.solve.staging
Bases: :py:class:
objectWhere one actor’s root joint ends up, and how it is drawn.
.. py:attribute:: Placement.actor_id
- module:
scenet.solve.staging
- type:
str
.. py:attribute:: Placement.reference
- module:
scenet.solve.staging
- type:
str
.. py:attribute:: Placement.pose
- module:
scenet.solve.staging
- type:
str
.. py:attribute:: Placement.expression
- module:
scenet.solve.staging
- type:
str
.. py:attribute:: Placement.x
- module:
scenet.solve.staging
- type:
float
.. py:attribute:: Placement.y
- module:
scenet.solve.staging
- type:
float
.. py:attribute:: Placement.scale
- module:
scenet.solve.staging
- type:
float
.. py:attribute:: Placement.facing_right
- module:
scenet.solve.staging
- type:
bool
.. py:attribute:: Placement.depth
- module:
scenet.solve.staging
- type:
int
.. py:property:: Placement.origin
- module:
scenet.solve.staging
- type:
~scenet.geom.Point
Where this actor’s root joint lands, as a point.
.. py:method:: Placement.init(actor_id, reference, pose, expression, x, y, scale, facing_right, depth)
- module:
scenet.solve.staging
.. py:function:: horizontal_order(panel)
- module:
scenet.solve.staging
A total left-to-right order over the cast.
Declared
left_ofrelations are honoured; everything else is broken by anchor position and then by actor id. The tiebreak matters more than it looks: the solver needs a total order to write non-overlap constraints against, and it must be the same total order on every run or the output stops being deterministic.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]`
.. py:function:: depth_order(panel)
- module:
scenet.solve.staging
Painter’s order from
in_front_of/behindrelations.Depth is the longest chain of actors behind a given one, so anything not mentioned stays at zero and the common case adds no noise to the output.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`int`]`
.. py:function:: solve_staging(panel, library, camera=None)
- module:
scenet.solve.staging
Resolve every actor’s position, scale, facing and draw order.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`tuple`\ \[:py:class:`~scenet.solve.staging.Placement`, :py:data:`…<Ellipsis>`], :py:class:`~scenet.solve.camera.CameraSolution`]`
scenet.solve.backdrop#
.. py:module:: scenet.solve.backdrop
Resolving a setting into tonal masses: geometry, value, and draw order.
The solver still never sees artwork. A backdrop reaches it as the same kind of geometric contract everything else does – polygons, a value, an integer depth – and the emitter is left with nothing to decide.
Why masses rather than 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 tonal masses have no perspective to get wrong. That is the structural argument; the other is that this is simply how comics establish place.
Notan – the Japanese light/dark mass principle, which entered Western art teaching through Arthur Wesley Dow’s Composition (1899) – holds that place is read from the arrangement of masses rather than from rendered detail. Layered silhouette depth gives the arrangement: foreground near-black, each receding plane paler. And aerial perspective supplies the parametric rule for free – with distance, value contrast drops toward the atmosphere colour. Three numbers per plane, monotonic in depth. That is notation, not interpretation, which is what makes it belong in a compiler.
Shape grammars, as a formalism rather than a library#
Silhouette profiles are generated with the split/repeat/subdivide operations of CGA
shape grammar (Mueller et al., Procedural Modeling of Buildings, SIGGRAPH 2006). It is
reused as a formalism: there is no open-source Python implementation of CGA, and the
reference one is commercial, inside Esri CityEngine. See
docs/explanation/prior_art.md.
The discipline that comes with it is worth stating: how many of a thing there are is derived from the geometry – a wider span gets more bays – and only how big each one is comes from the seed. Random counts make a backdrop flicker between panels that ought to look related.
Determinism#
Every profile is seeded from the declared content and the panel size, through
blake2b – never a clock, never hash(), which is salted per process and would agree
with itself all day while disagreeing with tomorrow’s build. Every profile is also
generated inside the frame by construction, so there is nothing to clip; shapely stays
where it earns its place, in the balloon occlusion cost.
.. py:data:: ATMOSPHERE
- module:
scenet.solve.backdrop
- value:
4
the atmosphere itself.
- type:
The rung beyond the farthest plane
.. py:data:: FALL_CONTRAST_THRESHOLD
- module:
scenet.solve.backdrop
- value:
0.5
Above this lightness – of the sky as the cloud leaves it, not of the bare sky – rain is drawn in ink rather than in the paper colour. Inkers flip the same way and for the same reason: a white streak over a noon sky is invisible and a black one over midnight is too. The choice is made here rather than in the emitter, because it is a decision about the panel.
Snow does not flip. Snow is white – a convention rather than a value on the depth ladder, and a black snowflake is not a thing any comic has ever drawn. The overcast veil above is what gives it something to read against.
.. py:data:: FOREGROUND_SPAN_KEEP
- module:
scenet.solve.backdrop
- value:
0.6
How much of its declared span a foreground mass keeps, held against its outer edge.
A foreground mass is a repoussoir – the doorway or the wall you are standing behind, which frames the panel.
leftreaches past the middle of the panel, and a foreground mass that wide stops framing the composition and starts burying it: the first contact sheet hadalleyhiding everything of the figure above the knees. A full-width foreground is left alone, because asking for one is asking for a silhouette.
.. py:data:: GROUND_START
- module:
scenet.solve.backdrop
- type:
dict[~scenet.ir.Plane, float]
- value:
{Plane.FAR: 0.0, Plane.FOREGROUND: 0.68, Plane.MID: 0.16, Plane.NEAR: 0.4}
Where a ground-like mass begins below the horizon, as a fraction of the distance from the horizon to the bottom edge.
Ground, floor and water all run to the bottom edge, so a nearer one drawn from the horizon would bury every plane behind it – the near quayside would simply erase the water. Starting each one lower leaves the planes behind it showing as bands, and that stack of receding bands is the depth cue.
The exception is the farthest ground-like mass in a panel, which meets the horizon itself: there is nothing behind it to reveal, and a strip of bare paper along the horizon reads as a mistake. See
_ground_start.
.. py:data:: PLANE_SCALE
- module:
scenet.solve.backdrop
- type:
dict[~scenet.ir.Plane, float]
- value:
{Plane.FAR: 0.55, Plane.FOREGROUND: 1.45, Plane.MID: 0.8, Plane.NEAR: 1.0}
How much larger the same mass is drawn nearer the reader. Size perspective alongside aerial perspective: a near hill is not merely darker than a far one, it is bigger.
.. py:data:: TONE_INDEX
- module:
scenet.solve.backdrop
- type:
dict[~scenet.ir.Plane, int]
- value:
{Plane.FAR: 3, Plane.FOREGROUND: 0, Plane.MID: 2, Plane.NEAR: 1}
Which rung of the ladder each plane takes. Front to back, so the foreground is the darkest and the far plane the palest of the four.
.. py:class:: ResolvedAtmosphere
- module:
scenet.solve.backdrop
Bases: :py:class:
objectWhat the air is doing, resolved.
.. attribute:: time
When the panel happens.
.. attribute:: weather
What is falling, if anything.
.. attribute:: tone
The atmosphere’s own value at this hour.
.. attribute:: veil
The turbulence layer – fog, or cloud for rain and snow.
.. attribute:: streaks
Rain, as
(start, end)pairs all at one angle... attribute:: flecks
Snow, as discs.
.. attribute:: streak_width
Stroke width for a streak, in panel units.
.. attribute:: fall_tone
What rain and snow are drawn in, chosen against the atmosphere so they stay visible at every hour.
.. py:attribute:: ResolvedAtmosphere.time
- module:
scenet.solve.backdrop
- type:
~scenet.ir.TimeOfDay
.. py:attribute:: ResolvedAtmosphere.weather
- module:
scenet.solve.backdrop
- type:
~scenet.ir.Weather
.. py:attribute:: ResolvedAtmosphere.tone
- module:
scenet.solve.backdrop
- type:
str
.. py:attribute:: ResolvedAtmosphere.veil
- module:
scenet.solve.backdrop
- type:
~scenet.solve.backdrop.ResolvedVeil | None
.. py:attribute:: ResolvedAtmosphere.streaks
- module:
scenet.solve.backdrop
- type:
tuple[tuple[~scenet.geom.Point, ~scenet.geom.Point], …]
.. py:attribute:: ResolvedAtmosphere.flecks
- module:
scenet.solve.backdrop
- type:
tuple[~scenet.geom.Circle, …]
.. py:attribute:: ResolvedAtmosphere.streak_width
- module:
scenet.solve.backdrop
- type:
float
.. py:attribute:: ResolvedAtmosphere.fall_tone
- module:
scenet.solve.backdrop
- type:
str
.. py:method:: ResolvedAtmosphere.init(time, weather, tone, veil=None, streaks=(), flecks=(), streak_width=0.0, fall_tone=’’)
- module:
scenet.solve.backdrop
.. py:class:: ResolvedBackdrop
- module:
scenet.solve.backdrop
Bases: :py:class:
objectEverything behind, around and in front of the cast.
.. attribute:: horizon
Where the ground meets what is behind it, in panel units.
.. attribute:: masses
The tonal masses, back to front.
.. attribute:: atmosphere
The air, or None when the weather is clear.
.. attribute:: seed
What every profile in here was generated from.
.. py:attribute:: ResolvedBackdrop.horizon
- module:
scenet.solve.backdrop
- type:
float
.. py:attribute:: ResolvedBackdrop.seed
- module:
scenet.solve.backdrop
- type:
int
.. py:attribute:: ResolvedBackdrop.masses
- module:
scenet.solve.backdrop
- type:
tuple[~scenet.solve.backdrop.ResolvedMass, …]
.. py:attribute:: ResolvedBackdrop.atmosphere
- module:
scenet.solve.backdrop
- type:
~scenet.solve.backdrop.ResolvedAtmosphere | None
.. py:method:: ResolvedBackdrop.occluders()
- module:
scenet.solve.backdrop
The masses a balloon should prefer not to sit on, with their planes.
Masses are not exclusions. Balloons sit over backgrounds routinely; that is the point of having a background. This feeds a soft cost instead.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`tuple`\ \[:py:class:`tuple`\ \[:py:class:`~scenet.geom.Point`, :py:data:`…<Ellipsis>`], :py:class:`~scenet.ir.Plane`], :py:data:`…<Ellipsis>`]`
.. py:method:: ResolvedBackdrop.init(horizon, seed, masses=(), atmosphere=None)
- module:
scenet.solve.backdrop
.. py:class:: ResolvedMass
- module:
scenet.solve.backdrop
Bases: :py:class:
objectOne tonal mass, resolved to a numeric polygon.
.. attribute:: id
Stable identifier,
m0,m1, … back to front... attribute:: kind
What it is made of, kept so a Core document stays readable.
.. attribute:: plane
How far back it sits.
.. attribute:: depth
Its place in the painter’s order, shared with the actors.
.. attribute:: tone
The
#rrggbbfill... attribute:: polygon
The silhouette, in panel coordinates.
.. py:attribute:: ResolvedMass.id
- module:
scenet.solve.backdrop
- type:
str
.. py:attribute:: ResolvedMass.kind
- module:
scenet.solve.backdrop
- type:
~scenet.ir.MassKind
.. py:attribute:: ResolvedMass.plane
- module:
scenet.solve.backdrop
- type:
~scenet.ir.Plane
.. py:attribute:: ResolvedMass.depth
- module:
scenet.solve.backdrop
- type:
int
.. py:attribute:: ResolvedMass.tone
- module:
scenet.solve.backdrop
- type:
str
.. py:attribute:: ResolvedMass.polygon
- module:
scenet.solve.backdrop
- type:
tuple[~scenet.geom.Point, …]
.. py:method:: ResolvedMass.init(id, kind, plane, depth, tone, polygon)
- module:
scenet.solve.backdrop
.. py:class:: ResolvedVeil
- module:
scenet.solve.backdrop
Bases: :py:class:
objectThe turbulence layer, as parameters rather than as pixels.
SVG has Perlin noise built in through
feTurbulence, and the specification includes reference code, so a fixed seed is reproducible by definition – the emitted text is identical. Browsers agree only approximately on what to paint from it, which is fine and is why the determinism contract is on the SVG text and has never been on pixels. Seedocs/reference/language.md... py:attribute:: ResolvedVeil.tone
- module:
scenet.solve.backdrop
- type:
str
.. py:attribute:: ResolvedVeil.opacity
- module:
scenet.solve.backdrop
- type:
float
.. py:attribute:: ResolvedVeil.frequency
- module:
scenet.solve.backdrop
- type:
float
.. py:attribute:: ResolvedVeil.octaves
- module:
scenet.solve.backdrop
- type:
int
.. py:attribute:: ResolvedVeil.seed
- module:
scenet.solve.backdrop
- type:
int
.. py:method:: ResolvedVeil.init(tone, opacity, frequency, octaves, seed)
- module:
scenet.solve.backdrop
.. py:function:: contrast_ratio(one, other)
- module:
scenet.solve.backdrop
How far apart two neutral values read, on the WCAG scale.
Measured in relative luminance, not in the OKLab lightness
lightnessreturns, and the two sitting in one file is deliberate rather than an oversight. The ladder is spaced in OKLab because that predicts even perceived steps, which is what makes four planes recede evenly. Legibility is checked here because WCAG is where the published threshold comes from, and a floor is only worth stating if it is the number the standard states.- type one:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param one:
A
#rrggbbneutral grey.- type other:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param other:
The value to compare it against.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- returns:
A ratio in
1.0 .. 21.0, symmetric in its arguments.
.. admonition:: Example
from scenet.solve.backdrop import contrast_ratio round(contrast_ratio(“#000000”, “#ffffff”), 1) 21.0
.. py:function:: depth_for(plane, *, frontmost_actor)
- module:
scenet.solve.backdrop
Painter’s order for a plane, against the cast that is already placed.
- type plane:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.Plane``
- param plane:
How far back the mass sits.
- type frontmost_actor:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- param frontmost_actor:
The largest depth any actor in this panel was given.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- returns:
A depth for the existing
(depth, id)sort. Backdrop planes are negative, so they land behind every actor; the foreground takes one above the frontmost, so it draws over the cast and still under the lettering.
.. py:function:: lightness(tone)
- module:
scenet.solve.backdrop
The OKLab lightness a neutral grey sits at.
The inverse of how the ladder was built, so that monotonicity is checkable rather than asserted. For a neutral, OKLab’s matrices cancel and
Lis the cube root of the linear value, which is the whole conversion – and that linear value is exactly the relative luminancecontrast_ratioweighs, so the two share one linearisation rather than each carrying its own copy of the sRGB transfer curve.- type tone:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param tone:
A
#rrggbbneutral grey.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- returns:
Lightness in
0.0 .. 1.0.
.. admonition:: Example
from scenet.solve.backdrop import lightness round(lightness(“#ffffff”), 3) 1.0
.. py:function:: seed_for(setting, width, height)
- module:
scenet.solve.backdrop
A stable seed for one panel’s backdrop.
Derived from the declared content and the panel size, so the same source produces the same silhouettes forever – and two panels that differ get different ones.
blake2brather thanhash(), deliberately and load-bearingly:hash()is salted per process, so a seed derived from it agrees with itself all day and disagrees with tomorrow’s build. That is exactly the failure a golden-file test cannot see.- type setting:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.SettingSpec``
- param setting:
The declared setting.
- type width:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param width:
Panel width in panel units.
- type height:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param height:
Panel height in panel units.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- returns:
A 32-bit seed.
.. py:function:: solve_backdrop(setting, panel, *, frontmost_actor=0)
- module:
scenet.solve.backdrop
Resolve a declared setting into masses, tones and atmosphere.
- type setting:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.SettingSpec``
- param setting:
The declared setting.
- type panel:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.geom.BBox``
- param panel:
The panel rectangle. Not the margined frame: a backdrop bleeds to the edge, exactly as artwork does, and only lettering is kept inside a margin.
- type frontmost_actor:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- param frontmost_actor:
The largest depth any actor was given, so a foreground mass can be placed in front of the whole cast.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.backdrop.ResolvedBackdrop` | :py:obj:`None``
- returns:
The resolved backdrop, or None when there is nothing to draw – which is what every panel written before this block existed gets.
.. admonition:: Example
from scenet.geom import BBox from scenet.ir import SettingSpec from scenet.solve.backdrop import solve_backdrop solve_backdrop(SettingSpec(), BBox(0.0, 0.0, 800.0, 600.0)) is None True
.. py:function:: tone_for(kind, plane, time)
- module:
scenet.solve.backdrop
The value a mass is filled with.
Value comes from the plane and from nothing else, which is what keeps the notan reading literal: masses at one distance read as one mass, and the arrangement is what carries the place. Two kinds sit off their own plane’s rung, and both stay on the ladder rather than beside it:
skyis the atmosphere. It is at infinite distance whatever plane it was filed under, so it always takes the last rung.windowis a hole showing a more distant plane, so it takes the rung one step farther back than the wall it is cut into.
- type kind:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.MassKind``
- param kind:
What the mass is made of.
- type plane:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.Plane``
- param plane:
How far back it sits.
- type time:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.TimeOfDay``
- param time:
When the panel happens, which selects the ladder.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
A
#rrggbbneutral grey.
.. admonition:: Example
from scenet.ir import MassKind, Plane, TimeOfDay from scenet.solve.backdrop import tone_for tone_for(MassKind.SKY, Plane.FAR, TimeOfDay.NIGHT) ‘#4d4d4d’
scenet.solve.text#
.. py:module:: scenet.solve.text
Text measurement and line breaking.
Nothing downstream can proceed without this. A balloon’s size is a function of its text, wrapped at some measure, in a specific font – and placement, occlusion and reading order all depend on that size. So wrapping is decided here, during compilation, and the result is carried through Panel Core as explicit lines. The emitter never re-measures and therefore can never disagree with the solver.
Determinism demands the font be fixed. It arrives as a declared dependency rather than a system lookup precisely because “whatever font this machine happens to have” is the opposite of reproducible.
.. py:data:: ITALIC_FONT_PATH
- module:
scenet.solve.text
- value:
PosixPath(‘/home/runner/work/scenet/scenet/.venv/lib/python3.14/site-packages/font_source_sans_pro/files/SourceSansPro-It.ttf’)
The italic face of the same family, for the caption kinds letterers set in italic. A real font file rather than a skew transform: a synthetic oblique measures as the roman face and draws as neither, which is exactly the disagreement between measurement and rendering this module exists to prevent. It costs nothing to use – it ships in the same declared dependency.
.. py:data:: BOLD_ITALIC_FONT_PATH
- module:
scenet.solve.text
- value:
PosixPath(‘/home/runner/work/scenet/scenet/.venv/lib/python3.14/site-packages/font_source_sans_pro/files/SourceSansPro-BoldIt.ttf’)
“There’s almost no plain bold in comics dialogue. Typically, bold italic is used when emphasis is placed on a word.” A real file for the same reason the italic is one.
- type:
The bold italic face of the same family, for emphasis. Blambot
.. py:data:: DISPLAY_FONT_PATH
- module:
scenet.solve.text
- value:
PosixPath(‘/home/runner/work/scenet/scenet/src/scenet/fonts/Bangers-Regular.ttf’)
Bangers, by Vernon Adams, drawn in the manner of mid-century comic cover lettering. Not of the same family, and not meant to be – a sound effect is letters treated as picture, not as text. No package carries it, so it is vendored under
scenet/fonts/with its licence, the SIL OFL 1.1, beside it. A file of the package rather than a system font, for the same reason as every face.- type:
The display face sound effects are lettered in
.. py:data:: SHIPPED_FACES
- module:
scenet.solve.text
- type:
dict[~scenet.ir.Face, ~pathlib.Path]
- value:
{Face.BOLD_ITALIC: PosixPath(‘/home/runner/work/scenet/scenet/.venv/lib/python3.14/site-packages/font_source_sans_pro/files/SourceSansPro-BoldIt.ttf’), Face.DISPLAY: PosixPath(‘/home/runner/work/scenet/scenet/src/scenet/fonts/Bangers-Regular.ttf’), Face.ITALIC: PosixPath(‘/home/runner/work/scenet/scenet/.venv/lib/python3.14/site-packages/font_source_sans_pro/files/SourceSansPro-It.ttf’), Face.REGULAR: PosixPath(‘/home/runner/work/scenet/scenet/.venv/lib/python3.14/site-packages/font_source_sans_pro/files/SourceSansPro-Regular.ttf’)}
The shipped family, face by face.
.. py:data:: Run
- module:
scenet.solve.text
what a line of lettering is made of.
- type:
A run of text in one face
alias of :py:class:
tuple\ [:py:class:str, :py:class:~scenet.ir.Face]
.. py:data:: PAIR_LOOKUP
- module:
scenet.solve.text
- value:
2
pair adjustment, and the extension that wraps a lookup of another type when a table outgrows 16-bit offsets.
- type:
GPOS lookup types, from the OpenType specification
.. py:class:: Styled
- module:
scenet.solve.text
Bases: :py:class:
objectText with the face every character is set in.
What lettering is measured and drawn as once emphasis is read:
I _told_ youis the plain textI told youwithtoldin bold italic. A string of one face is the same thing with every character in that face, and measures exactly as the string always did... attribute:: text
The characters, markers already removed.
.. attribute:: faces
One face per character.
.. py:attribute:: Styled.text
- module:
scenet.solve.text
- type:
str
.. py:attribute:: Styled.faces
- module:
scenet.solve.text
- type:
tuple[~scenet.ir.Face, …]
.. py:method:: Styled.of(text, face=Face.REGULAR)
- module:
scenet.solve.text
- classmethod:
Text all in one face. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~scenet.solve.text.Styled\``
.. py:method:: Styled.slice(start, end) :module: scenet.solve.text
The characters from `start` up to `end`, with their faces. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`\~scenet.solve.text.Styled\``
.. py:property:: Styled.runs :module: scenet.solve.text :type: tuple[tuple[str, ~scenet.ir.Face], …]
The text cut wherever the face changes, as `(text, face)` pairs.
.. py:method:: Styled.init(text, faces) :module: scenet.solve.text
.. py:function:: styled(text, base=Face.REGULAR)
- module:
scenet.solve.text
Read a line as written into the faces it is lettered in.
- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param text:
Dialogue or a caption, emphasis markers and all.
- type base:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.Face``
- param base:
The face the line is set in – italic for most captions. Emphasis is bold italic whatever the base, which is the letterers’ convention for a stressed word in an italic caption as much as in a roman balloon.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.Styled``
- returns:
The text without its markers, each character in its face.
- raises EmphasisError:
A span was opened and never closed. The IR refuses such text, so this only happens to a caller building lettering by hand.
.. admonition:: Example
from scenet.solve.text import styled [(text, face.value) for text, face in styled(“I told you”).runs] [(‘I ‘, ‘regular’), (‘told’, ‘bold_italic’), (’ you’, ‘regular’)]
.. py:class:: TextBlock
- module:
scenet.solve.text
Bases: :py:class:
objectWrapped text, measured.
.. py:attribute:: TextBlock.lines
- module:
scenet.solve.text
- type:
tuple[str, …]
.. py:attribute:: TextBlock.width
- module:
scenet.solve.text
- type:
float
.. py:attribute:: TextBlock.height
- module:
scenet.solve.text
- type:
float
.. py:attribute:: TextBlock.font_size
- module:
scenet.solve.text
- type:
float
.. py:attribute:: TextBlock.line_height
- module:
scenet.solve.text
- type:
float
.. py:attribute:: TextBlock.line_widths
- module:
scenet.solve.text
- type:
tuple[float, …]
.. py:attribute:: TextBlock.runs
- module:
scenet.solve.text
- type:
tuple[tuple[tuple[str, ~scenet.ir.Face], …], …]
Each line cut into runs of one face. A line with no emphasis is one run.
.. py:property:: TextBlock.aspect
- module:
scenet.solve.text
- type:
float
Width divided by height, or
0.0for an empty block.The quantity the line breaker optimises. Lettering convention wants a balloon wider than it is tall – see
TARGET_ASPECT.
.. py:property:: TextBlock.raggedness
- module:
scenet.solve.text
- type:
float
How unbalanced the lines are, from 0 (equal) to nearly 1 (one line tiny).
.. py:method:: TextBlock.init(lines, width, height, font_size, line_height, line_widths=(), runs=())
- module:
scenet.solve.text
.. py:data:: FAMILY_NAME
- module:
scenet.solve.text
- value:
1
the family and the style within it, as a font’s own four-face (regular, italic, bold, bold italic) naming gives them. The legacy pair rather than the typographic one, because it is what a renderer matches
font-familyagainst across the most systems.- type:
nametable entries
.. py:class:: FontMetrics
- module:
scenet.solve.text
Bases: :py:class:
objectAdvance widths and pair kerning, read straight from the font’s own tables.
Kerning is applied, in measurement and in the outlines alike. It used to be ignored, because SVG renderers do not agree on whether to kern
<text>, and a measurement the renderer will not reproduce is worse than a slightly generous one. That holds for--live-textand not for the default: outlines are positioned here, glyph by glyph, so no renderer has a say and every pair adjustment is reproduced exactly... attribute:: path
The file it was read from. Used to open it and nothing else: no path reaches any output.
.. attribute:: sha256
The digest of the file’s bytes, which is what Panel Core names a face by.
.. attribute:: family
The family name from the font’s
nametable... attribute:: style
The style within the family:
Regular,Italic,Bold Italic.Pairs come from the GPOS
kernfeature, or from a legacykerntable in a font that has no GPOS kerning – read with fontTools rather than shaped with HarfBuzz, which Pyodide does not ship. HarfBuzz is the test oracle instead. Only pair adjustments are applied: no ligatures, no contextual alternates, no mark positioning, which is all a Latin line of lettering needs and all that measurement can promise to reproduce... py:method:: FontMetrics.init(path=PosixPath(‘/home/runner/work/scenet/scenet/.venv/lib/python3.14/site-packages/font_source_sans_pro/files/SourceSansPro-Regular.ttf’))
- module:
scenet.solve.text
Open a font and read the tables needed for measurement.
- type path:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~pathlib.Path``- param path:
A TrueType or OpenType file. Defaults to the font that ships as an ordinary dependency of this package – never a system font lookup, because determinism requires the same metrics everywhere.
- raises OSError:
The file cannot be read.
- raises ValueError:
The font has no usable Unicode character map, so no text could be measured against it at all.
.. py:property:: FontMetrics.extent
- module:
scenet.solve.text
- type:
tuple[float, float]
How far the face reaches above and below the baseline, in em units.
The
hheaascender and descender, both as positive distances: what a line of this face can occupy, which is what a sound effect’s footprint is built from.
.. py:method:: FontMetrics.digest(data)
- module:
scenet.solve.text
- staticmethod:
What a font file is known by: the SHA-256 of its bytes, in hex. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`str\``
.. py:property:: FontMetrics.units_per_em :module: scenet.solve.text :type: float
The font's design grid size, from its `head` table.
.. py:method:: FontMetrics.advance(character) :module: scenet.solve.text
Advance width of one character, in em units, before any kerning. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`float\``
.. py:method:: FontMetrics.kerning(left, right) :module: scenet.solve.text
The adjustment between two neighbouring characters, in em units. Negative tightens. Zero for a pair the font does not kern, and for a character the font has no glyph for. .. admonition:: Example >>> from scenet.solve.text import load_metrics >>> load_metrics().kerning("A", "V") < 0 True :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`float\``.. py:method:: FontMetrics.step(character, following=None) :module: scenet.solve.text
How far one character moves the pen, in em units. Its advance, plus the kerning between it and the character after it, summed in font units before dividing -- so a pair the font does not kern steps exactly as far as its advance. :type character: :sphinx_autodoc_typehints_type:`\:py\:class\:\`str\`` :param character: The character being set. :type following: :sphinx_autodoc_typehints_type:`\:py\:class\:\`str\` \| \:py\:obj\:\`None\`` :param following: The one after it in the same face, or `None` at the end of a run. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`float\`` :returns: The distance to the next character's origin.
.. py:method:: FontMetrics.measure(text, font_size) :module: scenet.solve.text
Width of a string set at a given size, kerned. :type text: :sphinx_autodoc_typehints_type:`\:py\:class\:\`str\`` :param text: The string to measure. Not wrapped; measured as one run. :type font_size: :sphinx_autodoc_typehints_type:`\:py\:class\:\`float\`` :param font_size: Type size in panel units. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`float\`` :returns: *Width in panel units* -- the sum of every character's `step`, which is exactly how far the outlines advance when they are drawn. .. admonition:: Example >>> from scenet.solve.text import load_metrics >>> metrics = load_metrics() >>> metrics.measure("mm", 100) > metrics.measure("ii", 100) True.. py:method:: FontMetrics.line_height(font_size) :module: scenet.solve.text
Baseline-to-baseline distance for a given type size. :type font_size: :sphinx_autodoc_typehints_type:`\:py\:class\:\`float\`` :param font_size: Type size in panel units. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`float\`` :returns: `font_size * LINE_HEIGHT_FACTOR`. A fixed multiple rather than the font's own ascent-plus-descent, because comics lettering is set to a chosen leading rather than to whatever the typeface suggests... py:method:: FontMetrics.glyph_outlines(text) :module: scenet.solve.text
Each character's outline as SVG path data, with its `step` in em units. The step is the advance plus the kerning to the next character, so the outlines advance by exactly what `measure` summed. Converting lettering to outlines rather than emitting `<text>` is what makes the output genuinely self-contained: no font to embed, no font to be missing, and the rendered shapes are by construction the ones that were measured. The cost is that the text is no longer selectable, which is why `--live-text` exists. :rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`list\`\\ \\\[\:py\:class\:\`tuple\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`float\`\]\]`
.. py:function:: load_metrics(path=None)
- module:
scenet.solve.text
Cached metrics. Parsing a 300 KB font per balloon would be absurd.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics``
.. py:class:: Typeface
- module:
scenet.solve.text
Bases: :py:class:
objectA lettering family: one font file per face.
A face left as
Noneis the shipped one, loaded only when something is set in it – a panel with no emphasis never opens the bold italic file... attribute:: regular
Dialogue, and
spokencaptions... attribute:: italic
Every other caption kind.
.. attribute:: bold_italic
Emphasis, in either.
.. attribute:: display
Sound effects. Bangers when not given, whatever the other faces are.
.. admonition:: Example
from scenet.ir import Face from scenet.solve.text import Typeface Typeface().face(Face.BOLD_ITALIC).path.name ‘SourceSansPro-BoldIt.ttf’
.. py:attribute:: Typeface.regular
- module:
scenet.solve.text
- type:
~scenet.solve.text.FontMetrics | None
.. py:attribute:: Typeface.italic
- module:
scenet.solve.text
- type:
~scenet.solve.text.FontMetrics | None
.. py:attribute:: Typeface.bold_italic
- module:
scenet.solve.text
- type:
~scenet.solve.text.FontMetrics | None
.. py:attribute:: Typeface.display
- module:
scenet.solve.text
- type:
~scenet.solve.text.FontMetrics | None
.. py:method:: Typeface.face(face)
- module:
scenet.solve.text
The metrics for one face of the family.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics``
.. py:method:: Typeface.measure(text, font_size)
- module:
scenet.solve.text
Width of styled text, each character measured in its own face.
Kerned within a face and never across a change of face: two faces are two fonts, and a pair adjustment belongs to one font’s pairs. Otherwise the same sum, in the same order, as :meth:
FontMetrics.measure <scenet.solve.text.FontMetrics.measure>, so text in one face measures to the last bit exactly as the plain string does.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
.. py:method:: Typeface.init(regular=None, italic=None, bold_italic=None, display=None)
- module:
scenet.solve.text
.. py:function:: wrap_styled(text, typeface, font_size, measure)
- module:
scenet.solve.text
Greedy word wrap of styled text at a given measure.
Greedy rather than Knuth-Plass: balloons hold a handful of words, where the optimal-fit algorithm’s advantage vanishes, and greedy is trivially deterministic.
A single word longer than the measure is left to overflow rather than being hyphenated or broken. Breaking a word mid-way in comic lettering looks like a mistake, and the balloon widening to fit is the correct outcome.
Each line is measured in the faces it is set in, so a stressed word is wider here exactly as it will be drawn wider – and can push its neighbour onto the next line.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\list`\ \[:py:class:`~scenet.solve.text.Styled`]`
.. py:function:: wrap_to_width(text, metrics, font_size, measure)
- module:
scenet.solve.text
Greedy word wrap of plain text at a given measure; see
wrap_styled.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\list`\ \[:py:class:`str`]`
.. py:function:: candidate_measures(words, metrics, font_size)
- module:
scenet.solve.text
Every line measure at which the wrapping can change.
A line is always some contiguous run of words, so the widths of all such runs are exactly the measures worth trying. Anything between two of them produces the same break points as the lower one.
The obvious shortcut – dividing total width by the desired line count – looks equivalent and is not. For “You forgot your umbrella!” it never proposes the measure that fits “You forgot your”, so the good two-line break is unreachable and the search settles for a ragged three-line block instead. Balloons hold a few dozen words at most, so enumerating runs costs nothing.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\list`\ \[:py:class:`float`]`
.. py:function:: layout_text(text, *, font_size, metrics=None, typeface=None, target_aspect=2.0)
- module:
scenet.solve.text
Wrap text into the best-shaped block for a balloon.
Scored on how close the block comes to the target aspect ratio, plus a penalty per line. The penalty is what stops a three-word phrase being split: purely on aspect, breaking “I know.” into two lines scores marginally better than leaving it alone, which is not something any letterer would do.
- type text:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str` | :py:class:`~scenet.solve.text.Styled``
- param text:
Plain text, set in the regular face, or styled text from
styled.- type font_size:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param font_size:
Type size in panel units.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :py:obj:`None``
- param metrics:
The regular face, in place of the family’s.
- type typeface:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.Typeface` | :py:obj:`None``
- param typeface:
The family to measure in. Defaults to the shipped one.
- type target_aspect:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param target_aspect:
The width-to-height ratio the block aims for.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.TextBlock``
- returns:
The best block – its lines as plain text, and its runs the faces they are set in.
.. py:function:: balloon_size(block, padding_factor=0.55)
- module:
scenet.solve.text
Outer dimensions of a balloon holding this text block.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`float`, :py:class:`float`]`
scenet.solve.sfx#
.. py:module:: scenet.solve.sfx
Sound effects: letters set as part of the picture, and placed like it.
A sound effect is lettering treated as art. It is set in the display face rather than the balloon face, on one line, and bent and turned the way letterers bend and turn them – an arc, a rotation – as transforms of the glyph outlines Scenet already draws, so no renderer and no installed font has a say. Then it is placed the way everything else is placed: by generating candidate positions and scoring them, never at a coordinate.
What it may not do is the hard rule every box obeys: cover a face, leave the frame, lie under an inset. And two effects never overlap. What it prefers is to sit near the actor it comes from, or in the zone it names, and off any figure but its source’s.
What it does to everything else is cost them. Effects are placed before any balloon or
caption – they are part of the picture, which lettering is placed over – and each one’s
footprint then joins the emanata as ground a balloon pays to cover and is never forbidden
to. Covering a sound effect deletes what the panel was saying, which is the argument for
emanata too (docs/explanation/design_decisions.md).
They move nobody. An effect is placed after staging and the camera, from the figures those produced, and reaches neither.
.. py:data:: INK
- module:
scenet.solve.sfx
- value:
‘#111111’
the stroke colour every balloon uses, and the paper the panel is printed on.
- type:
The two values an effect is drawn in
.. py:data:: SIZE_FACTORS
- module:
scenet.solve.sfx
- type:
dict[~scenet.ir.SfxSize, float]
- value:
{SfxSize.LARGE: 4.0, SfxSize.MEDIUM: 2.6, SfxSize.SMALL: 1.6}
How big each size is, as a multiple of the dialogue type size. Of the type, not of the figure, so an effect reads at a long shot as well as at a close-up.
.. py:class:: EffectShape
- module:
scenet.solve.sfx
Bases: :py:class:
objectAn effect laid out around its own centre, before it is placed.
.. attribute:: glyphs
Every letter, the origin at the effect’s centre.
.. attribute:: footprint
What the letters cover, outline included: a convex polygon.
.. attribute:: font_size
The type size, in panel units.
.. attribute:: stroke_width
The outline’s width, in panel units.
.. attribute:: metrics
The face it is set in.
.. py:attribute:: EffectShape.glyphs
- module:
scenet.solve.sfx
- type:
tuple[~scenet.solve.sfx.PlacedGlyph, …]
.. py:attribute:: EffectShape.footprint
- module:
scenet.solve.sfx
- type:
~shapely.geometry.polygon.Polygon
.. py:attribute:: EffectShape.font_size
- module:
scenet.solve.sfx
- type:
float
.. py:attribute:: EffectShape.stroke_width
- module:
scenet.solve.sfx
- type:
float
.. py:attribute:: EffectShape.metrics
- module:
scenet.solve.sfx
- type:
~scenet.solve.text.FontMetrics
.. py:method:: EffectShape.init(glyphs, footprint, font_size, stroke_width, metrics)
- module:
scenet.solve.sfx
.. py:class:: PlacedEffect
- module:
scenet.solve.sfx
Bases: :py:class:
objectOne effect after placement, before it is reduced to a Core document.
.. attribute:: id
s0,s1, … in script order... attribute:: order
Its number in the panel’s one reading order.
.. attribute:: text
The sound, as written.
.. attribute:: source
The actor it comes from, if any.
.. attribute:: font_size
The type size.
.. attribute:: glyphs
Every letter, in panel units.
.. attribute:: zone
The footprint, placed: what balloons paid to avoid.
.. attribute:: fill
What the letters are filled with, or
none... attribute:: stroke
What they are outlined in.
.. attribute:: stroke_width
The outline’s width.
.. attribute:: hollow
Whether it is an open effect, all outline.
.. py:attribute:: PlacedEffect.id
- module:
scenet.solve.sfx
- type:
str
.. py:attribute:: PlacedEffect.order
- module:
scenet.solve.sfx
- type:
int
.. py:attribute:: PlacedEffect.text
- module:
scenet.solve.sfx
- type:
str
.. py:attribute:: PlacedEffect.source
- module:
scenet.solve.sfx
- type:
str | None
.. py:attribute:: PlacedEffect.font_size
- module:
scenet.solve.sfx
- type:
float
.. py:attribute:: PlacedEffect.glyphs
- module:
scenet.solve.sfx
- type:
tuple[~scenet.solve.sfx.PlacedGlyph, …]
.. py:attribute:: PlacedEffect.zone
- module:
scenet.solve.sfx
- type:
~shapely.geometry.polygon.Polygon
.. py:attribute:: PlacedEffect.fill
- module:
scenet.solve.sfx
- type:
str
.. py:attribute:: PlacedEffect.stroke
- module:
scenet.solve.sfx
- type:
str
.. py:attribute:: PlacedEffect.stroke_width
- module:
scenet.solve.sfx
- type:
float
.. py:attribute:: PlacedEffect.hollow
- module:
scenet.solve.sfx
- type:
bool
.. py:method:: PlacedEffect.init(id, order, text, source, font_size, glyphs, zone, fill, stroke, stroke_width, hollow)
- module:
scenet.solve.sfx
.. py:class:: PlacedGlyph
- module:
scenet.solve.sfx
Bases: :py:class:
objectOne letter of an effect, where it is drawn.
.. attribute:: character
The letter.
.. attribute:: origin
Where its baseline starts, in panel units once the effect is placed.
.. attribute:: angle
Its rotation in degrees, clockwise, about
origin... py:attribute:: PlacedGlyph.character
- module:
scenet.solve.sfx
- type:
str
.. py:attribute:: PlacedGlyph.origin
- module:
scenet.solve.sfx
- type:
~scenet.geom.Point
.. py:attribute:: PlacedGlyph.angle
- module:
scenet.solve.sfx
- type:
float
.. py:method:: PlacedGlyph.init(character, origin, angle)
- module:
scenet.solve.sfx
.. py:function:: layout_effect(event, *, dialogue_size, typeface)
- module:
scenet.solve.sfx
Set an effect’s letters, bend and turn them, and find what they cover.
The letters are kerned and advanced exactly as any lettering is. An arc puts their baselines on a circle whose length is the line’s own, so the letters keep their spacing as it bends; each is turned to the tangent there. The whole is then centred on its own middle and turned by
rotate.- type event:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.SfxEvent``
- param event:
The effect.
- type dialogue_size:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param dialogue_size:
The panel’s dialogue type size, which the effect’s is a multiple of.
- type typeface:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.Typeface``
- param typeface:
The family whose display face the effect is set in.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.sfx.EffectShape``
- returns:
The effect, centred on the origin.
.. admonition:: Example
from scenet.ir import SfxEvent from scenet.solve.sfx import layout_effect from scenet.solve.text import Typeface shape = layout_effect(SfxEvent(text=”BLAM”), dialogue_size=30, typeface=Typeface()) [glyph.character for glyph in shape.glyphs] [‘B’, ‘L’, ‘A’, ‘M’]
.. py:function:: place_effects(events, *, actors, hulls, panel, dialogue_size, typeface, marks=(), blocked=(), inside=None)
- module:
scenet.solve.sfx
Place every sound effect, in script order, before any balloon is placed.
- type events:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`tuple`\ \[:py:class:`int`, :py:class:`~scenet.ir.SfxEvent`]]`
- param events:
Each effect with its index in the script, which is its reading order.
- type actors:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`~scenet.assets.kinematics.ResolvedPuppet`]`
- param actors:
Resolved figures, by actor id.
- type hulls:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`~shapely.geometry.polygon.Polygon`]`
- param hulls:
Their silhouettes, by actor id.
- type panel:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.geom.BBox``
- param panel:
The rectangle effects stay inside, margins applied.
- type dialogue_size:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- param dialogue_size:
The dialogue type size, which effect sizes are multiples of.
- type typeface:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.Typeface``
- param typeface:
The family whose display face effects are set in.
- type marks:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`~shapely.geometry.base.BaseGeometry`]`
- param marks:
Emanata, which effects prefer not to cover.
- type blocked:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`~scenet.geom.BBox`]`
- param blocked:
Areas drawn over the panel, such as insets.
- type inside:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~shapely.geometry.polygon.Polygon` | :py:obj:`None``
- param inside:
The shape every effect must lie within, for a panel that is not a rectangle.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`~scenet.solve.sfx.PlacedEffect`, :py:data:`…<Ellipsis>`]`
- returns:
The effects, placed.
- raises SfxPlacementError:
An effect had no legal position anywhere in the panel.
scenet.solve.balloons#
.. py:module:: scenet.solve.balloons
Placing everything in a panel that carries words: balloons, captions, and tails.
Placement is a scored search over candidate positions rather than a sweep of a cost grid. Balloons belong in a small number of sensible places relative to their speaker – around the head, or tucked into a corner – so generating those directly is both cheaper than scanning cells and produces more natural results. This is the approach used in the cartographic label-placement literature, which is the same problem.
The constraint that naive implementations miss is reading order. A box may never sit above-and-left of the one before it in the script, because that makes the panel read in the wrong order. That is a correctness bug in a comic, not a cosmetic one, so it is enforced as a hard filter rather than scored.
Captions go through this machinery rather than a parallel one. The placement principles the lettering references give for floating text – keep off the important figures, preserve the space of the art, keep the reading order flowing – are the ones already implemented here. What differs is where a caption wants to be: a balloon mildly dislikes hugging the panel edge, and a caption is looking for exactly that.
So the two are placed in one pass in script order, sharing the list of boxes already down. Placing every caption first would be simpler and wrong: a caption written after the dialogue would then impose reading order on balloons that precede it.
.. py:data:: SMALL_TYPE_FRACTION
- module:
scenet.solve.balloons
- value:
0.75
a step down a letterer would make by eye, as the caption size is one. The balloon keeps the padding the normal size would have, which is what makes small type read as muttered rather than as a smaller balloon.
- type:
Small lettering against the panel’s dialogue size
.. py:data:: CAPTION_INK
- module:
scenet.solve.balloons
- value:
‘#111111’
What lettering is drawn in, and its opposite.
CAPTION_INKis the emitter’s stroke colour, restated here because the choice between the two is made in the solver.
.. py:data:: LETTERING_FLOOR
- module:
scenet.solve.balloons
- value:
4.5
WCAG AA for body text. This is the contrast a reader actually gets, because the box is opaque and the text sits on the fill whatever is behind it.
letter_toneis what holds it, andtests/test_setting.pyis what proves every tone in the palette does.- type:
The floor a caption’s own lettering must clear against its fill
.. py:data:: SEPARATION_FLOOR
- module:
scenet.solve.balloons
- value:
3.0
WCAG AA for large text, which is the right comparison for a filled rectangle rather than for type.
Not every tone clears this on every rung, and none is required to. White on a noon sky is 1.16:1, which is the whole reason
toneexists. What the palette owes the author is an escape from every background the compiler can produce – at least one tone above this floor for every rung of every row – and that is what is tested.- type:
The floor at which a box separates from the plane behind it
.. py:class:: TailRoute
- module:
scenet.solve.balloons
Bases: :py:class:
objectThe pointer from balloon to mouth.
A straight tail is correct almost always.
controlis set only when the direct route was obstructed and the tail had to bend around something... py:attribute:: TailRoute.start
- module:
scenet.solve.balloons
- type:
~scenet.geom.Point
.. py:attribute:: TailRoute.end
- module:
scenet.solve.balloons
- type:
~scenet.geom.Point
.. py:attribute:: TailRoute.control
- module:
scenet.solve.balloons
- type:
~scenet.geom.Point | None
.. py:property:: TailRoute.is_curved
- module:
scenet.solve.balloons
- type:
bool
Whether this tail had to bend around a face.
Reported in :attr:
CompileResult.notes <scenet.pipeline.CompileResult.notes>, since a curved tail is a sign the panel is crowded enough to be worth a second look.
.. py:method:: TailRoute.init(start, end, control=None)
- module:
scenet.solve.balloons
.. py:class:: PlacedBalloon
- module:
scenet.solve.balloons
Bases: :py:class:
objectOne balloon after placement, before it is reduced to a Core document.
.. attribute:: id
Stable identifier,
b0,b1, … in script order... attribute:: speaker
Actor id of whoever is talking.
.. attribute:: order
Position in reading order, counting from zero.
.. attribute:: kind
Which sort of balloon to draw.
.. attribute:: box
Where it ended up.
.. attribute:: block
The text, already broken into lines and measured.
.. attribute:: tail
The route from balloon to mouth – or, for a speaker off panel, to the frame on their side.
.. attribute:: off_panel
The side of the frame an off-panel speaker is on, as resolved, or
Nonefor one who is drawn... py:attribute:: PlacedBalloon.id
- module:
scenet.solve.balloons
- type:
str
.. py:attribute:: PlacedBalloon.speaker
- module:
scenet.solve.balloons
- type:
str
.. py:attribute:: PlacedBalloon.order
- module:
scenet.solve.balloons
- type:
int
.. py:attribute:: PlacedBalloon.kind
- module:
scenet.solve.balloons
- type:
~scenet.ir.BalloonKind
.. py:attribute:: PlacedBalloon.box
- module:
scenet.solve.balloons
- type:
~scenet.geom.BBox
.. py:attribute:: PlacedBalloon.block
- module:
scenet.solve.balloons
- type:
~scenet.solve.text.TextBlock
.. py:attribute:: PlacedBalloon.tail
- module:
scenet.solve.balloons
- type:
~scenet.solve.balloons.TailRoute
.. py:attribute:: PlacedBalloon.off_panel
- module:
scenet.solve.balloons
- type:
~scenet.ir.Side | None
.. py:method:: PlacedBalloon.init(id, speaker, order, kind, box, block, tail, off_panel=None)
- module:
scenet.solve.balloons
.. py:class:: PlacedCaption
- module:
scenet.solve.balloons
Bases: :py:class:
objectOne caption after placement, before it is reduced to a Core document.
.. attribute:: id
Stable identifier,
c0,c1, … in the order the captions appear... attribute:: order
Position in the panel’s reading order, which captions share with balloons – so a caption between two lines of dialogue takes the number between theirs.
.. attribute:: kind
What the box is doing, which decides how it is set.
.. attribute:: box
Where it ended up.
.. attribute:: block
The text, already quoted where the kind calls for it, broken into lines and measured against the face it will be drawn in.
.. attribute:: fill
The value the box is filled with, resolved from the declared tone.
.. attribute:: ink
The value its lettering is drawn in, chosen against
fillso the text reads on the box it sits in... attribute:: speaker
Who is talking, for a
spokencaption. They are off panel, so this is not an actor id and resolves to nobody in the cast.There is no tail, which is the reason this is not a fifth
BalloonKind... py:attribute:: PlacedCaption.id
- module:
scenet.solve.balloons
- type:
str
.. py:attribute:: PlacedCaption.order
- module:
scenet.solve.balloons
- type:
int
.. py:attribute:: PlacedCaption.kind
- module:
scenet.solve.balloons
- type:
~scenet.ir.CaptionKind
.. py:attribute:: PlacedCaption.box
- module:
scenet.solve.balloons
- type:
~scenet.geom.BBox
.. py:attribute:: PlacedCaption.block
- module:
scenet.solve.balloons
- type:
~scenet.solve.text.TextBlock
.. py:attribute:: PlacedCaption.fill
- module:
scenet.solve.balloons
- type:
str
.. py:attribute:: PlacedCaption.ink
- module:
scenet.solve.balloons
- type:
str
.. py:attribute:: PlacedCaption.speaker
- module:
scenet.solve.balloons
- type:
str | None
.. py:method:: PlacedCaption.init(id, order, kind, box, block, fill=’#ffffff’, ink=’#111111’, speaker=None)
- module:
scenet.solve.balloons
.. py:class:: ScriptLayout
- module:
scenet.solve.balloons
Bases: :py:class:
objectEverything in a panel that carries words, placed.
Separate tuples rather than one merged sequence: they reduce to different Core types, and the thing that orders them –
order– is on each... py:attribute:: ScriptLayout.captions
- module:
scenet.solve.balloons
- type:
tuple[~scenet.solve.balloons.PlacedCaption, …]
.. py:attribute:: ScriptLayout.balloons
- module:
scenet.solve.balloons
- type:
tuple[~scenet.solve.balloons.PlacedBalloon, …]
.. py:attribute:: ScriptLayout.effects
- module:
scenet.solve.balloons
- type:
tuple[~scenet.solve.sfx.PlacedEffect, …]
.. py:method:: ScriptLayout.init(captions=(), balloons=(), effects=())
- module:
scenet.solve.balloons
.. py:function:: route_tail(balloon, mouth, obstacles, speaker_face=None)
- module:
scenet.solve.balloons
Route a tail from the balloon toward the speaker’s mouth.
Straight is right almost always, so it is tried first. Only when the direct line crosses another character’s face does the tail bend, and then via a single control point chosen from a handful of lateral offsets.
Grid pathfinding is deliberately not used here. A tail is a short tapered stroke, and A-star produces a jointed path that looks nothing like one drawn by hand.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.balloons.TailRoute``
.. py:function:: letter_tone(fill)
- module:
scenet.solve.balloons
What a caption filled with this value is lettered in.
Ink over a pale box, paper over a dark one, chosen by contrast rather than by a threshold on the tone – the same rule and the same reason as falling rain in
solve/backdrop.py, where a white streak is invisible against noon and a black one against midnight. Inkers flip the same way.Resolved here rather than in the emitter because which mark reads is a fact about the panel, not a rendering preference: the emitter must not be able to draw a box in a value the solver did not choose.
- type fill:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- param fill:
The
#rrggbbthe box is filled with.- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
The value the lettering is drawn in.
.. admonition:: Example
from scenet.solve.balloons import letter_tone letter_tone(“#ffffff”), letter_tone(“#090909”) (‘#111111’, ‘#ffffff’)
.. py:function:: caption_text(events, index)
- module:
scenet.solve.balloons
The text of a caption, with quotation marks where the kind calls for them.
Blambot’s rule for a run of one speaker’s spoken captions: an opening quote on each, a closing quote only on the last. Consecutive boxes are one continuous line of off-panel speech, and closing each of them would read as four separate interruptions.
Applied here, before measurement, and carried through Panel Core as part of the resolved lines. Adding the marks in the emitter would make the text wider than the box that was drawn for it.
- type events:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`~scenet.ir.SayEvent` | :py:class:`~scenet.ir.CaptionEvent` | :py:class:`~scenet.ir.SfxEvent` | :py:class:`~scenet.ir.SayEvent` | :py:class:`~scenet.ir.CaptionEvent` | :py:class:`~scenet.ir.SfxEvent`]`
- param events:
The whole script, because whether this caption closes depends on what follows it.
- type index:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- param index:
Which entry to render.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\str``
- returns:
The text to letter.
.. admonition:: Example
from scenet.ir import CaptionEvent, CaptionKind from scenet.solve.balloons import caption_text run = ( … CaptionEvent(text=”Get down!”, kind=CaptionKind.SPOKEN), … CaptionEvent(text=”All of you!”, kind=CaptionKind.SPOKEN), … ) caption_text(run, 0).endswith(”””) False caption_text(run, 1).endswith(”””) True
.. py:function:: place_script(events, actors, panel, *, metrics=None, italic_metrics=None, typeface=None, font_size=None, type_size=None, lettering_height=None, backdrop=None, emanata=None, exclusions=(), inside=None, bounds=None, outline=None)
- module:
scenet.solve.balloons
Place every sound effect, then every balloon and caption in script order.
Greedy rather than jointly optimised: each box is placed against those already down, which is exactly how reading order works – a box constrains its successor, never its predecessor. That makes the greedy pass the natural formulation rather than a compromise.
One pass over the whole script, not captions and then balloons. The two share the list of boxes already placed, so a caption written between two lines of dialogue is read between them.
- type events:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`~scenet.ir.SayEvent` | :py:class:`~scenet.ir.CaptionEvent` | :py:class:`~scenet.ir.SfxEvent` | :py:class:`~scenet.ir.SayEvent` | :py:class:`~scenet.ir.CaptionEvent` | :py:class:`~scenet.ir.SfxEvent`]`
- param events:
The panel’s script, in reading order.
- type actors:
- sphinx_autodoc_typehints_type:
\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.assets.kinematics.ResolvedPuppet`]`
- param actors:
Resolved puppets, keyed by actor id.
- type panel:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.geom.BBox``
- param panel:
The rectangle to compose within, margins already applied.
- type metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :py:obj:`None``
- param metrics:
Font to measure roman lettering against, in place of the family’s.
- type italic_metrics:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.FontMetrics` | :py:obj:`None``
- param italic_metrics:
Font to measure italic captions against, in place of the family’s.
- type typeface:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.text.Typeface` | :py:obj:`None``
- param typeface:
The lettering family, emphasis face included. Defaults to the shipped one;
metricsanditalic_metricsreplace single faces of it.- type font_size:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float` | :py:obj:`None``
- param font_size:
Override for every type size, dialogue and captions alike, in panel units. For tests that want one size throughout.
- type type_size:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float` | :py:obj:`None``
- param type_size:
The dialogue size the author set with
lettering.size, in panel units. Captions keep their proportion to it. Takes the place oflettering_height, which only matters when no size was set.- type lettering_height:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float` | :py:obj:`None``
- param lettering_height:
The height type sizes are a fraction of, in place of the frame’s own. A page passes one value to every panel on it, so a short panel and a tall one letter alike.
- type backdrop:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.backdrop.ResolvedBackdrop` | :py:obj:`None``
- param backdrop:
The resolved setting, if the panel has one. Its masses are a soft cost, never an exclusion: a balloon over a sky is the ordinary case.
- type emanata:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`~collections.abc.Sequence`\ \[:py:class:`~collections.abc.Sequence`\ \[:py:class:`~scenet.geom.Point`]]] | :py:obj:`None``
- param emanata:
Actor id to the zones of the marks drawn around them. Also a soft cost, and a heavier one than a body, but never an exclusion.
- type exclusions:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`~scenet.geom.BBox`]`
- param exclusions:
Areas that are drawn over, such as an inset: as hard as a face, since words under them could not be read. They take no part in reading order.
- type inside:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`tuple`\ \[:py:class:`float`, :py:class:`float`]] | :py:obj:`None``
- param inside:
The shape every box must lie within, when the panel is not a rectangle, margins already applied – as
panelhas them. A box must also lie withinpanel; candidates are still generated in it.- type bounds:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.geom.BBox` | :py:obj:`None``
- param bounds:
The panel’s own rectangle, margins not applied: the frame an off-panel speaker’s tail ends on. Defaults to
panel.- type outline:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Sequence`\ \[:py:class:`tuple`\ \[:py:class:`float`, :py:class:`float`]] | :py:obj:`None``
- param outline:
The panel’s own outline when it is not a rectangle, margins not applied, which that tail ends on instead.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.solve.balloons.ScriptLayout``
- returns:
Everything that carries words, placed.
- raises BalloonPlacementError:
Some box had no legal position anywhere in the panel.
- raises SfxPlacementError:
Some sound effect had no legal position anywhere in the panel.
scenet.solve.page#
.. py:module:: scenet.solve.page
Page layout: tiers of panels, or of columns of panels, into frames.
Plain arithmetic, with no constraint solver. Tiers are ordered top to bottom and panels
left to right within a tier, and each takes a share of what the margins and gutters leave,
in proportion to its weight – the same model as CSS Grid’s fr tracks with a gap. A tier
of columns is split the same way twice: across into columns, then down each column into its
panels, with the tier gutter between them. There is nothing to choose between, so nothing
for Cassowary to do: its value in this project is the priority system that settles
conflicting preferences (docs/explanation/prior_art.md), and a strict grid has none.
The order panels are written in is the order they are read in. In a tier of panels that is the Z-path. In a tier of columns it is down each column before across, which is what readers do when a panel spanning the tier blocks the way across (Cohn, Navigating Comics, 2013);
- class:
PageLayout <scenet.ir.PageLayout>refuses columns where nothing blocks it. An inset is where readers agree least, splitting about evenly between it and the panel it sits in, so it is read after its parent unless it says otherwise.
.. py:data:: LETTERING_TIERS
- module:
scenet.solve.page
- value:
3
Type on a page is set as if every panel were one tier of a page this many tiers tall. Three tiers of the default page letter at about 1.2% of the page’s height, which on a printed comic page is about eight points – the size lettering is usually set at. It is also exactly what a single panel letters at today when it is a third of a page tall, so nothing changes for a panel that was already the size it ends up on the page.
.. py:class:: Frame
- module:
scenet.solve.page
Bases: :py:class:
objectWhere one panel goes on its page.
.. attribute:: panel
The panel’s name.
.. attribute:: x
Left edge.
.. attribute:: y
Top edge.
.. attribute:: width
Frame width.
.. attribute:: height
Frame height.
.. attribute:: inset_of
For an inset, the panel it is set into;
Noneotherwise... attribute:: clearance
For an inset, the area it covers with its ring of white: the frame grown by a gutter on every side. It is painted white under the inset, and its parent’s lettering keeps clear of it.
Nonefor a panel that is no inset... attribute:: outline
For a panel in a slanted tier, its four corners, clockwise from the top left, in page units; the frame is their bounding box.
Nonefor a rectangle... py:attribute:: Frame.panel
- module:
scenet.solve.page
- type:
str
.. py:attribute:: Frame.x
- module:
scenet.solve.page
- type:
float
.. py:attribute:: Frame.y
- module:
scenet.solve.page
- type:
float
.. py:attribute:: Frame.width
- module:
scenet.solve.page
- type:
float
.. py:attribute:: Frame.height
- module:
scenet.solve.page
- type:
float
.. py:attribute:: Frame.inset_of
- module:
scenet.solve.page
- type:
str | None
.. py:attribute:: Frame.clearance
- module:
scenet.solve.page
- type:
~scenet.geom.BBox | None
.. py:attribute:: Frame.outline
- module:
scenet.solve.page
- type:
tuple[tuple[float, float], …] | None
.. py:method:: Frame.init(panel, x, y, width, height, inset_of=None, clearance=None, outline=None)
- module:
scenet.solve.page
.. py:function:: lettering_height(page_format)
- module:
scenet.solve.page
The height every panel on a page takes its type size from.
A panel letters at a fixed fraction of a height. Alone, that height is its own; on a page it is this one, the same for every panel, so a short panel and a tall one letter alike, as no letterer would do otherwise.
- type page_format:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.PageFormat``
- param page_format:
The page.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\float``
- returns:
A third of the height inside the margins (see
LETTERING_TIERS).
.. py:function:: resolve_frames(page_format, page, *, index=0)
- module:
scenet.solve.page
Lay out one page.
- type page_format:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.PageFormat``
- param page_format:
Size, margin and gutters.
- type page:
- sphinx_autodoc_typehints_type:
\:py\:class\:\~scenet.ir.PageSpec``
- param page:
The tiers, already validated to have room for what they hold.
- type index:
- sphinx_autodoc_typehints_type:
\:py\:class\:\int``
- param index:
The page’s position among the pages, from 0, to locate a mistake.
- rtype:
- sphinx_autodoc_typehints_type:
\:py\:class\:\tuple`\ \[:py:class:`~scenet.solve.page.Frame`, :py:data:`…<Ellipsis>`]`
- returns:
One frame per panel, in reading order – tier by tier, and within a tier left to right – or, for a tier of columns, column by column and top to bottom in each. An inset comes right after the panel it is set into, or right before it when it says
read: before.- raises RuleViolationError:
Rule
page-layout, for two insets in one panel that overlap. It is found here, where the frames are worked out, andscenet checkruns this too, so the finding is still located.
.. admonition:: Example
from scenet.ir import PageFormat, PageSpec page = PageSpec.model_validate( … {“tiers”: [{“panels”: [{“use”: “a”}, {“use”: “b”, “width”: 2}]}]} … ) [(f.panel, f.x, f.width) for f in resolve_frames(PageFormat(), page)] [(‘a’, 100.0, 586.67), (‘b’, 726.67, 1173.33)]