Objects and Classes Reference

This page describes the classes built into Scenic, representing points, oriented points, and physical objects, and how they are instantiated to create objects.

Note

The documentation given here describes only the public properties and methods provided by the built-in classes. If you are working on Scenic’s internals, you can find more complete documentation in the scenic.core.object_types module.

Instance Creation

new <class> [<specifier> [, <specifier>]*]

Instantiates a Scenic object from a Scenic class. The properties of the object are determined by the given set of zero or more specifiers. For details on the available specifiers and how they interact, see the Specifiers Reference.

Instantiating an instance of Object has a side effect: the object is added to the scenario being defined.

Changed in version 3.0: Instance creation now requires the new keyword. As a result, Scenic classes can be referred to without creating an instance.

Built-in Classes

Point

Locations in space. This class provides the fundamental property position and several associated properties.

class Point <specifiers>[source]

The Scenic base class Point.

The default mutator for Point adds Gaussian noise to position with a standard deviation given by the positionStdDev 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 this Point on a region, when using the modifying on specifier. See the on 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 if viewRayCount 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 value False.

  • 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 its position with radius visibleDistance.

OrientedPoint

A location along with an orientation, defining a local coordinate system. This class subclasses Point, adding the fundamental property orientation and several associated properties.

class OrientedPoint <specifiers>[source]

The Scenic class OrientedPoint.

The default mutator for OrientedPoint adds Gaussian noise to yaw, pitch and roll, using the three standard deviations (for yaw/pitch/roll respectively) given by the orientationStdDev property. It then also applies the mutator for Point. By default the standard deviations for pitch and roll are zero so that, by default, only yaw is mutated.

Properties:

  • yaw (float; dynamic) – Yaw of the OrientedPoint in radians in the local coordinate system provided by parentOrientation. Default value 0.

  • pitch (float; dynamic) – Pitch of the OrientedPoint in radians in the local coordinate system provided by parentOrientation. Default value 0.

  • roll (float; dynamic) – Roll of the OrientedPoint in radians in the local coordinate system provided by parentOrientation. Default value 0.

  • parentOrientation (Orientation) – The local coordinate system that the OrientedPoint’s yaw, pitch, and roll 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 the OrientedPoint relative to the global coordinate system. Derived from the yaw, pitch, roll, and parentOrientation of this OrientedPoint and non-overridable.

  • heading (float; dynamic; final) – Yaw value of this OrientedPoint in the global coordinate system. Derived from orientation 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 this OrientedPoint.

property visibleRegion

The visible region of this object.

The visible region of an OrientedPoint restricts that of Point (a sphere with radius visibleDistance) based on the value of viewAngles. In general, it is a capped rectangular pyramid subtending an angle of viewAngles[0] horizontally and viewAngles[1] vertically, as long as those angles are less than π/2; larger angles yield various kinds of wrap-around regions. See ViewRegion for details.

Object

A physical object. This class subclasses OrientedPoint, adding a variety of properties including:

  • width, length, and height to define the dimensions of the object;

  • shape to define the Shape of the object;

  • allowCollisions, requireVisible, and regionContainedIn to control the built-in requirements that apply to the object;

  • behavior, specifying the object’s dynamic behavior if any;

  • speed, velocity, and other properties capturing the dynamic state of the object during simulations.

The built-in requirements applying to each object are:

  • The object must be completely contained within its container, the region specified as its regionContainedIn property (by default the entire workspace).

  • The object must be visible from the ego object if the requireVisible property is set to True (default value False).

  • The object must not intersect another object (i.e., their bounding boxes must not overlap), unless either of the two objects has their allowCollisions property set to True.

Changed in version 3.0: requireVisible is now False by default.

class Object <specifiers>[source]

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 of Shape. 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 or None) – A Region the object is required to be contained in. If None, the object need only be contained in the scenario’s workspace.

  • baseOffset (Vector) – An offset from the position 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. See defaultSideSurface for details. Default value ((-0.5, 0.5), (-0.5, 0.5), (-0.5, 0.5)).

  • cameraOffset (Vector) – Position of the camera for the can see operator, relative to the object’s position. Default (0, 0, 0).

  • requireVisible (bool) – Whether the object is required to be visible from the ego object. Default value False.

  • 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 value None

  • velocity (Vector; dynamic) – Velocity in dynamic simulations. Default value is the velocity determined by speed and orientation.

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

property visibleRegion

The visible region of this object.

The visible region of an Object is the same as that of an OrientedPoint (see OrientedPoint.visibleRegion) except that it is offset by the value of cameraOffset (which is the zero vector by default).