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
Type alias for an interval (a pair of floats). |
|
Type alias for limits on dimensions (a triple of intervals). |
Functions
Extracts a side surface from the occupiedSpace of an object. |
|
|
|
|
|
|
Classes
Abstract base class for Scenic objects. |
|
An object controlling how the |
|
The Scenic class |
|
A 2D version of |
|
Mutator adding Gaussian noise to |
|
The Scenic class |
|
A 2D version of |
|
The Scenic base class |
|
A 2D version of |
|
Mutator adding Gaussian noise to |
Member Details
- 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)[source]
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)[source]
Create an instance with the given property values.
Values of unspecified properties are determined by specifier resolution as usual.
- class Mutator[source]
An object controlling how the
mutate
statement affects anObject
.A
Mutator
can be assigned to themutator
property of anObject
to control the effect of themutate
statement. When mutation is enabled for such an object using that statement, the mutator’sappliedTo
method is called to compute a mutated version. TheappliedTo
method can also decide whether to apply mutators inherited from superclasses.- appliedTo(obj)[source]
Return a mutated copy 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 inmutate O by S
.- Returns:
A pair consisting of the mutated copy of the object (which is most easily created using
_copyWith
) together with a Boolean indicating whether the mutator inherited from the superclass (if any) should also be applied.
- class PositionMutator(stddevs)[source]
Bases:
Mutator
Mutator adding Gaussian noise to
position
. Used byPoint
.- Attributes:
stddevs (tuple[float,float,float]) – standard deviation of noise for each dimension (x,y,z).
- class OrientationMutator(stddevs)[source]
Bases:
Mutator
Mutator adding Gaussian noise to
yaw
,pitch
, androll
. Used byOrientedPoint
.- Attributes:
stddevs (tuple[float,float,float]) – standard deviation of noise for each angle (yaw, pitch, roll).
- class Point <specifiers>[source]
Bases:
Constructible
The Scenic base class
Point
.The default mutator for
Point
adds Gaussian noise toposition
with a standard deviation given by thepositionStdDev
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 thisPoint
on a region, when using the modifyingon
specifier. See theon 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 ifviewRayCount
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 valueFalse
.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 itsposition
with radiusvisibleDistance
.
- class OrientedPoint <specifiers>[source]
Bases:
Point
The Scenic class
OrientedPoint
.The default mutator for
OrientedPoint
adds Gaussian noise toyaw
,pitch
androll
, using the three standard deviations (for yaw/pitch/roll respectively) given by theorientationStdDev
property. It then also applies the mutator forPoint
. By default the standard deviations forpitch
androll
are zero so that, by default, onlyyaw
is mutated.- Properties:
yaw (float; dynamic) – Yaw of the
OrientedPoint
in radians in the local coordinate system provided byparentOrientation
. Default value 0.pitch (float; dynamic) – Pitch of the
OrientedPoint
in radians in the local coordinate system provided byparentOrientation
. Default value 0.roll (float; dynamic) – Roll of the
OrientedPoint
in radians in the local coordinate system provided byparentOrientation
. Default value 0.parentOrientation (
Orientation
) – The local coordinate system that theOrientedPoint
’syaw
,pitch
, androll
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 theOrientedPoint
relative to the global coordinate system. Derived from theyaw
,pitch
,roll
, andparentOrientation
of thisOrientedPoint
and non-overridable.heading (float; dynamic; final) – Yaw value of this
OrientedPoint
in the global coordinate system. Derived fromorientation
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 thisOrientedPoint
.
- property visibleRegion
The visible region of this object.
The visible region of an
OrientedPoint
restricts that ofPoint
(a sphere with radiusvisibleDistance
) based on the value ofviewAngles
. In general, it is a capped rectangular pyramid subtending an angle ofviewAngles[0]
horizontally andviewAngles[1]
vertically, as long as those angles are less than π/2; larger angles yield various kinds of wrap-around regions. SeeViewRegion
for details.
- canSee(other, occludingObjects=(), debug=False)[source]
Whether or not this
OrientedPoint
can seeother
.- Parameters:
other – A
Point
,OrientedPoint
, orObject
to check for visibility.occludingObjects – A list of objects that can occlude visibility.
- Return type:
- class Object <specifiers>[source]
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 ofShape
. 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
orNone
) – ARegion
the object is required to be contained in. IfNone
, the object need only be contained in the scenario’s workspace.baseOffset (
Vector
) – An offset from theposition
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. SeedefaultSideSurface
for details. Default value((-0.5, 0.5), (-0.5, 0.5), (-0.5, 0.5))
.cameraOffset (
Vector
) – Position of the camera for thecan see
operator, relative to the object’sposition
. Default(0, 0, 0)
.requireVisible (bool) – Whether the object is required to be visible from the
ego
object. Default valueFalse
.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 valueNone
velocity (
Vector
; dynamic) – Velocity in dynamic simulations. Default value is the velocity determined byspeed
andorientation
.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.
- distanceTo(point)[source]
The minimal distance from the space this object occupies to a given point
- property visibleRegion
The visible region of this object.
The visible region of an
Object
is the same as that of anOrientedPoint
(seeOrientedPoint.visibleRegion
) except that it is offset by the value ofcameraOffset
(which is the zero vector by default).
- canSee(other, occludingObjects=(), debug=False)[source]
Whether or not this
Object
can seeother
.- Parameters:
other – A
Point
,OrientedPoint
, orObject
to check for visibility.occludingObjects – A list of objects that can occlude visibility.
- Return type:
- 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)[source]
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 thanthresholds[1][1]
and for the back surface of an object we would keep all faces that had a normal vector with y component less thanthresholds[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. IfTrue
, 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:
- class Point2D <specifiers>[source]
Bases:
Point
A 2D version of
Point
, used for backwards compatibility with Scenic 2.0- property visibleRegion
The visible region of this 2D point.
The visible region of a
Point
is a disc centered at itsposition
with radiusvisibleDistance
.
- class OrientedPoint2D <specifiers>[source]
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 itsposition
with radiusvisibleDistance
, oriented alongheading
and subtending an angle ofviewAngle
.
- class Object2D <specifiers>[source]
Bases:
OrientedPoint2D
,Object
A 2D version of
Object
, used for backwards compatibility with Scenic 2.0- property visibleRegion
The visible region of this 2D object.
The visible region of a 2D
Object
is a circular sector as forOrientedPoint
, except that the base of the sector may be offset fromposition
by thecameraOffset
property (to allow modeling cameras which are not located at the center of the object).