Specifiers Reference

Specifiers are used to define the properties of an object when a Scenic class is instantiated. This page describes all the specifiers built into Scenic, and the procedure used to resolve a set of specifiers into an assignment of values to properties.

Each specifier assigns values to one or more properties of an object, as a function of the arguments of the specifier and possibly other properties of the object assigned by other specifiers. For example, the left of X by Y specifier assigns the position property of the object being defined so that the object is a distance Y to the left of X: this requires knowing the width of the object first, so we say the left of specifier specifies the position property and depends on the width property.

In fact, the left of specifier also specifies the parentOrientation property (to be the orientation of X), but it does this with a lower priority. Multiple specifiers can specify the same property, but only the specifier that specifies the property with the highest priority is used. If a property is specified multiple times with the same priority, an ambiguity error is raised. We represent priorities as integers, with priority 1 being the highest and larger integers having progressively lower priorities (e.g. priority 2 supersedes priority 3). When a specifier specifies a property with a priority lower than 1, we say it optionally specifies the property, since it can be overridden (for example using the with specifier), whereas a specifier specifying the property with priority 1 cannot be overridden.

Certain specifiers can also modify already-specified values. These modifying specifiers do not cause an ambiguity error as above if another specifier specifies the same property with the same priority: they take the already-specified value and manipulate it in some way (potentially also specifying other properties as usual). Note that no property can be modified twice. The only modifying specifier currently in Scenic is on region, which can be used either as a standard specifier or a modifying specifier (the modifying version projects the already-specified position onto the given region – see below).

The Specifier Resolution process works out which specifier determines each property of an object, as well as an appropriate order in which to evaluate the specifiers so that dependencies have already been computed when needed.

General Specifiers

with property value

Specifies:

  • the given property, with priority 1

Dependencies: None

Assigns the given property to the given value. This is currently the only specifier available for properties other than position and orientation.

Position Specifiers

Diagram illustrating several specifiers.

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

at vector

Specifies:

  • position with priority 1

Dependencies: None

Positions the object at the given global coordinates.

in region

Specifies:

Dependencies: None

Positions the object uniformly at random in the given Region. If the Region has a preferred orientation (a vector field), also specifies parentOrientation to be equal to that orientation at the object’s position.

contained in region

Specifies:

  • position with priority 1

  • regionContainedIn with priority 1

  • parentOrientation with priority 3 (if the region has a preferred orientation)

Dependencies: None

Like in region, but also enforces that the object be entirely contained in the given Region.

on (region | Object | vector)

Specifies:

  • position with priority 1; modifies existing value, if any

  • parentOrientation with priority 2 (if the region has a preferred orientation)

Dependencies: baseOffsetcontactToleranceonDirection

If position is not already specified with priority 1, positions the base of the object uniformly at random in the given Region, on the onSurface of the given Object, or with the base of the object at the given vector. The position is always offset by half of contactTolerance (to avoid a collision). The base of the object is determined by adding the object’s baseOffset to its position.

If instead position has already been specified with priority 1, then its value is modified by projecting it onto the given region (or the onSurface of the given object). Note that this modifying version of the specifier does not accept a vector. More precisely, we find the closest point in the region along onDirection (or its negation [1]), and place the base of the object at that point. If onDirection is not specified, a default value is inferred from the region. A region can either specify a default value to be used, or for volumes straight up is used and for surfaces the mean of the face normal values is used (weighted by the area of the faces).

If the region has a preferred orientation (a vector field), parentOrientation is specified to be equal to that orientation at the object’s position (whether or not this specifier is being used as a modifying specifier). Note that this is done with higher priority than all other specifiers which optionally specify parentOrientation, and in particular the ahead of specifier and its variants: therefore the code new Object ahead of taxi by 100, on road aligns the new object with the road at the point 100 m ahead of the taxi rather than with the taxi itself (while also using projection to ensure the new object is on the surface of the road rather than under or over it if the road isn’t flat).

offset by vector

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: None

Positions the object at the given coordinates in the local coordinate system of ego (which must already be defined). Also specifies parentOrientation to be equal to the ego’s orientation.

New in version 3.0: offset by now specifies parentOrientation, whereas previously it did not optionally specify heading.

offset along direction by vector

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: None

Positions the object at the given coordinates in a local coordinate system centered at ego and oriented along the given direction (which can be a Heading, an Orientation, or a Vector Field). Also specifies parentOrientation to be equal to the ego’s orientation.

beyond vector by (vector | scalar) [from (vector | OrientedPoint)]

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: None

Positions the object at coordinates given by the second vector, in a local coordinate system centered at the first vector and oriented along the line of sight from the third vector (i.e. an orientation of (0,0,0) in the local coordinate system faces directly away from the third vector). If the second argument is a scalar D instead of a vector, it is interpreted as the vector (0, D, 0): thus beyond X by D from Y places the new object a distance of D behind X from the perspective of Y. If no third argument is provided, it is assumed to be the ego.

The value of parentOrientation is specified to be the orientation of the third argument if it is an OrientedPoint (including Object such as ego); otherwise the global coordinate system is used. For example, beyond taxi by (1, 3, 0) means 3 meters behind the taxi and one meter to the right as viewed by the ego.

visible [from (Point | OrientedPoint)]

Specifies:

  • position with priority 3

  • also adds a requirement (see below)

Dependencies: None

Requires that this object is visible from the ego or the given Point/OrientedPoint. See the Visibility System reference for a discussion of the visibility model.

Also optionally specifies position to be a uniformly random point in the visible region of the ego, or of the given Point/OrientedPoint if given. Note that the position set by this specifier is slightly stricter than simply adding a requirement that the ego can see the object: the specifier makes the center of the object (its position) visible, while the can see condition will be satisfied even if the center is not visible as long as some other part of the object is visible.

not visible [from (Point | OrientedPoint)]

Specifies:

  • position with priority 3

  • also adds a requirement (see below)

Dependencies: regionContainedIn

Requires that this object is not visible from the ego or the given Point/OrientedPoint.

Similarly to visible [from (Point | OrientedPoint)], this specifier can position the object uniformly at random in the non-visible region of the ego. However, it depends on regionContainedIn, in order to restrict the non-visible region to the container of the object being created, which is hopefully a bounded region (if the non-visible region is unbounded, it cannot be uniformly sampled from and an error will be raised).

(left | right) of (vector) [by scalar]

Specifies:

  • position with priority 1

Dependencies: widthorientation

Without the optional by scalar, positions the object immediately to the left/right of the given position; i.e., so that the midpoint of the right/left side of the object’s bounding box is at that position. If by scalar is used, the object is placed further to the left/right by the given distance.

(left | right) of OrientedPoint [by scalar]

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: width

Positions the object to the left/right of the given OrientedPoint. Also inherits parentOrientation from the given OrientedPoint.

(left | right) of Object [by scalar]

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: widthcontactTolerance

Positions the object to the left/right of the given Object. This accounts for both objects’ dimensions, placing them so that the distance between their bounding boxes is exactly the desired scalar distance (or contactTolerance if by scalar is not used). Also inherits parentOrientation from the given OrientedPoint.

(ahead of | behind) vector [by scalar]

Specifies:

  • position with priority 1

Dependencies: lengthorientation

Without the optional by scalar, positions the object immediately ahead of/behind the given position; i.e., so that the midpoint of the front/back side of the object’s bounding box is at that position. If by scalar is used, the object is placed further ahead/behind by the given distance.

(ahead of | behind) OrientedPoint [by scalar]

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: length

Positions the object ahead of/behind the given OrientedPoint. Also inherits parentOrientation from the given OrientedPoint.

(ahead of | behind) Object [by scalar]

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: lengthcontactTolerance

Positions the object ahead of/behind the given Object. This accounts for both objects’ dimensions, placing them so that the distance between their bounding boxes is exactly the desired scalar distance (or contactTolerance if by scalar is not used). Also inherits parentOrientation from the given OrientedPoint.

(above | below) vector [by scalar]

Specifies:

  • position with priority 1

Dependencies: heightorientation

Without the optional by scalar, positions the object immediately above/below the given position; i.e., so that the midpoint of the top/bottom side of the object’s bounding box is at that position. If by scalar is used, the object is placed further above/below by the given distance.

(above | below) OrientedPoint [by scalar]

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: height

Positions the object above/below the given OrientedPoint. Also inherits parentOrientation from the given OrientedPoint.

(above | below) Object [by scalar]

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: heightcontactTolerance

Positions the object above/below the given Object. This accounts for both objects’ dimensions, placing them so that the distance between their bounding boxes is exactly the desired scalar distance (or contactTolerance if by scalar is not used). Also inherits parentOrientation from the given OrientedPoint.

following vectorField [from vector] for scalar

Specifies:

  • position with priority 1

  • parentOrientation with priority 3

Dependencies: None

Positions the object at a point obtained by following the given Vector Field for the given distance starting from ego (or the position optionally provided with from vector). Specifies parentOrientation to be the orientation of the vector field at the resulting point.

Note

This specifier uses a forward Euler approximation of the continuous vector field. The choice of step size can be customized for individual fields: see the documentation of Vector Field. If necessary, you can also call the underlying method VectorField.followFrom directly.

Orientation Specifiers

facing orientation

Specifies:

  • yaw with priority 1

  • pitch with priority 1

  • roll with priority 1

Dependencies: parentOrientation

Sets the object’s yaw, pitch, and roll so that its orientation in global coordinates is equal to the given orientation. If a single scalar is given, it is interpreted as a Heading: so for example facing 45 deg orients the object in the XY plane, facing northwest. If a triple of scalars is given, it is interpreted as a triple of global Euler angles: so for example facing (45 deg, 90 deg, 0) would orient the object to face northwest as above but then apply a 90° pitch upwards.

facing vectorField

Specifies:

  • yaw with priority 1

  • pitch with priority 1

  • roll with priority 1

Dependencies: positionparentOrientation

Sets the object’s yaw, pitch, and roll so that its orientation in global coordinates is equal to the orientation provided by the given Vector Field at the object’s position.

facing (toward | away from) vector

Specifies:

  • yaw with priority 1

Dependencies: positionparentOrientation

Sets the object’s yaw so that it faces toward/away from the given position (thereby depending on the object’s position).

facing directly (toward | away from) vector

Specifies:

  • yaw with priority 1

  • pitch with priority 1

Dependencies: positionparentOrientation

Sets the object’s yaw and pitch so that it faces directly toward/away from the given position (thereby depending on the object’s position).

apparently facing heading [from vector]

Specifies:

  • yaw with priority 1

Dependencies: positionparentOrientation

Sets the yaw of the object so that it has the given heading with respect to the line of sight from ego (or the from vector). For example, if the ego is in the XY plane, then apparently facing 90 deg orients the new object so that the ego’s camera views its left side head-on.

Specifier Resolution

Specifier resolution is the process of determining, given the set of specifiers used to define an object, which properties each specifier should determine and what order to evaluate the specifiers in. As each specifier can specify multiple properties with various priorities, and can depend on the results of other specifiers, this process is somewhat non-trivial. Assuming there are no cyclic dependencies or conflicts, the process will conclude with each property being determined by its unique highest-priority specifier if one exists (possibly modified by a modifying specifier), and otherwise by its default value, with default values from subclasses overriding those in superclasses.

The full procedure, given a set of specifiers S used to define an instance of class C, works as follows:

  1. If a property is specified at the same priority level by multiple specifiers in S, an ambiguity error is raised.

  2. The set of properties P for the new object is found by combining the properties specified by all members of S with the properties inherited from the class C.

  3. Default value specifiers from C (or if not overridden, from its superclasses) are added to S as needed so that each property in P is paired with a unique non-modifying specifier in S specifying it (taking the highest-priority specifier, if there are multiple), plus up to one modifying specifier modifying it.

  4. The dependency graph of the specifiers S is constructed (with edges from each specifier to the others which depend on its results). If it is cyclic, an error is raised.

  5. The graph is topologically sorted and the specifiers are evaluated in this order to determine the values of all properties P of the new object.