scenic.syntax.veneer

Python implementations of Scenic language constructs.

This module is automatically imported by all Scenic programs. In addition to defining the built-in functions, operators, specifiers, etc., it also stores global state such as the list of all created Scenic objects.

Summary of Module Members

Functions

`Ahead`	The `ahead of X by Y` polymorphic specifier.
`AngleFrom`	The `angle from <vector> to <vector>` operator.
`AngleTo`	The `angle to <vector>` operator (using the position of ego as the reference).
`ApparentHeading`	The `apparent heading of <oriented point> [from <vector>]` operator.
`ApparentlyFacing`	The `apparently facing <heading> [from <vector>]` specifier.
`At`	The `at <vector>` specifier.
`Back`	The `back of <object>` operator.
`BackLeft`	The `back left of <object>` operator.
`BackRight`	The `back right of <object>` operator.
`Behind`	The `behind X by Y` polymorphic specifier.
`Beyond`	The `beyond X by Y from Z` polymorphic specifier.
`CanSee`	The `X can see Y` polymorphic operator.
`DistanceFrom`	The `distance from X to Y` polymorphic operator.
`DistancePast`	The `distance past <vector> of <oriented point>` operator.
`Facing`	The `facing X` polymorphic specifier.
`FacingToward`	The `facing toward <vector>` specifier.
`FieldAt`	The `<VectorField> at <vector>` operator.
`Follow`	The `follow <field> from <vector> for <number>` operator.
`Following`	The `following F from X for D` specifier.
`Front`	The `front of <object>` operator.
`FrontLeft`	The `front left of <object>` operator.
`FrontRight`	The `front right of <object>` operator.
`In`	The `in/on <region>` specifier.
`Left`	The `left of <object>` operator.
`LeftSpec`	The `left of X by Y` polymorphic specifier.
`NotVisible`	The `not visible <region>` operator.
`NotVisibleFrom`	The `not visible from <Point>` specifier.
`NotVisibleSpec`	The `not visible` specifier (equivalent to `not visible from ego`).
`OffsetAlong`	The `X offset along H by Y` polymorphic operator.
`OffsetAlongSpec`	The `offset along X by Y` polymorphic specifier.
`OffsetBy`	The `offset by <vector>` specifier.
`RelativeHeading`	The `relative heading of <heading> [from <heading>]` operator.
`RelativePosition`	The `relative position of <vector> [from <vector>]` operator.
`RelativeTo`	The `X relative to Y` polymorphic operator.
`Right`	The `right of <object>` operator.
`RightSpec`	The `right of X by Y` polymorphic specifier.
`Visible`	The `visible <region>` operator.
`VisibleFrom`	The `visible from <Point>` specifier.
`VisibleSpec`	The `visible` specifier (equivalent to `visible from ego`).
`With`	The `with <property> <value>` specifier.
`activate`	Activate the veneer when beginning to compile a Scenic module.
`alwaysProvidesOrientation`	Whether a Region or distribution over Regions always provides an orientation.
`beginSimulation`
`callWithStarArgs`
`deactivate`	Deactivate the veneer after compiling a Scenic module.
`ego`	Function implementing loads and stores to the 'ego' pseudo-variable.
`endScenario`
`endSimulation`
`executeInBehavior`
`executeInGuard`
`executeInRequirement`
`executeInScenario`
`filter`
`finishScenarioSetup`
`globalParameters`
`in_initial_scenario`
`instantiateSimulator`
`isActive`	Are we in the middle of compiling a Scenic module?
`leftSpecHelper`
`localPath`	Convert a path relative to the calling Scenic file into an absolute path.
`makeRequirement`
`model`
`mutate`	Function implementing the mutate statement.
`override`
`param`	Function implementing the param statement.
`prepareScenario`
`record`
`record_final`
`record_initial`
`registerDynamicScenarioClass`
`registerExternalParameter`	Register a parameter whose value is given by an external sampler.
`registerObject`	Add a Scenic object to the global list of created objects.
`require`	Function implementing the require statement.
`require_always`	Function implementing the 'require always' statement.
`require_eventually`	Function implementing the 'require eventually' statement.
`resample`	The built-in resample function.
`simulation`	Get the currently-running `Simulation`.
`simulationInProgress`
`simulator`
`startScenario`
`str`
`terminate_after`
`terminate_simulation_when`	Function implementing the 'terminate simulation when' statement.
`terminate_when`	Function implementing the 'terminate when' statement.
`verbosePrint`	Built-in function printing a message only in verbose mode.
`workspace`	Function implementing loads and stores to the 'workspace' pseudo-variable.
`wrapStarredValue`

Classes

`Modifier`
`ParameterTableProxy`

Member Details

ego(obj=None)[source]

Function implementing loads and stores to the ‘ego’ pseudo-variable.

The translator calls this with no arguments for loads, and with the source value for stores.

workspace(workspace=None)[source]

Function implementing loads and stores to the ‘workspace’ pseudo-variable.

See ego.

require(reqID, req, line, name, prob=1)[source]: Function implementing the require statement.

resample(dist)[source]: The built-in resample function.

param(*quotedParams, **params)[source]: Function implementing the param statement.

mutate(*objects)[source]: Function implementing the mutate statement.

verbosePrint(*objects, level=1, indent=True, sep=' ', end='\n', file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, flush=False)[source]

Built-in function printing a message only in verbose mode.

Scenic’s verbosity may be set using the -v command-line option. The simplest way to use this function is with code like verbosePrint('hello world!') or verbosePrint('details here', level=3); the other keyword arguments are probably only useful when replacing more complex uses of the Python print function.

Parameters

objects – Object(s) to print (str will be called to make them strings).
level (int) – Minimum verbosity level at which to print. Default is 1.
indent (bool) – Whether to indent the message to align with messages generated by Scenic (default true).
sep – As in print.
end – As in print.
file – As in print.
flush – As in print.

localPath(relpath)[source]

Convert a path relative to the calling Scenic file into an absolute path.

For example, localPath('resource.dat') evaluates to the absolute path of a file called resource.dat located in the same directory as the Scenic file where this expression appears.

simulation()[source]

Get the currently-running Simulation.

May only be called from code that runs at simulation time, e.g. inside dynamic behaviors and compose blocks of scenarios.

require_always(reqID, req, line, name)[source]: Function implementing the ‘require always’ statement.

require_eventually(reqID, req, line, name)[source]: Function implementing the ‘require eventually’ statement.

terminate_when(reqID, req, line, name)[source]: Function implementing the ‘terminate when’ statement.

terminate_simulation_when(reqID, req, line, name)[source]: Function implementing the ‘terminate simulation when’ statement.

Visible(region)[source]: The visible <region> operator.

NotVisible(region)[source]: The not visible <region> operator.

Front(X): The front of <object> operator.

Back(X): The back of <object> operator.

Left(X): The left of <object> operator.

Right(X): The right of <object> operator.

FrontLeft(X): The front left of <object> operator.

FrontRight(X): The front right of <object> operator.

BackLeft(X): The back left of <object> operator.

BackRight(X): The back right of <object> operator.

RelativeHeading(X, Y=None)[source]

The relative heading of <heading> [from <heading>] operator.

If the from <heading> is omitted, the heading of ego is used.

ApparentHeading(X, Y=None)[source]

The apparent heading of <oriented point> [from <vector>] operator.

If the from <vector> is omitted, the position of ego is used.

RelativePosition(X, Y=None)[source]

The relative position of <vector> [from <vector>] operator.

If the from <vector> is omitted, the position of ego is used.

DistanceFrom(X, Y=None)[source]

The distance from X to Y polymorphic operator.

Allowed forms:

distance from <vector> [to <vector>]
distance from <region> [to <vector>]
distance from <vector> to <region>

If the to <vector> is omitted, the position of ego is used.

DistancePast(X, Y=None)[source]

The distance past <vector> of <oriented point> operator.

If the of {oriented point} is omitted, the ego object is used.

AngleTo(X)[source]: The angle to <vector> operator (using the position of ego as the reference).

AngleFrom(X, Y)[source]: The angle from <vector> to <vector> operator.

Follow(F, X, D)[source]: The follow <field> from <vector> for <number> operator.

FieldAt(X, Y)[source]: The <VectorField> at <vector> operator.

RelativeTo(X, Y)[source]

The X relative to Y polymorphic operator.

Allowed forms:

<value> relative to <value> # with at least one a field, the other a field or heading
<vector> relative to <oriented point> # and vice versa
<vector> relative to <vector>
<heading> relative to <heading>

OffsetAlong(X, H, Y)[source]

The X offset along H by Y polymorphic operator.

Allowed forms:

<vector> offset along <heading> by <vector>
<vector> offset along <field> by <vector>

CanSee(X, Y)[source]

The X can see Y polymorphic operator.

Allowed forms:

<point> can see <object>
<point> can see <vector>

class Vector(x, y)[source]

Bases: Samplable, Sequence

A 2D vector, whose coordinates can be distributions.

rotatedBy(angle)[source]

Return a vector equal to this one rotated counterclockwise by the given angle.

Return type: Vector

angleWith(other)[source]

Compute the signed angle between self and other.

The angle is positive if other is counterclockwise of self (considering the smallest possible rotation to align them).

Return type: float

class VectorField(name, value, minSteps=4, defaultStepSize=5)[source]

A vector field, providing a heading at every point.

Parameters

name (str) – name for debugging.
value – function computing the heading at the given Vector.
minSteps (int) – Minimum number of steps for followFrom; default 4.
defaultStepSize (float) – Default step size for followFrom; default 5. This is an upper bound: more steps will be taken as needed to ensure that no single step is longer than this value, but if the distance to travel is small then the steps may be smaller.

followFrom(pos, dist, steps=None, stepSize=None)[source]

Follow the field from a point for a given distance.

Uses the forward Euler approximation, covering the given distance with equal-size steps. The number of steps can be given manually, or computed automatically from a desired step size.

Parameters

pos (Vector) – point to start from.
dist (float) – distance to travel.
steps (int) – number of steps to take, or None to compute the number of steps based on the distance (default None).
stepSize (float) – length used to compute how many steps to take, or None to use the field’s default step size.

static forUnionOf(regions, tolerance=0)[source]

Creates a PiecewiseVectorField from the union of the given regions.

If none of the regions have an orientation, returns None instead.

class PolygonalVectorField(name, cells, headingFunction=None, defaultHeading=None)[source]

Bases: VectorField

A piecewise-constant vector field defined over polygonal cells.

Parameters

name (str) – name for debugging.
cells – a sequence of cells, with each cell being a pair consisting of a Shapely geometry and a heading. If the heading is None, we call the given headingFunction for points in the cell instead.
headingFunction – function computing the heading for points in cells without specified headings, if any (default None).
defaultHeading – heading for points not contained in any cell (default None, meaning reject such points).

class Region(name, *dependencies, orientation=None)[source]

Bases: Samplable

Abstract class for regions.

intersect(other)[source]

Get a Region representing the intersection of this one with another.

If both regions have a preferred orientation, the one of self is inherited by the intersection.

Return type: Region

intersects(other)[source]

Check if this Region intersects another.

Return type: bool

difference(other)[source]

Get a Region representing the difference of this one and another.

Return type: Region

union(other)[source]

Get a Region representing the union of this one with another.

Not supported by all region types.

Return type: Region

static uniformPointIn(region)[source]: Get a uniform Distribution over points in a Region.

uniformPointInner()[source]: Do the actual random sampling. Implemented by subclasses.

containsPoint(point)[source]

Check if the Region contains a point. Implemented by subclasses.

Return type: bool

containsObject(obj)[source]

Check if the Region contains an Object.

The default implementation assumes the Region is convex; subclasses must override the method if this is not the case.

Return type: bool

distanceTo(point)[source]

Distance to this region from a given point.

Not supported by all region types.

Return type: float

getAABB()[source]: Axis-aligned bounding box for this Region. Implemented by some subclasses.

orient(vec)[source]: Orient the given vector along the region’s orientation, if any.

class PointSetRegion(name, points, kdTree=None, orientation=None, tolerance=1e-06)[source]

Bases: Region

Region consisting of a set of discrete points.

No Object can be contained in a PointSetRegion, since the latter is discrete. (This may not be true for subclasses, e.g. GridRegion.)

Parameters

name (str) – name for debugging
points (arraylike) – set of points comprising the region
kdTree (scipy.spatial.KDTree, optional) – k-D tree for the points (one will be computed if none is provided)
orientation (VectorField; optional) – preferred orientation for the region
tolerance (float; optional) – distance tolerance for checking whether a point lies in the region

class RectangularRegion(position, heading, width, length, name=None)[source]

Bases: Region

A rectangular region with a possibly-random position, heading, and size.

Parameters

position (Vector) – center of the rectangle.
heading (float) – the heading of the length axis of the rectangle.
width (float) – width of the rectangle.
length (float) – length of the rectangle.
name (str; optional) – name for debugging.

class CircularRegion(center, radius, resolution=32, name=None)[source]

Bases: Region

A circular region with a possibly-random center and radius.

Parameters

center (Vector) – center of the disc.
radius (float) – radius of the disc.
resolution (int; optional) – number of vertices to use when approximating this region as a polygon.
name (str; optional) – name for debugging.

class SectorRegion(center, radius, heading, angle, resolution=32, name=None)[source]

Bases: Region

A sector of a CircularRegion.

This region consists of a sector of a disc, i.e. the part of a disc subtended by a given arc.

Parameters

center (Vector) – center of the corresponding disc.
radius (float) – radius of the disc.
heading (float) – heading of the centerline of the sector.
angle (float) – angle subtended by the sector.
resolution (int; optional) – number of vertices to use when approximating this region as a polygon.
name (str; optional) – name for debugging.

class PolygonalRegion(points=None, polygon=None, orientation=None, name=None)[source]

Bases: Region

Region given by one or more polygons (possibly with holes).

The region may be specified by giving either a sequence of points defining the boundary of the polygon, or a collection of shapely polygons (a Polygon or MultiPolygon).

Parameters

points – sequence of points making up the boundary of the polygon (or None if using the polygon argument instead).
polygon – shapely polygon or collection of polygons (or None if using the points argument instead).
orientation (VectorField; optional) – preferred orientation to use.
name (str; optional) – name for debugging.

property boundary: PolylineRegion: Get the boundary of this region as a PolylineRegion.

class PolylineRegion(points=None, polyline=None, orientation=True, name=None)[source]

Bases: Region

Region given by one or more polylines (chain of line segments).

The region may be specified by giving either a sequence of points or shapely polylines (a LineString or MultiLineString).

Parameters

points – sequence of points making up the polyline (or None if using the polyline argument instead).
polyline – shapely polyline or collection of polylines (or None if using the points argument instead).
orientation (optional) – preferred orientation to use, or True to use an orientation aligned with the direction of the polyline (the default).
name (str; optional) – name for debugging.

property start

Get an OrientedPoint at the start of the polyline.

The OP’s heading will be aligned with the orientation of the region, if there is one (the default orientation pointing along the polyline).

property end

Get an OrientedPoint at the end of the polyline.

The OP’s heading will be aligned with the orientation of the region, if there is one (the default orientation pointing along the polyline).

signedDistanceTo(point)[source]

Compute the signed distance of the PolylineRegion to a point.

The distance is positive if the point is left of the nearest segment, and negative otherwise.

Return type: float

pointAlongBy(distance, normalized=False)[source]

Find the point a given distance along the polyline from its start.

If normalized is true, then distance should be between 0 and 1, and is interpreted as a fraction of the length of the polyline. So for example pointAlongBy(0.5, normalized=True) returns the polyline’s midpoint.

Return type: Vector

class Workspace(region=<AllRegion everywhere>)[source]

Bases: Region

A workspace describing the fixed world of a scenario.

Parameters: region (Region) – The region defining the extent of the workspace (default everywhere).

show(plt)[source]: Render a schematic of the workspace for debugging

zoomAround(plt, objects, expansion=1)[source]: Zoom the schematic around the specified objects

scenicToSchematicCoords(coords)[source]: Convert Scenic coordinates to those used for schematic rendering.

class Mutator[source]

An object controlling how the mutate statement affects an Object.

A Mutator can be assigned to the mutator property of an Object to control the effect of the mutate statement. When mutation is enabled for such an object using that statement, the mutator’s appliedTo method is called to compute a mutated version. The appliedTo method can also decide whether to apply mutators inherited from superclasses.

appliedTo(obj)[source]

Return a mutated copy of the given object. Implemented by subclasses.

The mutator may inspect the mutationScale attribute of the given object to scale its effect according to the scale given in mutate O by S.

Returns: A pair consisting of the mutated copy of the object (which is most easily created using _copyWith) together with a Boolean indicating whether the mutator inherited from the superclass (if any) should also be applied.

class Range(*args, **kwargs)[source]

Bases: Distribution

Uniform distribution over a range

class DiscreteRange(*args, **kwargs)[source]

Bases: Distribution

Distribution over a range of integers.

class Options(*args, **kwargs)[source]

Bases: MultiplexerDistribution

Distribution over a finite list of options.

Specified by a dict giving probabilities; otherwise uniform over a given iterable.

Uniform(*opts)[source]

Uniform distribution over a finite list of options.

Implemented as an instance of Options when the set of options is known statically, and an instance of UniformDistribution otherwise.

Discrete: alias of Options

class Normal(*args, **kwargs)[source]

Bases: Distribution

Normal distribution

class TruncatedNormal(*args, **kwargs)[source]

Bases: Normal

Truncated normal distribution.

class VerifaiParameter(*args, **kwargs)[source]

Bases: ExternalParameter

An external parameter sampled using one of VerifAI’s samplers.

static withPrior(dist, buckets=None)[source]

Creates a VerifaiParameter using the given distribution as a prior.

Since the VerifAI cross-entropy sampler currently only supports piecewise-constant distributions, if the prior is not of that form it may be approximated. For most built-in distributions, the approximation is exact: for a particular distribution, check its bucket method.

class VerifaiRange(*args, **kwargs)[source]

Bases: VerifaiParameter

A Range (real interval) sampled by VerifAI.

_defaultValueType: alias of float

class VerifaiDiscreteRange(*args, **kwargs)[source]

Bases: VerifaiParameter

A DiscreteRange (integer interval) sampled by VerifAI.

_defaultValueType: alias of float

class VerifaiOptions(*args, **kwargs)[source]

Bases: Options

An Options (discrete set) sampled by VerifAI.

class Point(<specifiers>)[source]

Bases: Constructible

The Scenic base class Point.

The default mutator for Point adds Gaussian noise to position with a standard deviation given by the positionStdDev property.

Properties

position (Vector; dynamic) – Position of the point. Default value is the origin.
visibleDistance (float) – Distance for can see operator. Default value 50.
width (float) – Default value zero (only provided for compatibility with operators that expect an Object).
length (float) – Default value zero.
mutationScale (float) – Overall scale of mutations, as set by the mutate statement. Default value zero (mutations disabled).
positionStdDev (float) – Standard deviation of Gaussian noise to add to this object’s position when mutation is enabled with scale 1. Default value 1.

property visibleRegion

The visible region of this object.

The visible region of a Point is a disc centered at its position with radius visibleDistance.

class OrientedPoint(<specifiers>)[source]

Bases: Point

The Scenic class OrientedPoint.

The default mutator for OrientedPoint adds Gaussian noise to heading with a standard deviation given by the headingStdDev property, then applies the mutator for Point.

Properties

heading (float; dynamic) – Heading of the OrientedPoint. Default value 0 (North).
viewAngle (float) – View cone angle for can see operator. Default value 2π.
headingStdDev (float) – Standard deviation of Gaussian noise to add to this object’s heading when mutation is enabled with scale 1. Default value 5°.

property visibleRegion

The visible region of this object.

The visible region of an OrientedPoint is a sector of the disc centered at its position with radius visibleDistance, oriented along heading and subtending an angle of viewAngle.

distancePast(vec)[source]: Distance past a given point, assuming we’ve been moving in a straight line.

class Object(<specifiers>)[source]

Bases: OrientedPoint

The Scenic class Object.

This is the default base class for Scenic classes.

Properties

width (float) – Width of the object, i.e. extent along its X axis. Default value 1.
length (float) – Length of the object, i.e. extent along its Y axis. Default value 1.
allowCollisions (bool) – Whether the object is allowed to intersect other objects. Default value False.
requireVisible (bool) – Whether the object is required to be visible from the ego object. Default value True.
regionContainedIn (Region or None) – A Region the object is required to be contained in. If None, the object need only be contained in the scenario’s workspace.
cameraOffset (Vector) – Position of the camera for the can see operator, relative to the object’s position. Default (0, 0).
speed (float; dynamic) – Speed in dynamic simulations. Default value 0.
velocity (Vector; dynamic) – Velocity in dynamic simulations. Default value is the velocity determined by self.speed and self.heading.
angularSpeed (float; dynamic) – Angular speed in dynamic simulations. Default value 0.
behavior – Behavior for dynamic agents, if any (see Dynamic Scenarios). Default value None.

startDynamicSimulation()[source]

Hook called at the beginning of each dynamic simulation.

Does nothing by default; provided for objects to do simulator-specific initialization as needed.

property visibleRegion

The visible region of this object.

The visible region of an Object is a circular sector as for OrientedPoint, except that the base of the sector may be offset from position by the cameraOffset property (to allow modeling cameras which are not located at the center of the object).

With(prop, val)[source]

The with <property> <value> specifier.

Specifies the given property, with no dependencies.

At(pos)[source]

The at <vector> specifier.