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).

Heading

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)

Abstract class for regions.

intersect(other)

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)

Check if this Region intersects another.

Return type

bool

union(other)

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.

class CircularRegion(center, radius, resolution=32, name=None)

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)

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

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)

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)

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)

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)

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__()

Get the number of vertices of the polyline.

Return type

int

class PolygonalRegion(points=None, polygon=None, orientation=None, name=None)

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)

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 (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)

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