Syntax Guide

This page summarizes the syntax of Scenic, excluding the basic syntax of variable assignments, functions, loops, etc., which is identical to Python (see the Python Tutorial for an introduction). For more details, click the links for individual language constructs to go to the corresponding section of the Language Reference.

Primitive Data Types

Booleans	expressing truth values
Scalars	representing distances, angles, etc. as floating-point numbers
Vectors	representing positions and offsets in space
Headings	representing 2D orientations in the XY plane
Orientations	representing 3D orientations in space
Vector Fields	associating an orientation to each point in space
Regions	representing sets of points in space
Shapes	representing shapes (regions modulo similarity)

Distributions

Range(low, high)	uniformly-distributed real number in the interval
DiscreteRange(low, high)	uniformly-distributed integer in the (fixed) interval
Normal(mean, stdDev)	normal distribution with the given mean and standard deviation
TruncatedNormal(mean, stdDev, low, high)	normal distribution truncated to the given window
Uniform(value, ...)	uniform over a finite set of values
Discrete({value: weight, ...})	discrete with given values and weights
new Point in region	uniformly-distributed Point in a region

Statements

Compound Statements

Syntax	Meaning
class name[(superclass)]:	Defines a Scenic class.
behavior name(arguments):	Defines a dynamic behavior.
monitor name(arguments):	Defines a monitor.
scenario name(arguments):	Defines a modular scenario.
try: ... interrupt when boolean:	Run code with interrupts inside a dynamic behavior or modular scenario.

Simple Statements

Syntax	Meaning
model name	Select the world model.
import module	Import a Scenic or Python module.
param name = value, ...	Define global parameters of the scenario.
require boolean	Define a hard requirement.
require[number] boolean	Define a soft requirement.
require LTL formula	Define a dynamic hard requirement.
require monitor monitor	Define a dynamic requirement using a monitor.
terminate when boolean	Define a termination condition.
terminate after scalar (seconds | steps)	Set the scenario to terminate after a given amount of time.
mutate identifier, ... [by number]	Enable mutation of the given list of objects.
record [initial | final] value as name	Save a value at every time step or only at the start/end of the simulation.

Dynamic Statements

These statements can only be used inside a dynamic behavior, monitor, or compose block of a modular scenario.

Syntax	Meaning
take action, ...	Take the action(s) specified.
wait	Take no actions this time step.
terminate	Immediately end the scenario.
terminate simulation	Immediately end the entire simulation.
do behavior/scenario, ...	Run one or more sub-behaviors/sub-scenarios until they complete.
do behavior/scenario, ... until boolean	Run sub-behaviors/scenarios until they complete or a condition is met.
do behavior/scenario, ... for scalar (seconds | steps)	Run sub-behaviors/scenarios for (at most) a specified period of time.
do choose behavior/scenario, ...	Run one choice of sub-behavior/scenario whose preconditions are satisfied.
do shuffle behavior/scenario, ...	Run several sub-behaviors/scenarios in a random order, satisfying preconditions.
abort	Break out of the current try-interrupt statement.
override object specifier, ...	Override properties of an object for the duration of the current scenario.

Objects

The syntax new class specifier, ... creates an instance of a Scenic class.

The Scenic class Point provides the basic position properties in the first table below; its subclass OrientedPoint adds the orientation properties in the second table. Finally, the class Object, which represents physical objects and is the default superclass of user-defined Scenic classes, adds the properties in the third table. See the Objects and Classes Reference for details.

Property	Default	Meaning
position [1]	(0, 0, 0)	position in global coordinates
visibleDistance	50	distance for the ‘can see’ operator
viewRayDensity	5	determines ray count (if ray count is not provided)
viewRayDistanceScaling	False	whether to scale number of rays with distance (if ray count is not provided)
viewRayCount	None	tuple of number of rays to send in each dimension.
mutationScale	0	overall scale of mutations
positionStdDev	(1,1,0)	mutation standard deviation for position

Properties added by OrientedPoint:

Property	Default	Meaning
yaw [1]	0	yaw in local coordinates
pitch [1]	0	pitch in local coordinates
roll [1]	0	roll in local coordinates
parentOrientation	global	basis for local coordinate system
viewAngles	(2π, π)	angles for visibility calculations
orientationStdDev	(5°, 0, 0)	mutation standard deviation for orientation

Properties added by Object:

Property	Default	Meaning
width	1	width of bounding box (X axis)
length	1	length of bounding box (Y axis)
height	1	height of bounding box (Z axis)
shape	BoxShape	shape of the object
allowCollisions	False	whether collisions are allowed
regionContainedIn	workspace	Region the object must lie within
baseOffset	(0, 0, -self.height/2)	offset determining the base of the object
contactTolerance	1e-4	max distance to be considered on a surface
sideComponentThresholds	(-0.5, 0.5) per side	thresholds to determine side surfaces
cameraOffset	(0, 0, 0)	position of camera for can see
requireVisible	False	whether object must be visible from ego
occluding	True	whether object occludes visibility
showVisibleRegion	False	whether to display the visible region
color	None	color of object
velocity [1]	from speed	initial (instantaneous) velocity
speed [1]	0	initial (later, instantaneous) speed
angularVelocity [1]	(0, 0, 0)	initial (instantaneous) angular velocity
angularSpeed [1]	0	angular speed (change in heading/time)
behavior	None	dynamic behavior, if any
lastActions	None	tuple of actions taken in last timestamp

[1] (1,2,3,4,5,6,7,8)

These are dynamic properties, updated automatically every time step during dynamic simulations.

Specifiers

The with property value specifier can specify any property, including new properties not built into Scenic. Additional specifiers for the position and orientation properties are listed below.

Illustration of the beyond, behind, and offset by specifiers. Each OrientedPoint (e.g. P) is shown as a bold arrow.

Specifier for position	Meaning
at vector	Positions the object at the given global coordinates
in region	Positions the object uniformly at random in the given Region
contained in region	Positions the object uniformly at random entirely contained in the given Region
on vector	Positions the base of the object at the given global coordinates
on (region | Object)	Positions the object uniformly at random or modifies the position so that base of the Object is in the given Region/on the given Object.
offset by vector	Positions the object at the given coordinates in the local coordinate system of ego (which must already be defined)
offset along direction by vector	Positions the object at the given coordinates, in a local coordinate system centered at ego and oriented along the given direction
beyond vector by (vector | scalar) [from (vector | OrientedPoint)]	Positions the object with respect to the line of sight from a point or the ego
visible [from (Point | OrientedPoint)]	Ensures the object is visible from the ego, or from the given Point/OrientedPoint if given, while optionally specifying position to be uniformly random over all positions that result in a visible object.
not visible [from (Point | OrientedPoint)]	Ensures the object is not visible from the ego, or from the given Point/OrientedPoint if given, while optionally specifying position to be uniformly random over all positions that result in a non-visible object.
(left | right) of (vector | OrientedPoint | Object) [by scalar]	Positions the object to the left/right by the given scalar distance.
(ahead of | behind) (vector | OrientedPoint | Object) [by scalar]	Positions the object to the front/back by the given scalar distance
(above | below) (vector | OrientedPoint | Object) [by scalar]	Positions the object above/below by the given scalar distance
following vectorField [from vector] for scalar	Position by following the given vector field for the given distance starting from ego or the given vector

Specifier for orientation	Meaning
facing orientation	Orients the object along the given orientation in global coordinates
facing vectorField	Orients the object along the given vector field at the object’s position
facing (toward | away from) vector	Orients the object toward/away from the given position (thereby depending on the object’s position)
facing directly (toward | away from) vector	Orients the object directly toward/away from the given position (thereby depending on the object’s position)
apparently facing heading [from vector]	Orients the object so that it has the given heading with respect to the line of sight from ego (or the given vector)

Operators

In the following tables, operators are grouped by the type of value they return.

Illustration of several operators. Each OrientedPoint (e.g. P) is shown as a bold arrow.

Scalar Operators	Meaning
relative heading of heading [from heading]	The relative heading of the given heading with respect to ego (or the from heading)
apparent heading of OrientedPoint [from vector]	The apparent heading of the OrientedPoint, with respect to the line of sight from ego (or the given vector)
distance [from vector] to vector	The distance to the given position from ego (or the from vector)
angle [from vector] to vector	The heading (azimuth) to the given position from ego (or the from vector)
altitude [from vector] to vector	The altitude to the given position from ego (or the from vector)

Boolean Operators	Meaning
(Point | OrientedPoint) can see (vector | Object)	Whether or not a position or Object is visible from a Point or OrientedPoint
(vector | Object) in region	Whether a position or Object lies in the region
(Object | region) intersects (Object | region)	Whether an Object/Region intersects an Object/Region.

Orientation Operators	Meaning
scalar deg	The given angle, interpreted as being in degrees
vectorField at vector	The orientation specified by the vector field at the given position
direction relative to direction	The first direction (a heading, orientation, or vector field), interpreted as an offset relative to the second direction

Vector Operators	Meaning
vector (relative to | offset by) vector	The first vector, interpreted as an offset relative to the second vector (or vice versa)
vector offset along direction by vector	The second vector, interpreted in a local coordinate system centered at the first vector and oriented along the given direction

Region Operators	Meaning
visible region	The part of the given region visible from ego
not visible region	The part of the given region not visible from ego
region visible from (Point | OrientedPoint)	The part of the given region visible from the given Point or OrientedPoint.
region not visible from (Point | OrientedPoint)	The part of the given region not visible from the given Point or OrientedPoint.

OrientedPoint Operators	Meaning
vector relative to OrientedPoint	The given vector, interpreted in the local coordinate system of the OrientedPoint
OrientedPoint offset by vector	Equivalent to vector relative to OrientedPoint above
(front | back | left | right) of Object	The midpoint of the corresponding side of the bounding box of the Object, inheriting the Object’s orientation.
(front | back) (left | right) of Object	The midpoint of the corresponding edge of the bounding box of the Object, inheriting the Object’s orientation.
(front | back) (left | right) of Object	The midpoint of the corresponding edge of the bounding box of the Object, inheriting the Object’s orientation.
(top | bottom) (front | back) (left | right) of Object	The corresponding corner of the bounding box of the Object, inheriting the Object’s orientation.

Temporal Operators	Meaning
always condition	Require the condition to hold at every time step.
eventually condition	Require the condition to hold at some time step.
next condition	Require the condition to hold in the next time step.
condition until condition	Require the first condition to hold until the second becomes true.
condition implies condition	Require the second condition to hold if the first condition holds.

Built-in Functions

Function	Description
Misc Python functions	Various Python functions including min, max, open, etc.
filter	Filter a possibly-random list (allowing limited randomized control flow).
resample	Sample a new value from a distribution.
localPath	Convert a relative path to an absolute path, based on the current directory.
verbosePrint	Like print, but silent at low-enough verbosity levels.
simulation	Get the the current simulation object.