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
The |
|
The |
|
The |
|
The |
|
|
|
The |
|
The |
|
The |
|
The |
|
The |
|
|
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
|
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
|
|
The |
|
The |
|
The |
|
The |
|
|
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
|
|
|
|
|
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
The |
|
|
|
The |
|
The |
|
The |
|
The |
|
The |
|
|
Activate the veneer when beginning to compile a Scenic module. |
|
Whether a Region or distribution over Regions always provides an orientation. |
|
|
|
|
|
Deactivate the veneer after compiling a Scenic module. |
|
|
Function implementing loads and stores to the 'ego' pseudo-variable. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Are we in the middle of compiling a Scenic module? |
|
|
Convert a path relative to the calling Scenic file into an absolute path. |
|
|
|
|
|
Function implementing the mutate statement. |
|
|
|
|
|
Function implementing the param statement. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Register a parameter whose value is given by an external sampler. |
|
Add a Scenic instance to the global list of created objects. |
|
Add a Scenic object to the global list of created objects. |
Function implementing the require statement. |
|
|
Function implementing the 'require always' statement. |
|
Function implementing the 'require eventually' statement. |
|
|
The built-in resample function. |
|
|
|
Get the currently-running |
|
|
|
|
|
|
|
|
|
|
|
Function implementing the 'terminate simulation when' statement. |
|
Function implementing the 'terminate when' statement. |
|
Built-in function printing a message only in verbose mode. |
|
Function implementing loads and stores to the 'workspace' pseudo-variable. |
|
|
Classes
|
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
.
- verbosePrint(*objects, level=1, indent=True, sep=' ', end='\n', file=sys.stdout, 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 likeverbosePrint('hello world!')
orverbosePrint('details here', level=3)
; the other keyword arguments are probably only useful when replacing more complex uses of the Pythonprint
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 calledresource.dat
located in the same directory as the Scenic file where this expression appears. Note that the path is returned as apathlib.Path
object.
- 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.
- 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.
- 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.
- Top(X)
The
top of <object>
operator.
- Bottom(X)
The
bottom of <object>
operator.
- TopFrontLeft(X)
The
top front left of <object>
operator.
- TopFrontRight(X)
The
top front right of <object>
operator.
- TopBackLeft(X)
The
top back left of <object>
operator.
- TopBackRight(X)
The
top back right of <object>
operator.
- BottomFrontLeft(X)
The
bottom front left of <object>
operator.
- BottomFrontRight(X)
The
bottom front right of <object>
operator.
- BottomBackLeft(X)
The
bottom back left of <object>
operator.
- BottomBackRight(X)
The
bottom 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.
- 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> <orientation> relative to <orientation>
- Return type:
- 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 <vector> <point> can see <point>
- class Vector(x, y, z=0)[source]
-
A 3D vector, whose coordinates can be distributions.
- class Orientation(rotation)[source]
An orientation in 3D space.
- classmethod fromQuaternion(quaternion)[source]
Create an
Orientation
from a quaternion (of the form (x,y,z,w))- Return type:
- classmethod fromEuler(yaw, pitch, roll)[source]
Create an
Orientation
from yaw, pitch, and roll angles (in radians).- Return type:
- class VectorField(name, value, minSteps=4, defaultStepSize=5)[source]
A vector field, providing an orientation 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:
- 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 Shape(dimensions, scale)[source]
Bases:
ABC
An abstract base class for Scenic shapes.
Represents a physical shape in Scenic. Does not encode position or orientation, which are handled by the
Region
class. Does contain dimension information, which is used as a default value by anyObject
with this shape and can be overwritten.If dimensions and scale are both specified the dimensions are first set by dimensions, and then scaled by scale.
- Parameters:
dimensions – The raw (before scaling) dimensions of the shape.
scale – Scales all the dimensions of the shape by a multiplicative factor.
- property containsCenter
Whether or not this object contains its central point
- class MeshShape(mesh, dimensions=None, scale=1, initial_rotation=None)[source]
Bases:
Shape
A Shape subclass defined by a
trimesh.base.Trimesh
object.The mesh passed must be a
trimesh.base.Trimesh
object that represents a well defined volume (i.e. theis_volume
property must be true), meaning the mesh must be watertight, have consistent winding and have outward facing normals.- Parameters:
mesh – A mesh object.
dimensions – The raw (before scaling) dimensions of the shape. If dimensions and scale are both specified the dimensions are first set by dimensions, and then scaled by scale.
scale – Scales all the dimensions of the shape by a multiplicative factor. If dimensions and scale are both specified the dimensions are first set by dimensions, and then scaled by scale.
initial_rotation – A 3-tuple containing the yaw, pitch, and roll respectively to apply when loading the mesh. Note the initial_rotation must be fixed.
- classmethod fromFile(path, filetype=None, compressed=None, binary=False, unify=True, **kwargs)[source]
Load a mesh shape from a file, attempting to infer filetype and compression.
For example: “foo.obj.bz2” is assumed to be a compressed .obj file. “foo.obj” is assumed to be an uncompressed .obj file. “foo” is an unknown filetype, so unless a filetype is provided an exception will be raised.
- Parameters:
path (str) – Path to the file to import.
filetype (str) – Filetype of file to be imported. This will be inferred if not provided. The filetype must be one compatible with
trimesh.load
.compressed (bool) – Whether or not this file is compressed (with bz2). This will be inferred if not provided.
binary (bool) – Whether or not to open the file as a binary file.
unify (bool) – Whether or not to attempt to unify this mesh.
kwargs – Additional arguments to the MeshShape initializer.
- class BoxShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None)[source]
Bases:
MeshShape
A box shape with all dimensions 1 by default.
- class CylinderShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None, sections=24)[source]
Bases:
MeshShape
A cylinder shape with all dimensions 1 by default.
- class ConeShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None)[source]
Bases:
MeshShape
A cone shape with all dimensions 1 by default.
- class SpheroidShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None)[source]
Bases:
MeshShape
A spheroid shape with all dimensions 1 by default.
- class MeshVolumeRegion(*args, **kwargs)[source]
Bases:
MeshRegion
A region representing the volume of a mesh.
The mesh passed must be a
trimesh.base.Trimesh
object that represents a well defined volume (i.e. theis_volume
property must be true), meaning the mesh must be watertight, have consistent winding and have outward facing normals.The mesh is first placed so the origin is at the center of the bounding box (unless
centerMesh
isFalse
). The mesh is scaled todimensions
, translated so the center of the bounding box of the mesh is atpositon
, and then rotated torotation
.Meshes are centered by default (since
centerMesh
is true by default). If you disable this operation, do note that scaling and rotation transformations may not behave as expected, since they are performed around the origin.- Parameters:
mesh – The base mesh for this region.
name – An optional name to help with debugging.
dimensions – An optional 3-tuple, with the values representing width, length, height respectively. The mesh will be scaled such that the bounding box for the mesh has these dimensions.
position – An optional position, which determines where the center of the region will be.
rotation – An optional Orientation object which determines the rotation of the object in space.
orientation – An optional vector field describing the preferred orientation at every point in the region.
tolerance – Tolerance for internal computations.
centerMesh – Whether or not to center the mesh after copying and before transformations.
onDirection – The direction to use if an object being placed on this region doesn’t specify one.
engine – Which engine to use for mesh operations. Either “blender” or “scad”.
- intersects(other, triedReversed=False)[source]
Check if this region intersects another.
This function handles intersect calculations for
MeshVolumeRegion
with: *MeshVolumeRegion
*MeshSurfaceRegion
*PolygonalFootprintRegion
- intersect(other, triedReversed=False)[source]
Get a
Region
representing the intersection of this region with another.This function handles intersection computation for
MeshVolumeRegion
with: *MeshVolumeRegion
*PolygonalFootprintRegion
*PolygonalRegion
*PathRegion
*PolylineRegion
- union(other, triedReversed=False)[source]
Get a
Region
representing the union of this region with another.- This function handles union computation for
MeshVolumeRegion
with:
- This function handles union computation for
- difference(other, debug=False)[source]
Get a
Region
representing the difference of this region with another.This function handles union computation for
MeshVolumeRegion
with: *MeshVolumeRegion
*PolygonalFootprintRegion
- class MeshSurfaceRegion(*args, **kwargs)[source]
Bases:
MeshRegion
A region representing the surface of a mesh.
The mesh is first placed so the origin is at the center of the bounding box (unless
centerMesh
isFalse
). The mesh is scaled todimensions
, translated so the center of the bounding box of the mesh is atpositon
, and then rotated torotation
.Meshes are centered by default (since
centerMesh
is true by default). If you disable this operation, do note that scaling and rotation transformations may not behave as expected, since they are performed around the origin.If an orientation is not passed to this mesh, a default orientation is provided which provides an orientation that aligns an object’s z axis with the normal vector of the face containing that point, and has a yaw aligned with a yaw of 0 in the global coordinate system.
- Parameters:
mesh – The base mesh for this region.
name – An optional name to help with debugging.
dimensions – An optional 3-tuple, with the values representing width, length, height respectively. The mesh will be scaled such that the bounding box for the mesh has these dimensions.
position – An optional position, which determines where the center of the region will be.
rotation – An optional Orientation object which determines the rotation of the object in space.
orientation – An optional vector field describing the preferred orientation at every point in the region.
tolerance – Tolerance for internal computations.
centerMesh – Whether or not to center the mesh after copying and before transformations.
onDirection – The direction to use if an object being placed on this region doesn’t specify one.
- intersects(other, triedReversed=False)[source]
Check if this region’s surface intersects another.
This function handles intersection computation for
MeshSurfaceRegion
with: *MeshSurfaceRegion
*PolygonalFootprintRegion
- getFlatOrientation(pos)[source]
Get a flat orientation at a point in the region.
Given a point on the surface of the mesh, returns an orientation that aligns an instance’s z axis with the normal vector of the face containing that point. Since there are infinitely many such orientations, the orientation returned has yaw aligned with a global yaw of 0.
If
pos
is not withinself.tolerance
of the surface of the mesh, aRejectionException
is raised.
- class BoxRegion(*args, **kwargs)[source]
Bases:
MeshVolumeRegion
Region in the shape of a rectangular cuboid, i.e. a box.
By default the unit box centered at the origin and aligned with the axes is used.
Parameters are the same as
MeshVolumeRegion
, with the exception of themesh
parameter which is excluded.
- class SpheroidRegion(*args, **kwargs)[source]
Bases:
MeshVolumeRegion
Region in the shape of a spheroid.
By default the unit sphere centered at the origin and aligned with the axes is used.
Parameters are the same as
MeshVolumeRegion
, with the exception of themesh
parameter which is excluded.
- class PathRegion(points=None, polylines=None, tolerance=1e-08, name=None)[source]
Bases:
Region
A region composed of multiple polylines in 3D space.
One of points or polylines should be provided.
- Parameters:
points – A list of points defining a single polyline.
polylines – A list of list of points, defining multiple polylines.
tolerance – Tolerance used internally.
- class Region(name, *dependencies, orientation=None)[source]
-
An abstract base class for Scenic Regions
- abstract containsPoint(point)[source]
Check if the
Region
contains a point. Implemented by subclasses.- Return type:
- abstract containsRegionInner(reg, tolerance)[source]
Check if the
Region
contains aRegion
- Return type:
- abstract projectVector(point, onDirection)[source]
Returns point projected onto this region along onDirection.
- intersect(other, triedReversed=False)[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:
- union(other, triedReversed=False)[source]
Get a
Region
representing the union of this one with another.Not supported by all region types.
- Return type:
- difference(other)[source]
Get a
Region
representing the difference of this one and another.Not supported by all region types.
- Return type:
- static uniformPointIn(region)[source]
Get a uniform
Distribution
over points in aRegion
.
- 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 aPointSetRegion
, 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 regiontolerance (float; optional) – distance tolerance for checking whether a point lies in the region
- class RectangularRegion(position, heading, width, length, name=None)[source]
Bases:
PolygonalRegion
A rectangular region with a possibly-random position, heading, and size.
- class CircularRegion(center, radius, resolution=32, name=None)[source]
Bases:
PolygonalRegion
A circular region with a possibly-random center and radius.
- class SectorRegion(center, radius, heading, angle, resolution=32, name=None)[source]
Bases:
PolygonalRegion
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, z=0, orientation=None, name=None, additionalDeps=[])[source]
Bases:
Region
Region given by one or more polygons (possibly with holes) at a fixed z coordinate.
The region may be specified by giving either a sequence of points defining the boundary of the polygon, or a collection of
shapely
polygons (aPolygon
orMultiPolygon
).- 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 (orNone
if using the points argument instead).z – The z coordinate the polygon is located at.
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 (aLineString
orMultiLineString
).- Parameters:
points – sequence of points making up the polyline (or
None
if using the polyline argument instead).polyline –
shapely
polyline or collection of polylines (orNone
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 orientation 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 orientation 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:
- 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:
- 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
).
- class Mutator[source]
An object controlling how the
mutate
statement affects anObject
.A
Mutator
can be assigned to themutator
property of anObject
to control the effect of themutate
statement. When mutation is enabled for such an object using that statement, the mutator’sappliedTo
method is called to compute a mutated version. TheappliedTo
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 inmutate 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(low, high)[source]
Bases:
Distribution
Uniform distribution over a range
- class DiscreteRange(low, high, weights=None, emptyMessage='empty DiscreteRange')[source]
Bases:
Distribution
Distribution over a range of integers.
- class Options(opts)[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 ofUniformDistribution
otherwise.
- class Normal(mean, stddev)[source]
Bases:
Distribution
Normal distribution
- class TruncatedNormal(mean, stddev, low, high)[source]
Bases:
Normal
Truncated normal distribution.
- class VerifaiParameter(domain)[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(low, high, buckets=None, weights=None)[source]
Bases:
VerifaiParameter
A
Range
(real interval) sampled by VerifAI.
- class VerifaiDiscreteRange(low, high, weights=None)[source]
Bases:
VerifaiParameter
A
DiscreteRange
(integer interval) sampled by VerifAI.
- class Point <specifiers>[source]
Bases:
Constructible
The Scenic base class
Point
.The default mutator for
Point
adds Gaussian noise toposition
with a standard deviation given by thepositionStdDev
property.- Properties:
position (
Vector
; dynamic) – Position of the point. Default value is the origin (0,0,0).width (float) – Default value 0 (only provided for compatibility with operators that expect an
Object
).length (float) – Default value 0.
height (float) – Default value 0.
baseOffset (
Vector
) – Only provided for compatibility with the on (region | Object | vector) specifier. Default value is (0,0,0).contactTolerance (float) – Only provided for compatibility with the specifiers that expect an
Object
. Default value 0.onDirection (
Vector
) – The direction used to determine where to place thisPoint
on a region, when using the modifyingon
specifier. See theon region
page for more details. Default value is None, indicating the direction will be inferred from the region this object is being placed on.visibleDistance (float) – Distance used to determine the visible range of this object. Default value 50.
viewRayDensity (float) – By default determines the number of rays used during visibility checks. This value is the density of rays per degree of visible range in one dimension. The total number of rays sent will be this value squared per square degree of this object’s view angles. This value determines the default value for
viewRayCount
, so ifviewRayCount
is overwritten this value is ignored. Default value 5.viewRayCount (None | tuple[float, float]) – The total number of horizontal and vertical view angles to be sent, or None if this value should be computed automatically. Default value
None
.viewRayDistanceScaling (bool) – Whether or not the number of rays should scale with the distance to the object. Ignored if
viewRayCount
is passed. Default valueFalse
.mutationScale (float) – Overall scale of mutations, as set by the
mutate
statement. Default value 0 (mutations disabled).positionStdDev (tuple[float, float, float]) – Standard deviation of Gaussian noise for each dimension (x,y,z) to be added to this object’s
position
when mutation is enabled with scale 1. Default value (1,1,0), mutating only the x,y values of the point.
- property visibleRegion
The visible region of this object.
The visible region of a
Point
is a sphere centered at itsposition
with radiusvisibleDistance
.
- class OrientedPoint <specifiers>[source]
Bases:
Point
The Scenic class
OrientedPoint
.The default mutator for
OrientedPoint
adds Gaussian noise toyaw
while leavingpitch
androll
unchanged, using the three standard deviations (for yaw/pitch/roll respectively) given by theorientationStdDev
property. It then also applies the mutator forPoint
.The default mutator for
OrientedPoint
adds Gaussian noise toyaw
,pitch
androll
according toorientationStdDev
. By default the standard deviations forpitch
androll
are zero so that, by default, onlyyaw
is mutated.- Properties:
yaw (float; dynamic) – Yaw of the
OrientedPoint
in radians in the local coordinate system provided byparentOrientation
. Default value 0.pitch (float; dynamic) – Pitch of the
OrientedPoint
in radians in the local coordinate system provided byparentOrientation
. Default value 0.roll (float; dynamic) – Roll of the
OrientedPoint
in radians in the local coordinate system provided byparentOrientation
. Default value 0.parentOrientation (
Orientation
) – The local coordinate system that theOrientedPoint
’syaw
,pitch
, androll
are interpreted in. Default value is the global coordinate system, where an object is flat in the XY plane, facing North.orientation (
Orientation
; dynamic; final) – The orientation of theOrientedPoint
relative to the global coordinate system. Derived from theyaw
,pitch
,roll
, andparentOrientation
of thisOrientedPoint
and non-overridable.heading (float; dynamic; final) – Yaw value of this
OrientedPoint
in the global coordinate system. Derived fromorientation
and non-overridable.viewAngles (tuple[float,float]) – Horizontal and vertical view angles of this
OrientedPoint
in radians. Horizontal view angle can be up to 2π and vertical view angle can be up to π. Values greater than these will be truncated. Default value is (2π, π)orientationStdDev (tuple[float,float,float]) – Standard deviation of Gaussian noise to add to this object’s Euler angles (yaw, pitch, roll) when mutation is enabled with scale 1. Default value (5°, 0, 0), mutating only the
yaw
of thisOrientedPoint
.
- property visibleRegion
The visible region of this object.
The visible region of an
OrientedPoint
restricts that ofPoint
(a sphere with radiusvisibleDistance
) based on the value ofviewAngles
. In general, it is a capped rectangular pyramid subtending an angle ofviewAngles[0]
horizontally andviewAngles[1]
vertically, as long as those angles are less than π/2; larger angles yield various kinds of wrap-around regions. SeeViewRegion
for details.
- canSee(other, occludingObjects=(), debug=False)[source]
Whether or not this
OrientedPoint
can seeother
.- Parameters:
other – A
Point
,OrientedPoint
, orObject
to check for visibility.occludingObjects – A list of objects that can occlude visibility.
- Return type:
- 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 of 1 inherited from the object’s
shape
.length (float) – Length of the object, i.e. extent along its Y axis. Default value of 1 inherited from the object’s
shape
.height (float) – Height of the object, i.e. extent along its Z axis. Default value of 1 inherited from the object’s
shape
.shape (
Shape
) – The shape of the object, which must be an instance ofShape
. The default shape is a box, with default unit dimensions.allowCollisions (bool) – Whether the object is allowed to intersect other objects. Default value
False
.regionContainedIn (
Region
orNone
) – ARegion
the object is required to be contained in. IfNone
, the object need only be contained in the scenario’s workspace.baseOffset (
Vector
) – An offset from theposition
of the Object to the base of the object, used by the on (region | Object | vector) specifier. Default value is(0, 0, -self.height/2)
, placing the base of the Object at the bottom center of the Object’s bounding box.contactTolerance (float) – The maximum distance this object can be away from a surface to be considered on the surface. Objects are placed at half this distance away from a point when the on (region | Object | vector) specifier or a directional specifier like (left | right) of Object [by scalar] is used. Default value 1e-4.
sideComponentThresholds (
DimensionLimits
) – Used to determine the various sides of an object (when using the default implementation). The three interior 2-tuples represent the maximum and minimum bounds for each dimension’s (x,y,z) surface. SeedefaultSideSurface
for details. Default value((-0.5, 0.5), (-0.5, 0.5), (-0.5, 0.5))
.cameraOffset (
Vector
) – Position of the camera for thecan see
operator, relative to the object’sposition
. Default(0, 0, 0)
.requireVisible (bool) – Whether the object is required to be visible from the
ego
object. Default valueFalse
.occluding (bool) – Whether or not this object can occlude other objects. Default value
True
.showVisibleRegion (bool) – Whether or not to display the visible region in the Scenic internal visualizer.
color (tuple[float, float, float, float] or tuple[float, float, float] or
None
) – An optional color (with optional alpha) property that is used by the internal visualizer, or possibly simulators. All values should be between 0 and 1. Default valueNone
velocity (
Vector
; dynamic) – Velocity in dynamic simulations. Default value is the velocity determined byspeed
andorientation
.speed (float; dynamic) – Speed in dynamic simulations. Default value 0.
angularVelocity (
Vector
; dynamic)angularSpeed (float; dynamic) – Angular speed in dynamic simulations. Default value 0.
behavior – Behavior for dynamic agents, if any (see Dynamic Scenarios). Default value
None
.lastActions – Tuple of actions taken by this agent in the last time step (or
None
if the object is not an agent or this is the first time step).
- startDynamicSimulation()[source]
Hook called when the object is created in a dynamic simulation.
Does nothing by default; provided for objects to do simulator-specific initialization as needed.
Changed in version 3.0: This method is called on objects created in the middle of dynamic simulations, not only objects present in the initial scene.
- distanceTo(point)[source]
The minimal distance from the space this object occupies to a given point
- property visibleRegion
The visible region of this object.
The visible region of an
Object
is the same as that of anOrientedPoint
(seeOrientedPoint.visibleRegion
) except that it is offset by the value ofcameraOffset
(which is the zero vector by default).
- canSee(other, occludingObjects=(), debug=False)[source]
Whether or not this
Object
can seeother
.- Parameters:
other – A
Point
,OrientedPoint
, orObject
to check for visibility.occludingObjects – A list of objects that can occlude visibility.
- Return type:
- property corners
A tuple containing the corners of this object’s bounding box
- property occupiedSpace
A region representing the space this object occupies
- property _isConvex
Whether this object’s shape is convex
- property boundingBox
A region representing this object’s bounding box
- property inradius
A lower bound on the inradius of this object
- property surface
A region containing the entire surface of this object
- property onSurface
The surface used by the
on
specifier.This region is used to sample position when another object is placed
on
this object. By default the top surface of this object (topSurface
), but can be overwritten by subclasses.
- property topSurface
A region containing the top surface of this object
For how this surface is computed, see
defaultSideSurface
.
- property rightSurface
A region containing the right surface of this object
For how this surface is computed, see
defaultSideSurface
.
- property leftSurface
A region containing the left surface of this object
For how this surface is computed, see
defaultSideSurface
.
- property frontSurface
A region containing the front surface of this object
For how this surface is computed, see
defaultSideSurface
.
- property backSurface
A region containing the back surface of this object
For how this surface is computed, see
defaultSideSurface
.
- property bottomSurface
A region containing the bottom surface of this object
For how this surface is computed, see
defaultSideSurface
.
- property _isPlanarBox
Whether this object is a box aligned with the XY plane.
- With(prop, val)[source]
The
with <property> <value>
specifier.Specifies the given property, with no dependencies.
- In(region)[source]
The
in <region>
specifier.Specifies
position
, and optionally,parentOrientation
if the given region has a preferred orientation, with no dependencies.
- ContainedIn(region)[source]
The
contained in <region>
specifier.Specifies
position
,regionContainedIn
, and optionally,parentOrientation
if the given region has a preferred orientation, with no dependencies.
- On(thing)[source]
The
on X
specifier.Specifies
position
, and optionally,parentOrientation
if the given region has a preferred orientation. Depends ononDirection
,baseOffset
, andcontactTolerance
.Note that while
on
can be used withRegion
,Object
andVector
, it cannot be used with a distribution containing anything other thanRegion
.May be used to modify an already-specified
position
property.- Allowed forms:
on <region> on <object> on <vector>
- Beyond(pos, offset, fromPt=None)[source]
The
beyond X by Y from Z
polymorphic specifier.Specifies
position
, and optionallyparentOrientation
, with no dependencies.Allowed forms:
beyond <vector> by <number> [from <vector>] beyond <vector> by <vector> [from <vector>]
If the
from <vector>
is omitted, the position of ego is used.
- VisibleFrom(base)[source]
The
visible from <point>
specifier.Specifies
_observingEntity
andposition
, with no dependencies.
- NotVisibleFrom(base)[source]
The
not visible from <point>
specifier.Specifies
_nonObservingEntity
andposition
, depending onregionContainedIn
.See
VisibleFrom
.
- VisibleSpec()[source]
The
visible
specifier (equivalent tovisible from ego
).Specifies
_observingEntity
andposition
, with no dependencies.
- NotVisibleSpec()[source]
The
not visible
specifier (equivalent tonot visible from ego
).Specifies
_nonObservingEntity
andposition
, depending onregionContainedIn
.
- OffsetBy(offset)[source]
The
offset by <vector>
specifier.Specifies
position
, and optionallyparentOrientation
, with no dependencies.
- OffsetAlongSpec(direction, offset)[source]
The
offset along X by Y
polymorphic specifier.Specifies
position
, and optionallyparentOrientation
, with no dependencies.Allowed forms:
offset along <heading> by <vector> offset along <field> by <vector>
- Facing(heading)[source]
The
facing X
polymorphic specifier.Specifies
yaw
,pitch
, androll
, depending onparentOrientation
, and depending on the form:facing <number> # no further dependencies; facing <field> # depends on 'position'
- ApparentlyFacing(heading, fromPt=None)[source]
The
apparently facing <heading> [from <vector>]
specifier.Specifies
yaw
, depending onposition
andparentOrientation
.If the
from <vector>
is omitted, the position of ego is used.
- FacingToward(pos)[source]
The
facing toward <vector>
specifier.Specifies
yaw
, depending onposition
andparentOrientation
.
- FacingDirectlyToward(pos)[source]
The
facing directly toward <vector>
specifier.Specifies
yaw
andpitch
, depends onposition
andparentOrientation
.
- FacingAwayFrom(pos)[source]
The
facing away from <vector>
specifier.Specifies
yaw
, depending onposition
andparentOrientation
.
- FacingDirectlyAwayFrom(pos)[source]
The
facing directly away from <vector>
specifier.Specifies
yaw
andpitch
, depending onposition
andparentOrientation
.
- LeftSpec(pos, dist=None)[source]
The
left of X by Y
polymorphic specifier.Specifies
position
, and optionally,parentOrientation
, depending onwidth
.Allowed forms:
left of <oriented point> [by <scalar/vector>] left of <vector> [by <scalar/vector>]
If the
by <scalar/vector>
is omitted, the object’s contact tolerance is used.
- RightSpec(pos, dist=None)[source]
The
right of X by Y
polymorphic specifier.Specifies
position
, and optionallyparentOrientation
, depending onwidth
.Allowed forms:
right of <oriented point> [by <scalar/vector>] right of <vector> [by <scalar/vector>]
If the
by <scalar/vector>
is omitted, zero is used.
- Ahead(pos, dist=None)[source]
The
ahead of X by Y
polymorphic specifier.Specifies
position
, and optionallyparentOrientation
, depending onlength
.Allowed forms:
ahead of <oriented point> [by <scalar/vector>] ahead of <vector> [by <scalar/vector>]
If the
by <scalar/vector>
is omitted, the object’s contact tolerance is used.
- Behind(pos, dist=None)[source]
The
behind X by Y
polymorphic specifier.Specifies
position
, and optionallyparentOrientation
, depending onlength
.Allowed forms:
behind <oriented point> [by <scalar/vector>] behind <vector> [by <scalar/vector>]
If the
by <scalar/vector>
is omitted, the object’s contact tolerance is used.
- Above(pos, dist=None)[source]
The
above X by Y
polymorphic specifier.Specifies
position
, and optionallyparentOrientation
, depending onheight
.Allowed forms:
above <oriented point> [by <scalar/vector>] above <vector> [by <scalar/vector>]
If the
by <scalar/vector>
is omitted, the object’s contact tolerance is used.
- Below(pos, dist=None)[source]
The
below X by Y
polymorphic specifier.Specifies :prop`position`, and optionally
parentOrientation
, depending onheight
.Allowed forms:
below <oriented point> [by <scalar/vector>] below <vector> [by <scalar/vector>]
If the
by <scalar/vector>
is omitted, the object’s contact tolerance is used.
- Following(field, dist, fromPt=None)[source]
The
following F from X for D
specifier.Specifies
position
, and optionallyparentOrientation
, with no dependencies.Allowed forms:
following <field> [from <vector>] for <number>
If the
from <vector>
is omitted, the position of ego is used.
- exception GuardViolation(behavior, lineno)[source]
Bases:
Exception
Abstract exception raised when a guard of a behavior is violated.
This will never be raised directly; either of the subclasses
PreconditionViolation
orInvariantViolation
will be used, as appropriate.
- exception PreconditionViolation(behavior, lineno)[source]
Bases:
GuardViolation
Exception raised when a precondition is violated.
Raised when a precondition is violated when invoking a behavior or when a precondition encounters a
RejectionException
, so that rejections count as precondition violations.
- exception InvariantViolation(behavior, lineno)[source]
Bases:
GuardViolation
Exception raised when an invariant is violated.
Raised when an invariant is violated when invoking/resuming a behavior or when an invariant encounters a
RejectionException
, so that rejections count as invariant violations.
- exception RejectionException[source]
Bases:
Exception
Exception used to signal that the sample currently being generated must be rejected.
- _scenic_default
alias of
PropertyDefault
- class Behavior(*args, **kwargs)[source]
-
Dynamic behaviors of agents.
Behavior statements are translated into definitions of subclasses of this class.
- class Monitor(*args, **kwargs)[source]
Bases:
Behavior
Monitors for dynamic simulations.
Monitor statements are translated into definitions of subclasses of this class.
- class Modifier(name, value, terminator)[source]
Bases:
NamedTuple
- _asdict()
Return a new dict which maps field names to their values.
- classmethod _make(iterable)
Make a new Modifier object from a sequence or iterable
- _replace(**kwds)
Return a new Modifier object replacing specified fields with new values
- class DynamicScenario(*args, **kwargs)[source]
Bases:
Invocable
Internal class for scenarios which can execute during dynamic simulations.
Provides additional information complementing
Scenario
, which originally only supported static scenarios. The two classes should probably eventually be merged.- classmethod _requiresArguments()[source]
Whether this scenario cannot be instantiated without arguments.
- _prepare(delayPreconditionCheck=False)[source]
Prepare the scenario for execution, executing its setup block.
- _step()[source]
Execute the (already-started) scenario for one time step.
- Returns:
None
if the scenario will continue executing; otherwise a string describing why it has terminated.
- _addRequirement(ty, reqID, req, line, name, prob)[source]
Save a requirement defined at compile-time for later processing.