Data Types Reference

This page describes the primitive data types built into Scenic. In addition to these types, Scenic provides a class hierarchy for points, oriented points, and objects: see the Objects and Classes Reference.

Boolean

Booleans represent truth values, and can be True or False.

Note

These are equivalent to the Python bool type.

Scalar

Scalars represent distances, angles, etc. as floating-point numbers, which can be sampled from various distributions.

Note

These are equivalent to the Python float type; however, any context which accepts a scalar will also allow an int or a NumPy numeric type such as numpy.single (to be precise, any instance of numbers.Real is legal).

Vector

Vectors represent positions and offsets in space. They are constructed from coordinates using a length-3 list or tuple ([X, Y, Z] or (X, Y, Z). Alternatively, they can be constructed with the syntax X @ Y (inspired by Smalltalk) or a length-2 list or tuple, with an implied z value of 0. By convention, coordinates are in meters, although the semantics of Scenic does not depend on this.

For convenience, instances of Point can be used in any context where a vector is expected: so for example if P is a Point, then P offset by (1, 2) is equivalent to P.position offset by (1, 2).

Changed in version 3.0: Vectors are now 3 dimensional.

Heading

Headings represent yaw in the global XY plane. Scenic represents headings in radians, measured anticlockwise from North, so that a heading of 0 is due North and a heading of π/2 is due West. We use the convention that the heading of a local coordinate system is the heading of its Y-axis, so that, for example, the vector -2 @ 3 means 2 meters left and 3 ahead.

For convenience, instances of OrientedPoint can be used in any context where a heading is expected: so for example if OP is an OrientedPoint, then relative heading of OP is equivalent to relative heading of OP.heading. Since OrientedPoint is a subclass of Point, expressions involving two oriented points like OP1 relative to OP2 can be ambiguous: the polymorphic operator relative to accepts both vectors and headings, and either version could be meant here. Scenic rejects such expressions as being ambiguous: more explicit syntax like OP1.position relative to OP2 must be used instead.

Orientation

Orientations represent orientations in 3D space. Scenic represents orientations internally using quaternions, though for convenience they can be created using Euler angles. Scenic follows the right hand rule with the Z,X,Y order of rotations. In other words, Euler angles are given as (Yaw, Pitch, Roll), in radians, and applied in that order. To help visualize, one can consider their right hand with fingers extended orthogonally. The index finger points along positive X, the middle finger bends left along positive Y, and the thumb ends up pointing along positive Z. For rotations, align your right thumb with a positive axis and the way your fingers curl is a positive rotation.

New in version 3.0.

Vector Field

Vector fields associate an orientation to each point in space. For example, a vector field could represent the shortest paths to a destination, or the nominal traffic direction on a road (e.g. scenic.domains.driving.model.roadDirection).

Changed in version 3.0: Vector fields now return an Orientation instead of a scalar heading.

Region

Regions represent sets of points in space. Scenic provides a variety of ways to define regions in 2D and 3D space: meshes, rectangles, circular sectors, line segments, polygons, occupancy grids, and explicit lists of points, among others.

Regions can have an associated vector field giving points in the region preferred orientations. For example, a region representing a lane of traffic could have a preferred orientation aligned with the lane, so that we can easily talk about distances along the lane, even if it curves. Another possible use of preferred orientations is to give the surface of an object normal vectors, so that other objects placed on the surface face outward by default.

The main operations available for use with all regions are:

the (vector | Object) in region operator to test containment within a region;
the visible region operator to get the part of a region which is visible from the ego;
the in region specifier to choose a position uniformly at random inside a region;
the on region specifier to choose a position like in region or to project an existing position onto the region’s surface.

If you need to perform more complex operations on regions, or are writing a world model and need to define your own regions, you will have to work with the Region class (which regions are instances of) and its subclasses for particular types of regions. These are listed in the Regions Types reference. If you are working on Scenic’s internals, see the scenic.core.regions module for full details.

Shape

Shapes represent the shape of an object, i.e., the volume it occupies modulo translation, rotation, and scaling. Shapes are represented by meshes, automatically converted to unit size and centered; Scenic considers the side of the shape facing the positive Y axis to be its front.

Shapes can be created from an arbitrary mesh or using one of the geometric primitives below. For convenience, a shape created with specified dimensions will set the default dimensions for any Object created with that shape. When creating a MeshShape, if no dimensions are provided then dimensions will be inferred from the mesh. MeshShape also takes an optional initial_rotation parameter, which allows directions other than the positive Y axis to be considered the front of the shape.

class MeshShape(mesh, dimensions=None, scale=1, initial_rotation=None)[source]

A Shape subclass defined by a trimesh.base.Trimesh object.

The mesh passed must be a trimesh.base.Trimesh object that represents a well defined volume (i.e. the is_volume property must be true), meaning the mesh must be watertight, have consistent winding and have outward facing normals.

Parameters:

mesh – A mesh object.
dimensions – The raw (before scaling) dimensions of the shape. If dimensions and scale are both specified the dimensions are first set by dimensions, and then scaled by scale.
scale – Scales all the dimensions of the shape by a multiplicative factor. If dimensions and scale are both specified the dimensions are first set by dimensions, and then scaled by scale.
initial_rotation – A 3-tuple containing the yaw, pitch, and roll respectively to apply when loading the mesh. Note the initial_rotation must be fixed.

classmethod fromFile(path, unify=True, **kwargs)[source]

Load a mesh shape from a file, attempting to infer filetype and compression.

For example: “foo.obj.bz2” is assumed to be a compressed .obj file. “foo.obj” is assumed to be an uncompressed .obj file. “foo” is an unknown filetype, so unless a filetype is provided an exception will be raised.

Parameters:

path (str) – Path to the file to import.
filetype (str) – Filetype of file to be imported. This will be inferred if not provided. The filetype must be one compatible with trimesh.load.
compressed (bool) – Whether or not this file is compressed (with bz2). This will be inferred if not provided.
binary (bool) – Whether or not to open the file as a binary file.
unify (bool) – Whether or not to attempt to unify this mesh.
kwargs – Additional arguments to the MeshShape initializer.

class BoxShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None)[source]: A box shape with all dimensions 1 by default.

class CylinderShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None, sections=24)[source]: A cylinder shape with all dimensions 1 by default.

class ConeShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None)[source]: A cone shape with all dimensions 1 by default.

class SpheroidShape(dimensions=(1, 1, 1), scale=1, initial_rotation=None)[source]: A spheroid shape with all dimensions 1 by default.