Region Types Reference

This page covers the scenic.core.regions.Region class and its subclasses; for an introduction to the concept of regions in Scenic and the basic operations available for them, see Region.

Abstract Regions

class Region(name, *dependencies, orientation=None)

An abstract base class for Scenic Regions

intersects(other)

Check if this Region intersects another.

Return type:

bool

intersect(other, triedReversed=False)

Get a Region representing the intersection of this one with another.

If both regions have a preferred orientation, the one of self is inherited by the intersection.

Return type:

Region

union(other, triedReversed=False)

Get a Region representing the union of this one with another.

Not supported by all region types.

Return type:

Region

Point Sets and Lines

class PointSetRegion(name, points, kdTree=None, orientation=None, tolerance=1e-06)

Region consisting of a set of discrete points.

No Object can be contained in a PointSetRegion, since the latter is discrete. (This may not be true for subclasses, e.g. GridRegion.)

Parameters:

• name (str) – name for debugging

• points (arraylike) – set of points comprising the region

• kdTree (scipy.spatial.KDTree, optional) – k-D tree for the points (one will be computed if none is provided)

• orientation (Vector Field; optional) – preferred orientation for the region

• tolerance (float; optional) – distance tolerance for checking whether a point lies in the region

class PolylineRegion(points=None, polyline=None, orientation=True, name=None)

Region given by one or more polylines (chain of line segments).

The region may be specified by giving either a sequence of points or shapely polylines (a LineString or MultiLineString).

Parameters:

• points – sequence of points making up the polyline (or None if using the polyline argument instead).

• polyline – shapely polyline or collection of polylines (or None if using the points argument instead).

• orientation (optional) – preferred orientation to use, or True to use an orientation aligned with the direction of the polyline (the default).

• name (str; optional) – name for debugging.

property start

Get an OrientedPoint at the start of the polyline.

The OP’s orientation will be aligned with the orientation of the region, if there is one (the default orientation pointing along the polyline).

property end

Get an OrientedPoint at the end of the polyline.

The OP’s orientation will be aligned with the orientation of the region, if there is one (the default orientation pointing along the polyline).

signedDistanceTo(point)

Compute the signed distance of the PolylineRegion to a point.

The distance is positive if the point is left of the nearest segment, and negative otherwise.

Return type:

float

pointAlongBy(distance, normalized=False)

Find the point a given distance along the polyline from its start.

If normalized is true, then distance should be between 0 and 1, and is interpreted as a fraction of the length of the polyline. So for example pointAlongBy(0.5, normalized=True) returns the polyline’s midpoint.

Return type:

Vector

__getitem__(i)

Get the ith point along this polyline.

If the region consists of multiple polylines, this order is linear along each polyline but arbitrary across different polylines.

Return type:

Vector

__len__()

Get the number of vertices of the polyline.

Return type:

int

class PathRegion(points=None, polylines=None, tolerance=1e-08, orientation=True, name=None)

A region composed of multiple polylines in 3D space.

One of points or polylines should be provided.

Parameters:

• points – A list of points defining a single polyline.

• polylines – A list of list of points, defining multiple polylines.

• orientation (optional) – preferred orientation to use, or True to use an orientation aligned with the direction of the path (the default).

• tolerance – Tolerance used internally.

2D Regions

2D regions represent a 2D shape parallel to the XY plane, at a certain elevation in space. All 2D regions inherit from PolygonalRegion.

Unlike the more PolygonalRegion, the simple geometric shapes are allowed to depend on random values: for example, the visible region of an Object is a SectorRegion based at the object’s position, which might not be fixed.

Since 2D regions cannot contain an Object (which must be 3D), they define a footprint for convenience. Footprints are always a PolygonalFootprintRegion, which represents a 2D polygon extruded infinitely in the positive and negative vertical direction. When checking containment of an Object in a 2D region, Scenic will atuomatically use the footprint.

class PolygonalRegion(points=None, polygon=None, z=0, orientation=None, name=None, additionalDeps=[])

Region given by one or more polygons (possibly with holes) at a fixed z coordinate.

The region may be specified by giving either a sequence of points defining the boundary of the polygon, or a collection of shapely polygons (a Polygon or MultiPolygon).

Parameters:

• points – sequence of points making up the boundary of the polygon (or None if using the polygon argument instead).

• polygon – shapely polygon or collection of polygons (or None if using the points argument instead).

• z – The z coordinate the polygon is located at.

• orientation (Vector Field; optional) – preferred orientation to use.

• name (str; optional) – name for debugging.

property boundary: PolylineRegion

Get the boundary of this region as a PolylineRegion.

class CircularRegion(center, radius, resolution=32, name=None)

A circular region with a possibly-random center and radius.

Parameters:

• center (Vector) – center of the disc.

• radius (float) – radius of the disc.

• resolution (int; optional) – number of vertices to use when approximating this region as a polygon.

• name (str; optional) – name for debugging.

class SectorRegion(center, radius, heading, angle, resolution=32, name=None)

A sector of a CircularRegion.

This region consists of a sector of a disc, i.e. the part of a disc subtended by a given arc.

Parameters:

• center (Vector) – center of the corresponding disc.

• radius (float) – radius of the disc.

• heading (float) – heading of the centerline of the sector.

• angle (float) – angle subtended by the sector.

• resolution (int; optional) – number of vertices to use when approximating this region as a polygon.

• name (str; optional) – name for debugging.

class RectangularRegion(position, heading, width, length, name=None)

A rectangular region with a possibly-random position, heading, and size.

Parameters:

• position (Vector) – center of the rectangle.

• heading (float) – the heading of the length axis of the rectangle.

• width (float) – width of the rectangle.

• length (float) – length of the rectangle.

• name (str; optional) – name for debugging.

3D Regions

3D regions represent points in 3D space.

Most 3D regions inherit from either MeshVolumeRegion or MeshSurfaceRegion, which represent the volume (of a watertight mesh) and the surface of a mesh respectively. Various region classes are also provided to create primitive shapes. MeshVolumeRegion can be converted to MeshSurfaceRegion (and vice versa) using the the getSurfaceRegion and getVolumeRegion methods.

PolygonalFootprintRegions represent the footprint of a 2D region. See 2D Regions for more details.

class MeshVolumeRegion(*args, **kwargs)

Bases: MeshRegion

A region representing the volume of a mesh.

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.

The mesh is first placed so the origin is at the center of the bounding box (unless centerMesh is False). The mesh is scaled to dimensions, translated so the center of the bounding box of the mesh is at positon, and then rotated to rotation.

Meshes are centered by default (since centerMesh is true by default). If you disable this operation, do note that scaling and rotation transformations may not behave as expected, since they are performed around the origin.

Parameters:

• mesh – The base mesh for this region.

• name – An optional name to help with debugging.

• dimensions – An optional 3-tuple, with the values representing width, length, height respectively. The mesh will be scaled such that the bounding box for the mesh has these dimensions.

• position – An optional position, which determines where the center of the region will be.

• rotation – An optional Orientation object which determines the rotation of the object in space.

• orientation – An optional vector field describing the preferred orientation at every point in the region.

• tolerance – Tolerance for internal computations.

• centerMesh – Whether or not to center the mesh after copying and before transformations.

• onDirection – The direction to use if an object being placed on this region doesn’t specify one.

getSurfaceRegion()

Return a region equivalent to this one, except as a MeshSurfaceRegion

classmethod fromFile(path, unify=True, **kwargs)

Load a mesh region 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 MeshRegion initializer.

class MeshSurfaceRegion(*args, orientation=True, **kwargs)

Bases: MeshRegion

A region representing the surface of a mesh.

The mesh is first placed so the origin is at the center of the bounding box (unless centerMesh is False). The mesh is scaled to dimensions, translated so the center of the bounding box of the mesh is at positon, and then rotated to rotation.

Meshes are centered by default (since centerMesh is true by default). If you disable this operation, do note that scaling and rotation transformations may not behave as expected, since they are performed around the origin.

If an orientation is not passed to this mesh, a default orientation is provided which provides an orientation that aligns an object’s z axis with the normal vector of the face containing that point, and has a yaw aligned with a yaw of 0 in the global coordinate system.

Parameters:

• mesh – The base mesh for this region.

• name – An optional name to help with debugging.

• dimensions – An optional 3-tuple, with the values representing width, length, height respectively. The mesh will be scaled such that the bounding box for the mesh has these dimensions.

• position – An optional position, which determines where the center of the region will be.

• rotation – An optional Orientation object which determines the rotation of the object in space.

• orientation – An optional vector field describing the preferred orientation at every point in the region.

• tolerance – Tolerance for internal computations.

• centerMesh – Whether or not to center the mesh after copying and before transformations.

• onDirection – The direction to use if an object being placed on this region doesn’t specify one.

getVolumeRegion()

Return a region equivalent to this one, except as a MeshVolumeRegion

classmethod fromFile(path, unify=True, **kwargs)

Load a mesh region 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 MeshRegion initializer.

class BoxRegion(*args, **kwargs)

Region in the shape of a rectangular cuboid, i.e. a box.

By default the unit box centered at the origin and aligned with the axes is used.

Parameters are the same as MeshVolumeRegion, with the exception of the mesh parameter which is excluded.

class SpheroidRegion(*args, **kwargs)

Region in the shape of a spheroid.

By default the unit sphere centered at the origin and aligned with the axes is used.

Parameters are the same as MeshVolumeRegion, with the exception of the mesh parameter which is excluded.

class PolygonalFootprintRegion(polygon, name=None)

Region that contains all points in a polygonal footprint, regardless of their z value.

This region cannot be sampled from, as it has infinite height and therefore infinite volume.

Parameters:

• polygon – A shapely Polygon or MultiPolygon, that defines the footprint of this region.

• name – An optional name to help with debugging.

Niche Regions

class GridRegion(name, grid, Ax, Ay, Bx, By, orientation=None)

Bases: PointSetRegion

A Region given by an obstacle grid.

A point is considered to be in a GridRegion if the nearest grid point is not an obstacle.

Parameters:

• name (str) – name for debugging

• grid – 2D list, tuple, or NumPy array of 0s and 1s, where 1 indicates an obstacle and 0 indicates free space

• Ax (float) – spacing between grid points along X axis

• Ay (float) – spacing between grid points along Y axis

• Bx (float) – X coordinate of leftmost grid column

• By (float) – Y coordinate of lowest grid row

• orientation (Vector Field; optional) – orientation of region