an.semantic.views#

View spaces: what a camera move moves through, defined once for every engine (an#257).

A camera move (push_in, pan_left, an orbit) is not a crop, a zoom or a parameter tween: it is a path through a view space, which each engine lowers its own way —

a crop engine (burns, a still or a video) moves a rectangle over fixed pixels, so pushing in loses resolution;
a render engine (the stage engine of an/cutan, vector art) re-renders the scene into the rectangle, so pushing in loses nothing;
a parameter engine (previz) moves a vector of view parameters — an orbit camera in 3D, a chart’s axis domain.

So the vocabulary defines each move once, over an abstract space, and an engine affords the space it can lower (space.framing2d is an engine capability, an.capabilities.subjects). The core declares two spaces; a genre or a package declares more (an n-dimensional one) with view_space(), and registers moves over them into the same camera_move table — so push_in means one thing everywhere, and burns’ moves and previz’s camera formulas join it instead of redefining it.

>>> FRAMING_2D.entry.id, FRAMING_2D.capability.name, FRAMING_2D.entry.params["properties"]["zoom"]["scale"]
('view.framing2d', 'space.framing2d', 'log')

Module Attributes

`FRAMING_2D`	where the frame is, how close, how rolled.
`ORBIT_3D`	a camera on a sphere around a target (previz's turntable).

Functions

view_space(name, fields, *, description[, ...])

Declare a view space: an entry view.<name> and an engine capability space.<name>.

Classes

`ViewField`(name, unit[, scale, rest, description])	One axis of a view space: its name, unit, how it interpolates, its rest value.
`ViewSpace`(entry, capability)	A declared view space: its vocabulary entry and the engine capability to lower it.

an.semantic.views.FRAMING_2D: ViewSpace = ViewSpace(entry=Entry(id='view.framing2d', kind='view_space', version='1', name='framing2d', title='', description='a 2D framing of a flat picture: position, zoom (log), roll (angle)', usage='axes: x (frame widths, linear), y (frame heights, linear), zoom (ratio, log), rotation (rad, angle)', params={'type': 'object', 'properties': {'x': {'type': 'number', 'unit': 'frame widths', 'scale': 'linear', 'default': 0.0, 'description': '+x moves the view right'}, 'y': {'type': 'number', 'unit': 'frame heights', 'scale': 'linear', 'default': 0.0, 'description': '+y moves the view down'}, 'zoom': {'type': 'number', 'unit': 'ratio', 'scale': 'log', 'default': 1.0, 'description': 'on-screen magnification; > 1 is closer'}, 'rotation': {'type': 'number', 'unit': 'rad', 'scale': 'angle', 'default': 0.0, 'description': "the view's roll"}}}, examples=(), requires=(), levels=frozenset({'a'}), aspects=()), capability=Capability(name='space.framing2d', description='the engine lowers moves through the framing2d view space: a 2D framing of a flat picture: position, zoom (log), roll (angle)', remedy='render with an engine that lowers the framing2d view space', subject='engine', command=None, version='1'))#

where the frame is, how close, how rolled. Every engine that shows a flat picture lowers it — by cropping pixels (burns) or by re-rendering into the frame (the stage engine).

Type:: The 2D framing space

an.semantic.views.ORBIT_3D: ViewSpace = ViewSpace(entry=Entry(id='view.orbit3d', kind='view_space', version='1', name='orbit3d', title='', description='an orbit camera around a 3D target: azimuth and elevation (angles), distance (log)', usage='axes: azimuth (rad, angle), elevation (rad, angle), distance (scene units, log), target_x (scene units, linear), target_y (scene units, linear), target_z (scene units, linear)', params={'type': 'object', 'properties': {'azimuth': {'type': 'number', 'unit': 'rad', 'scale': 'angle', 'default': 0.0, 'description': 'around the target'}, 'elevation': {'type': 'number', 'unit': 'rad', 'scale': 'angle', 'default': 0.0, 'description': "above the target's horizon"}, 'distance': {'type': 'number', 'unit': 'scene units', 'scale': 'log', 'default': 1.0, 'description': 'from the target'}, 'target_x': {'type': 'number', 'unit': 'scene units', 'scale': 'linear', 'default': 0.0}, 'target_y': {'type': 'number', 'unit': 'scene units', 'scale': 'linear', 'default': 0.0}, 'target_z': {'type': 'number', 'unit': 'scene units', 'scale': 'linear', 'default': 0.0}}}, examples=(), requires=(), levels=frozenset({'a'}), aspects=()), capability=Capability(name='space.orbit3d', description='the engine lowers moves through the orbit3d view space: an orbit camera around a 3D target: azimuth and elevation (angles), distance (log)', remedy='render with an engine that lowers the orbit3d view space', subject='engine', command=None, version='1'))#

a camera on a sphere around a target (previz’s turntable).

Type:: The 3D orbit space

class an.semantic.views.ViewField(name, unit, scale='linear', rest=0.0, description='')[source]#

Bases: object

One axis of a view space: its name, unit, how it interpolates, its rest value.

class an.semantic.views.ViewSpace(entry, capability)[source]#

Bases: object

A declared view space: its vocabulary entry and the engine capability to lower it.

an.semantic.views.view_space(name, fields, *, description, version='1')[source]#

Declare a view space: an entry view.<name> and an engine capability space.<name>.

Return type:: ViewSpace