Source code for scenet.places

"""The place library: named settings, and what each expands into.

The thing an author wants to write is *where the scene is*, not a list of shapes. So
the headline surface is a named place:

.. code-block:: yaml

    setting:
      place: docks

**The rule that keeps that honest**: a preset expands into a mass list the author could
have written themselves, and is never a second opaque format. A library for
convenience, not a parallel language. The expansion happens in the frontend, so by the
time anything downstream sees a backdrop there is exactly one representation of it --
the same treatment `alice left_of bob` gets on its way to a
:class:`Relation <scenet.ir.Relation>`.

**Free prose is deliberately not offered.** `setting: "a rainy street corner at
midnight"` needs language understanding, and `frontends/script_front.py` already
refuses to interpret prose on the grounds that guessing produces panels that are
confidently wrong. A named place is the honest middle: it reads like a description and
resolves deterministically.

Within a place, masses are listed **back to front**. Draw order comes from the plane, so
the listing order only decides ties within one plane -- but reading the list in the
order it will be painted is what makes a preset reviewable.
"""

from collections.abc import Sequence
from enum import StrEnum

from scenet.ir import Mass, MassKind, Plane, Spans

__all__ = ["PLACES", "Place", "place_of"]


[docs] class Place(StrEnum): """A named setting, expanded into masses by the frontend. Ten to start with, chosen to span the distinctions that change how a backdrop is built rather than to be a catalogue: exterior and interior, built and natural, open and enclosed. `alley` is the one with a foreground mass, which is what makes it read as a place you are standing *in* rather than looking at. Example: >>> from scenet import PLACES, Place >>> [mass.kind.value for mass in PLACES[Place.SHORE]] ['sky', 'water', 'ground'] See Also: :data:`PLACES <scenet.places.PLACES>`, what each place expands into. :class:`SettingSpec <scenet.ir.SettingSpec>`, whose `place` takes one. """ ALLEY = "alley" DESERT = "desert" DOCKS = "docks" FIELD = "field" FOREST = "forest" MOUNTAIN = "mountain" OFFICE = "office" ROOM = "room" SHORE = "shore" STREET = "street"
def _mass(kind: MassKind, plane: Plane, spans: Spans = Spans.FULL) -> Mass: """One mass, written positionally so a preset reads as a table.""" return Mass(kind=kind, plane=plane, spans=spans) #: What each place is made of, as the masses a `setting: {place: ...}` expands into. #: #: Every entry here is a plain mass list, and a test proves it: whatever a preset produces, #: an author could have typed. The expansion happens in the frontend, so nothing downstream #: ever sees a place. #: #: Example: #: >>> from scenet import PLACES, Place #: >>> [mass.kind.value for mass in PLACES[Place.DOCKS]] #: ['sky', 'building', 'water', 'structural', 'ground'] #: #: See Also: #: :class:`Place <scenet.places.Place>`, the names it is keyed by. #: :class:`Mass <scenet.ir.Mass>`, what each entry lists. PLACES: dict[Place, tuple[Mass, ...]] = { Place.ALLEY: ( # The walls make the slot of sky, rather than the sky being authored as a strip: # that is how an alley actually works, and a partial sky leaves bare paper in the # corners where nothing was asked to be. They stand at `near` so they tower. # The foreground wall is what makes this a place you are standing *in*. _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.BUILDING, Plane.NEAR, Spans.LEFT), _mass(MassKind.BUILDING, Plane.NEAR, Spans.RIGHT), _mass(MassKind.GROUND, Plane.NEAR), _mass(MassKind.BUILDING, Plane.FOREGROUND, Spans.LEFT), ), Place.DESERT: ( _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.SOLID, Plane.FAR, Spans.RIGHT), _mass(MassKind.GROUND, Plane.MID), _mass(MassKind.GROUND, Plane.NEAR), ), Place.DOCKS: ( _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.BUILDING, Plane.FAR, Spans.LEFT), _mass(MassKind.WATER, Plane.MID), _mass(MassKind.STRUCTURAL, Plane.MID, Spans.RIGHT), _mass(MassKind.GROUND, Plane.NEAR), ), Place.FIELD: ( # Open country: a treeline far off, and the ground doing the rest in bands. Put # the planting nearer and this becomes `forest`, which is the distinction the # two presets exist to make. _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.PLANT, Plane.FAR), _mass(MassKind.GROUND, Plane.MID), _mass(MassKind.GROUND, Plane.NEAR), ), Place.FOREST: ( # Canopy behind, and two stands of it close enough to crowd the frame. _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.PLANT, Plane.FAR), _mass(MassKind.PLANT, Plane.NEAR, Spans.LEFT), _mass(MassKind.PLANT, Plane.NEAR, Spans.RIGHT), _mass(MassKind.GROUND, Plane.NEAR), ), Place.MOUNTAIN: ( _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.SOLID, Plane.FAR), _mass(MassKind.SOLID, Plane.MID, Spans.LEFT), _mass(MassKind.PLANT, Plane.MID, Spans.RIGHT), _mass(MassKind.GROUND, Plane.NEAR), ), Place.OFFICE: ( _mass(MassKind.WALL, Plane.FAR), _mass(MassKind.WINDOW, Plane.FAR, Spans.CENTRE), # The ceiling sits at a nearer plane than the back wall because it *is* nearer, # and a shadowed band across the top is what tells an interior from an exterior # at a glance. _mass(MassKind.CEILING, Plane.MID), _mass(MassKind.FLOOR, Plane.NEAR), _mass(MassKind.FURNITURE, Plane.NEAR), ), Place.ROOM: ( _mass(MassKind.WALL, Plane.FAR), _mass(MassKind.WINDOW, Plane.FAR, Spans.RIGHT), _mass(MassKind.CEILING, Plane.MID), _mass(MassKind.FLOOR, Plane.NEAR), _mass(MassKind.FURNITURE, Plane.NEAR, Spans.LEFT), ), Place.SHORE: ( _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.WATER, Plane.MID), _mass(MassKind.GROUND, Plane.NEAR), ), Place.STREET: ( _mass(MassKind.SKY, Plane.FAR), _mass(MassKind.BUILDING, Plane.FAR), _mass(MassKind.BUILDING, Plane.MID, Spans.LEFT), _mass(MassKind.BUILDING, Plane.MID, Spans.RIGHT), _mass(MassKind.GROUND, Plane.NEAR), ), }
[docs] def place_of(masses: Sequence[Mass]) -> Place | None: """The named place a list of masses is, or None for a list no place expands into. A place reaches the IR as its masses and nothing else, so this is how a place is named again afterwards: by its masses, whether `place:` wrote them or an author wrote the same list out by hand. The description reads it, and Panel Core records it. Example: >>> from scenet import PLACES, Place >>> from scenet.places import place_of >>> place_of(PLACES[Place.DOCKS]) <Place.DOCKS: 'docks'> >>> place_of(()) is None True """ written = tuple(masses) for place in Place: if PLACES[place] == written: return place return None