scenic.core.object_types

Implementations of the built-in Scenic classes.

Defines the 3 Scenic classes Point, OrientedPoint, and Object, and associated helper code (notably their base class Constructible, which implements the handling of property definitions and Specifier Resolution).

Warning

In 2D Compatibility Mode, these classes are overwritten with 2D analogs. While we make an effort to map imports to the correct class, this only works if imports use the form import scenic.core.object_types as object_types followed by accessing object_types.Object. If you instead use from scenic.core.object_types import Object, you may get the wrong class.

Summary of Module Members

Module Attributes

Interval	Type alias for an interval (a pair of floats).
DimensionLimits	Type alias for limits on dimensions (a triple of intervals).

Functions

defaultSideSurface	Extracts a side surface from the occupiedSpace of an object.
disableDynamicProxyFor
enableDynamicProxyFor
precomputed_property	A @property which can be precomputed if its dependencies are not random.
setDynamicProxyFor

Classes

Constructible	Abstract base class for Scenic objects.
Mutator	An object controlling how the mutate statement affects an Object.
Object	The Scenic class Object.
Object2D	A 2D version of Object, used for backwards compatibility with Scenic 2.0
OrientationMutator	Mutator adding Gaussian noise to yaw, pitch, and roll.
OrientedPoint	The Scenic class OrientedPoint.
OrientedPoint2D	A 2D version of OrientedPoint, used for backwards compatibility with Scenic 2.0
Point	The Scenic base class Point.
Point2D	A 2D version of Point, used for backwards compatibility with Scenic 2.0
PositionMutator	Mutator adding Gaussian noise to position.

Member Details

Interval

Type alias for an interval (a pair of floats).

alias of Tuple[float, float]

DimensionLimits

Type alias for limits on dimensions (a triple of intervals).

alias of Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]

class Constructible(properties, constProps=frozenset({}), _internal=False)

Bases: Samplable

Abstract base class for Scenic objects.

Scenic objects, which are constructed using specifiers, are implemented internally as instances of ordinary Python classes. This abstract class implements the procedure to resolve specifiers and determine values for the properties of an object, as well as several common methods supported by objects.

Warning

This class is an implementation detail, and none of its methods should be called directly from a Scenic program.

classmethod _withProperties(properties, constProps=None)

Create an instance with the given property values.

Values of unspecified properties are determined by specifier resolution as usual.

classmethod _withSpecifiers(specifiers, constProps=None, register=True)

Create an instance from the given specifiers.

_copyWith(**overrides)

Copy this object, possibly overriding some of its properties.

precomputed_property(func)

A @property which can be precomputed if its dependencies are not random.

Converts a function inside a subclass of Constructible into a method; the function’s arguments must correspond to the properties of the object needed to compute this property. If any of those dependencies have random values, this property will evaluate to None; otherwise it will be computed once the first time it is needed and then reused across samples.

class Mutator

An object controlling how the mutate statement affects an Object.

A Mutator can be assigned to the mutator property of an Object to control the effect of the mutate statement. When mutation is enabled for such an object using that statement, the mutator’s appliedTo method is called to compute a mutated version. The appliedTo method can also decide whether to apply mutators inherited from superclasses.

appliedTo(obj)

Return a mutated version 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 in mutate O by S.

Returns:

A pair consisting of the mutated version of the object together with a Boolean indicating whether the mutator inherited from the superclass (if any) should also be applied.

class PositionMutator(stddevs)

Bases: Mutator

Mutator adding Gaussian noise to position. Used by Point.

Attributes:

stddevs (tuple[float,float,float]) – standard deviation of noise for each dimension (x,y,z).

class OrientationMutator(stddevs)

Bases: Mutator

Mutator adding Gaussian noise to yaw, pitch, and roll. Used by OrientedPoint.

Attributes:

stddevs (tuple[float,float,float]) – standard deviation of noise for each angle (yaw, pitch, roll).

class Point <specifiers>

Bases: Constructible

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.

canSee(other, occludingObjects=(), debug=False)

Whether or not this Point can see other.

Parameters:

• other – A Point, OrientedPoint, or Object to check for visibility.

• occludingObjects – A list of objects that can occlude visibility.

Return type:

bool

class OrientedPoint <specifiers>

Bases: Point

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.

canSee(other, occludingObjects=(), debug=False)

Whether or not this OrientedPoint can see other.

Parameters:

• other – A Point, OrientedPoint, or Object to check for visibility.

• occludingObjects – A list of objects that can occlude visibility.

Return type:

bool

distancePast(vec)

Distance past a given point, assuming we’ve been moving in a straight line.

class Object <specifiers>

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

• visionSensorOffset (Vector) – Offset of the default vision sensor mount point, relative to the object’s position. Defaults to the front-center of the bounding box, (0, self.length/2, 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

• render (bool) – Whether this object is drawn in Scenic’s internal visualizer. Default value True. Set to False to hide the object.

• 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 (an empty tuple if the object is not an agent or this is the first time step).

• sensors – Dict of (“name”: sensor) that populate the observations field every time step

• observations – Dict of (“name”: observation) storing the latest observation of the sensor with the same name

startDynamicSimulation()

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.

containsPoint(point)

Whether or not the space this object occupies contains a point

distanceTo(point)

The minimal distance from the space this object occupies to a given point

intersects(other)

Whether or not this object intersects another object or region

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

canSee(other, occludingObjects=(), debug=False)

Whether or not this Object can see other.

Parameters:

• other – A Point, OrientedPoint, or Object to check for visibility.

• occludingObjects – A list of objects that can occlude visibility.

Return type:

bool

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 planarInradius

A lower bound on the planar inradius of this object.

This is defined as the inradius of the polygon of the occupiedSpace of this object projected into the XY plane, assuming that pitch and roll are both 0.

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.

defaultSideSurface(occupiedSpace, dimension, positive, thresholds)

Extracts a side surface from the occupiedSpace of an object.

This function is the default implementation for computing a region representing a side surface of an object. This is done by keeping only the faces of the object’s occupiedSpace mesh that have normal vectors with a large/small enough x,y, or z component. For example, for the front surface of an object we would would keep all faces that had a normal vector with y component greater than thresholds[1][1] and for the back surface of an object we would keep all faces that had a normal vector with y component less than thresholds[1][0].

Parameters:

• occupiedSpace – The occupiedSpace region of the object to extract the side surface from.

• dimension – The target dimension who’s component will be checked.

• positive – If False, the target component must be less than the first value in the appropriate tuple. If True, the component must be greater than the second value in the appropriate tuple.

• thresholds – A 3-tuple of 2-tuples, one for each dimension (x,y,z), with each tuple containing the thresholds for a non-positive and positive side, respectively, in each dimension.

• on_dimension – The on_dimension to be passed to the created surface.

Return type:

MeshSurfaceRegion

class Point2D <specifiers>

Bases: Point

A 2D version of Point, used for backwards compatibility with Scenic 2.0

_3DClass

alias of Point

property visibleRegion

The visible region of this 2D point.

The visible region of a Point is a disc centered at its position with radius visibleDistance.

class OrientedPoint2D <specifiers>

Bases: Point2D, OrientedPoint

A 2D version of OrientedPoint, used for backwards compatibility with Scenic 2.0

_3DClass

alias of OrientedPoint

property visibleRegion

The visible region of this 2D oriented point.

The visible region of an OrientedPoint is a sector of the disc centered at its position with radius visibleDistance, oriented along heading and subtending an angle of viewAngle.

class Object2D <specifiers>

Bases: OrientedPoint2D, Object

A 2D version of Object, used for backwards compatibility with Scenic 2.0

_3DClass

alias of Object

property visibleRegion

The visible region of this 2D object.

The visible region of a 2D Object is a circular sector as for OrientedPoint, except that the base of the sector may be offset from position by the cameraOffset property (to allow modeling cameras which are not located at the center of the object).