Data Types Reference¶

This page describes the primitive data types built into Scenic. In addition to these types, Scenic provides a class hierarchy for points, oriented points, and objects: see the Objects and Classes Reference.

Boolean¶

Booleans represent truth values, and can be `True` or `False`.

Note

These are equivalent to the Python `bool` type.

Scalar¶

Scalars represent distances, angles, etc. as floating-point numbers, which can be sampled from various distributions.

Note

These are equivalent to the Python `float` type; however, any context which accepts a scalar will also allow an `int` or a NumPy numeric type such as `numpy.single` (to be precise, any instance of `numbers.Real` is legal).

Vector¶

Vectors represent positions and offsets in space. They are constructed from coordinates with the syntax `X @ Y` (inspired by Smalltalk); using a length-2 list or tuple (`[X, Y]` or `(X, Y)`) is also allowed. By convention, coordinates are in meters, although the semantics of Scenic does not depend on this. More significantly, the vector syntax is specialized for 2-dimensional space. The 2D assumption dramatically simplifies much of Scenic’s syntax (particularly that dealing with orientations, as we will see below), while still being adequate for a variety of applications. Some world models, such as that for the Driving Domain, define an `elevation` property which defines a 3D location in combination with Scenic’s 2D `position` property. A future extension of Scenic will natively support 3D space.

For convenience, instances of Point can be used in any context where a vector is expected: so for example if `P` is a Point, then `P offset by (1, 2)` is equivalent to `P.position offset by (1, 2)`.

Headings represent orientations in space. Conveniently, in 2D these can be expressed using a single angle (rather than Euler angles or a quaternion). Scenic represents headings in radians, measured anticlockwise from North, so that a heading of 0 is due North and a heading of π/2 is due West. We use the convention that the heading of a local coordinate system is the heading of its Y-axis, so that, for example, the vector `-2 @ 3` means 2 meters left and 3 ahead.

For convenience, instances of OrientedPoint can be used in any context where a heading is expected: so for example if `OP` is an OrientedPoint, then `relative heading of OP` is equivalent to `relative heading of OP.heading`. Since OrientedPoint is a subclass of Point, expressions involving two oriented points like `OP1 relative to OP2` can be ambiguous: the polymorphic operator `relative to` accepts both vectors and headings, and either version could be meant here. Scenic rejects such expressions as being ambiguous: more explicit syntax like `OP1.position relative to OP2` must be used instead.

Vector Field¶

Vector fields associate an orientation (i.e. a heading) to each point in space. For example, a vector field could represent the shortest paths to a destination, or the nominal traffic direction on a road (e.g. `scenic.domains.driving.model.roadDirection`).

Region¶

Regions represent sets of points in space. Scenic provides a variety of ways to define regions: rectangles, circular sectors, line segments, polygons, occupancy grids, and explicit lists of points, among others.

Regions can have an associated vector field giving points in the region preferred orientations. For example, a region representing a lane of traffic could have a preferred orientation aligned with the lane, so that we can easily talk about distances along the lane, even if it curves. Another possible use of preferred orientations is to give the surface of an object normal vectors, so that other objects placed on the surface face outward by default.

The main operations available for use with all regions are the `(vector | Object) in region` operator to test containment within a region, the `visible region` operator to get the part of a region which is visible from the `ego`, and the `(in | on) region` specifier to choose a position uniformly at random inside a region.

If you need to perform more complex operations on regions, or are writing a world model and need to define your own regions, you will have to work with the `Region` class (which regions are instances of) and its subclasses for particular types of regions. These are summarized below: if you are working on Scenic’s internals, see the `scenic.core.regions` module for full details.

Abstract Regions¶

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

Abstract class for regions.

intersect(other)[source]

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

Return type

Region

intersects(other)[source]

Check if this Region intersects another.

Return type

bool

union(other)[source]

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

Not supported by all region types.

Return type

Region

Simple Shapes¶

Unlike the more complex regions, these simple geometric shapes are allowed to depend on random values: for example, the visible region of an Object is a `SectorRegion` based at the object’s `position`, which might not be fixed.

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

Parameters
• center (Vector) – center of the disc.

• resolution (int; optional) – number of vertices to use when approximating this region as a polygon.

• name (str; optional) – name for debugging.

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.

• 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 RectangularRegion(position, heading, width, length, name=None)[source]

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.

Polylines and Polygons¶

These subclasses represent fixed 1D and 2D regions defined by line segments and polygons.

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

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

__getitem__(i)[source]

Get the ith point along this polyline.

If the region consists of multiple polylines, this order is linear along each polyline but arbitrary across different polylines.

Return type

Vector

__len__()[source]

Get the number of vertices of the polyline.

Return type

int

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

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 (Vector Field; optional) – preferred orientation to use.

• name (str; optional) – name for debugging.

property boundary: PolylineRegion

Get the boundary of this region as a `PolylineRegion`.

Point Sets and Grids¶

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

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 (iterable) – 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 (Vector Field; optional) – preferred orientation for the region

• tolerance (float; optional) – distance tolerance for checking whether a point lies in the region

class GridRegion(name, grid, Ax, Ay, Bx, By, orientation=None)[source]

Bases: `PointSetRegion`

A Region given by an obstacle grid.

A point is considered to be in a `GridRegion` if the nearest grid point is not an obstacle.

Parameters
• name (str) – name for debugging

• grid – 2D list, tuple, or NumPy array of 0s and 1s, where 1 indicates an obstacle and 0 indicates free space

• Ax (float) – spacing between grid points along X axis

• Ay (float) – spacing between grid points along Y axis

• Bx (float) – X coordinate of leftmost grid column

• By (float) – Y coordinate of lowest grid row

• orientation (Vector Field; optional) – orientation of region