scenic.core.regions

Objects representing regions in space.

Manipulations of polygons and line segments are done using the shapely package.

Manipulations of meshes is done using the trimesh package.

Summary of Module Members

Module Attributes

everywhere	A Region containing all points.
nowhere	A Region containing no points.

Functions

convertToFootprint	Recursively convert a region into it's footprint.
orientationFor
regionFromShapelyObject	Build a 'Region' from Shapely geometry.
toPolygon

Classes

AllRegion	Region consisting of all space.
BoxRegion	Region in the shape of a rectangular cuboid, i.e. a box.
CircularRegion	A circular region with a possibly-random center and radius.
CylinderSectionRegion
DifferenceRegion
EmptyRegion	Region containing no points.
GridRegion	A Region given by an obstacle grid.
IntersectionRegion
MeshRegion	Region given by a scaled, positioned, and rotated mesh.
MeshSurfaceRegion	A region representing the surface of a mesh.
MeshVolumeRegion	A region representing the volume of a mesh.
PathRegion	A region composed of multiple polylines in 3D space.
PointInRegionDistribution	Uniform distribution over points in a Region
PointSetRegion	Region consisting of a set of discrete points.
PolygonalFootprintRegion	Region that contains all points in a polygonal footprint, regardless of their z value.
PolygonalRegion	Region given by one or more polygons (possibly with holes) at a fixed z coordinate.
PolylineRegion	Region given by one or more polylines (chain of line segments).
RectangularRegion	A rectangular region with a possibly-random position, heading, and size.
Region	An abstract base class for Scenic Regions
SectorRegion	A sector of a CircularRegion.
SpheroidRegion	Region in the shape of a spheroid.
SurfaceCollisionTrimesh	A Trimesh object that always returns non-convex.
UnionRegion
ViewRegion	The viewing volume of a camera defined by a radius and horizontal/vertical view angles.
ViewSectionRegion
VoxelRegion	(WIP) Region represented by a voxel grid in 3D space.

Exceptions

UndefinedSamplingException

Member Details

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

Bases: Samplable, ABC

An abstract base class for Scenic Regions

abstract uniformPointInner()

Do the actual random sampling. Implemented by subclasses.

abstract containsPoint(point)

Check if the Region contains a point. Implemented by subclasses.

Return type:

bool

abstract containsObject(obj)

Check if the Region contains an Object

Return type:

bool

abstract containsRegionInner(reg, tolerance)

Check if the Region contains a Region

Return type:

bool

abstract distanceTo(point)

Distance to this region from a given point.

Return type:

float

abstract projectVector(point, onDirection)

Returns point projected onto this region along onDirection.

abstract property AABB

Axis-aligned bounding box for this Region.

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

difference(other)

Get a Region representing the difference of this one and another.

Not supported by all region types.

Return type:

Region

_trueContainsPoint(point)

Whether or not this region could produce point when sampled.

By default this method calls containsPoint, but should be overwritten if containsPoint does not properly represent the points that can be sampled.

Return type:

bool

static uniformPointIn(region, tag=None)

Get a uniform Distribution over points in a Region.

orient(vec)

Orient the given vector along the region’s orientation, if any.

class PointInRegionDistribution(region, tag=None)

Bases: VectorDistribution

Uniform distribution over points in a Region

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

Bases: Region

Region consisting of all space.

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

Bases: Region

Region containing no points.

everywhere = <AllRegion everywhere>

A Region containing all points.

Points may not be sampled from this region, as no uniform distribution over it exists.

nowhere = <EmptyRegion nowhere>

A Region containing no points.

Attempting to sample from this region causes the sample to be rejected.

regionFromShapelyObject(obj, orientation=None)

Build a ‘Region’ from Shapely geometry.

class SurfaceCollisionTrimesh(vertices=None, faces=None, face_normals=None, vertex_normals=None, face_colors=None, vertex_colors=None, face_attributes=None, vertex_attributes=None, metadata=None, process=True, validate=False, merge_tex=None, merge_norm=None, use_embree=True, initial_cache=None, visual=None, **kwargs)

Bases: Trimesh

A Trimesh object that always returns non-convex.

Used so that fcl doesn’t find collision without an actual surface intersection.

Parameters:

• vertices (Optional[Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) –

• faces (Optional[Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) –

• face_normals (Optional[Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) –

• vertex_normals (Optional[Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) –

• face_colors (Optional[Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) –

• vertex_colors (Optional[Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) –

• face_attributes (Optional[dict[str, Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]) –

• vertex_attributes (Optional[dict[str, Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]) –

• metadata (dict) –

• process (bool) –

• validate (bool) –

• merge_tex (Optional[bool]) –

• merge_norm (Optional[bool]) –

• use_embree (bool) –

• initial_cache (Optional[dict[str, numpy.ndarray]]) –

• visual (Optional[Union[ColorVisuals, TextureVisuals]]) –

class MeshRegion(mesh, dimensions=None, position=None, rotation=None, orientation=None, tolerance=1e-06, centerMesh=True, onDirection=None, name=None, additionalDeps=[])

Bases: Region

Region given by a scaled, positioned, and rotated mesh.

This is an abstract class and cannot be instantiated directly. Instead a subclass should be used, like MeshVolumeRegion or MeshSurfaceRegion.

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

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

• additionalDeps – Any additional sampling dependencies this region relies on.

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.

projectVector(point, onDirection)

Find the nearest point in the region following the onDirection or its negation.

Returns None if no such points exist.

property circumcircle

Compute an upper bound on the radius of the region

property boundingPolygon

A PolygonalRegion bounding the mesh

class MeshVolumeRegion(*args, _internal=False, _isConvex=None, **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.

intersects(other, triedReversed=False)

Check if this region intersects another.

This function handles intersect calculations for MeshVolumeRegion with: * MeshVolumeRegion * MeshSurfaceRegion * PolygonalFootprintRegion

containsPoint(point)

Check if this region’s volume contains a point.

containsObject(obj)

Check if this region’s volume contains an Object.

intersect(other, triedReversed=False)

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

This function handles intersection computation for MeshVolumeRegion with: * MeshVolumeRegion * PolygonalFootprintRegion * PolygonalRegion * PathRegion * PolylineRegion

union(other, triedReversed=False)

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

This function handles union computation for MeshVolumeRegion with:

• MeshVolumeRegion

difference(other, debug=False)

Get a Region representing the difference of this region with another.

This function handles union computation for MeshVolumeRegion with: * MeshVolumeRegion * PolygonalFootprintRegion

distanceTo(point)

Get the minimum distance from this region to the specified point.

voxelized(pitch, lazy=False)

Returns a VoxelRegion representing a filled voxelization of this mesh

_erodeOverapproximate(maxErosion, pitch)

Compute an overapproximation of this region eroded.

Erode as much as possible, but no more than maxErosion, outputting a VoxelRegion. Note that this can sometimes return a larger region than the original mesh

_bufferOverapproximate(minBuffer, pitch)

Compute an overapproximation of this region buffered.

Buffer as little as possible, but at least minBuffer. If pitch is less than 1, the output is a VoxelRegion. If pitch is 1, a fast path is taken which returns a BoxRegion.

getSurfaceRegion()

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

getVolumeRegion()

Returns this object, as it is already a MeshVolumeRegion

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.

intersects(other, triedReversed=False)

Check if this region’s surface intersects another.

This function handles intersection computation for MeshSurfaceRegion with: * MeshSurfaceRegion * PolygonalFootprintRegion

containsPoint(point)

Check if this region’s surface contains a point.

distanceTo(point)

Get the minimum distance from this object to the specified point.

getFlatOrientation(pos)

Get a flat orientation at a point in the region.

Given a point on the surface of the mesh, returns an orientation that aligns an instance’s z axis with the normal vector of the face containing that point. Since there are infinitely many such orientations, the orientation returned has yaw aligned with a global yaw of 0.

If pos is not within self.tolerance of the surface of the mesh, a RejectionException is raised.

getVolumeRegion()

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

getSurfaceRegion()

Returns this object, as it is already a MeshSurfaceRegion

class BoxRegion(*args, **kwargs)

Bases: MeshVolumeRegion

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)

Bases: MeshVolumeRegion

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 VoxelRegion(voxelGrid, orientation=None, name=None, lazy=False)

Bases: Region

(WIP) Region represented by a voxel grid in 3D space.

NOTE: This region is a work in progress and is currently only recommended for internal use.

Parameters:

• voxelGrid – The Trimesh voxelGrid to be used.

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

• name – An optional name to help with debugging.

• lazy – Whether or not to be lazy about pre-computing internal values. Set this to True if this VoxelRegion is unlikely to be used outside of an intermediate step in compiling/pruning.

dilation(iterations, structure=None)

Returns a dilated/eroded version of this VoxelRegion.

Parameters:

• iterations – How many times repeat the dilation/erosion. A positive number indicates a dilation and a negative number indicates an erosion.

• structure – The structure to use. If none is provided, a rank 3 structuring unit with connectivity 3 is used.

property mesh

(WIP) Return a MeshVolumeRegion representation of this region.

NOTE: This region is a WIP and will sometimes return None if the transformation is not feasible.

class PolygonalFootprintRegion(polygon, name=None)

Bases: Region

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.

intersect(other, triedReversed=False)

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

This function handles intersection computation for PolygonalFootprintRegion with: * PolygonalFootprintRegion * PolygonalRegion

union(other, triedReversed=False)

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

This function handles union computation for PolygonalFootprintRegion with: * PolygonalFootprintRegion

difference(other)

Get a Region representing the difference of this region with another.

This function handles difference computation for PolygonalFootprintRegion with: * PolygonalFootprintRegion

containsPoint(point)

Checks if a point is contained in the polygonal footprint.

Equivalent to checking if the (x, y) values are contained in the polygon.

Parameters:

point – A point to be checked for containment.

containsObject(obj)

Checks if an object is contained in the polygonal footprint.

Parameters:

obj – An object to be checked for containment.

distanceTo(point)

Minimum distance from this polygonal footprint to the target point

approxBoundFootprint(centerZ, height)

Returns an overapproximation of boundFootprint

Returns a volume that is guaranteed to contain the result of boundFootprint(centerZ, height), but may be taller. Used to save time on recomputing boundFootprint.

boundFootprint(centerZ, height)

Cap the footprint of the object to a given height, centered at a given z.

Parameters:

• centerZ – The resulting mesh will be vertically centered at this height.

• height – The resulting mesh will have this height.

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

Bases: Region

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.

_segmentDistanceHelper(point)

Returns distance to point from each line segment

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

Bases: Region

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 (VectorField; 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)

Bases: PolygonalRegion

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)

Bases: PolygonalRegion

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)

Bases: PolygonalRegion

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.

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

Bases: Region

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

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

Bases: Region

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 (VectorField; optional) – preferred orientation for the region

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

convertToFootprint(region)

Recursively convert a region into it’s footprint.

For a polygonal region, returns the footprint. For composed regions, recursively reconstructs them using the footprints of their sub 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 (VectorField; optional) – orientation of region

class ViewRegion(visibleDistance, viewAngles, name=None, position=Vector(0, 0, 0), rotation=None, angleCutoff=0.017, tolerance=1e-08)

Bases: MeshVolumeRegion

The viewing volume of a camera defined by a radius and horizontal/vertical view angles.

The default view region can take several forms, depending on the viewAngles parameter:

• Case 1: viewAngles[1] = 180 degrees

  • Case 1.a viewAngles[0] = 360 degrees => Sphere

  • Case 1.b viewAngles[0] < 360 degrees => Sphere & CylinderSectionRegion

• Case 2: viewAngles[1] < 180 degrees => Sphere & ViewSectionRegion

When making changes to this class you should run pytest -k test_viewRegion --exhaustive.

Parameters:

• visibleDistance – The view distance for this region.

• viewAngles – The view angles for this region.

• name – An optional name to help with debugging.

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

• angleCutoff – How close to 180/360 degrees an angle has to be to be mapped to that value.

• tolerance – Tolerance for collision computations.