Syntax Guide

This page summarizes the syntax of Scenic (excluding syntax inherited from Python). For more details, click the links for individual language constructs to go to the corresponding reference section.

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 orientations in space

Vector Fields

associating an orientation (i.e. a heading) to each point in space

Regions

representing sets of points in space

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

Point (in | on) 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:

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 identifier = value, ...

Define global parameters of the scenario.

require boolean

Define a hard requirement.

require[number] boolean

Define a soft requirement.

require (always | eventually) boolean

Define a dynamic hard requirement.

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.

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

position in global coordinates

viewDistance

50

distance for the ‘can see’ operator

mutationScale

0

overall scale of mutations

positionStdDev

1

mutation standard deviation for position

Properties added by OrientedPoint:

Property

Default

Meaning

heading 1

0

heading in global coordinates

viewAngle

360 degrees

angle for the ‘can see’ operator

headingStdDev

5 degrees

mutation standard deviation for heading

Properties added by Object:

Property

Default

Meaning

width

1

width of bounding box (X axis)

length

1

length of bounding box (Y axis)

speed 1

0

initial speed (later, instantaneous speed)

velocity 1

from speed

initial velocity (later, instantaneous velocity)

angularSpeed 1

0

angular speed (change in heading/time)

behavior

None

dynamic behavior, if any

allowCollisions

False

whether collisions are allowed

requireVisible

True

whether object must be visible from ego

regionContainedIn

workspace

Region the object must lie within

cameraOffset

(0, 0)

position of camera for ‘can see’

1(1,2,3,4,5)

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 heading properties are listed below.

Diagram illustrating several specifiers.

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

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

(left | right) of vector [by scalar]

Positions the object further to the left/right by the given scalar distance

(ahead of | behind) vector [by scalar]

As above, except placing the object ahead of or behind the given position

beyond vector by vector [from vector]

Positions the object at coordinates given by the second vector, centered at the first vector and oriented along the line of sight from the third vector/ego

visible [from (Point | OrientedPoint)]

Positions the object uniformly at random in the visible region of the ego, or of the given Point/OrientedPoint if given

not visible [from (Point | OrientedPoint)]

Positions the object uniformly at random in the non-visible region of the ego, or of the given Point/OrientedPoint if given

Specifier for position and optionally heading

Meaning

(in | on) region

Positions the object uniformly at random in the given Region

(left | right) of (OrientedPoint | Object) [by scalar]

Positions the object to the left/right of the given OrientedPoint, depending on the object’s width

(ahead of | behind) (OrientedPoint | Object) [by scalar]

As above, except positioning the object ahead of or behind the given OrientedPoint, thereby depending on length

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 heading

Meaning

facing heading

Orients the object along the given heading 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)

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

Diagram illustrating several operators.

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

Heading Operators

Meaning

scalar deg

The given heading, interpreted as being in degrees

vectorField at vector

The heading specified by the vector field at the given position

direction relative to direction

The first direction, 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

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 edge of the bounding box of the Object, oriented along its heading

(front | back) (left | right) of Object

The corresponding corner of the Object’s bounding box, also oriented along its heading

Built in Functions

Function

Description

Misc Python functions

Various Python functions including min, max, sin, cos, 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.