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
A 

A 
Functions
Recursively convert a region into it's footprint. 



Build a 'Region' from Shapely geometry. 


Classes
Region consisting of all space. 

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

A circular region with a possiblyrandom center and radius. 





Region containing no points. 

A Region given by an obstacle grid. 



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

A region representing the surface of a mesh. 

A region representing the volume of a mesh. 

A region composed of multiple polylines in 3D space. 

Uniform distribution over points in a Region 

Region consisting of a set of discrete points. 

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

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

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

A rectangular region with a possiblyrandom position, heading, and size. 

An abstract base class for Scenic Regions 

A sector of a 

Region in the shape of a spheroid. 

A Trimesh object that always returns nonconvex. 



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



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

Member Details
 class Region(name, *dependencies, orientation=None)[source]

An abstract base class for Scenic Regions
 abstract containsPoint(point)[source]
Check if the
Region
contains a point. Implemented by subclasses. Return type:
 abstract containsRegionInner(reg, tolerance)[source]
Check if the
Region
contains aRegion
 Return type:
 abstract projectVector(point, onDirection)[source]
Returns point projected onto this region along onDirection.
 intersect(other, triedReversed=False)[source]
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:
 union(other, triedReversed=False)[source]
Get a
Region
representing the union of this one with another.Not supported by all region types.
 Return type:
 difference(other)[source]
Get a
Region
representing the difference of this one and another.Not supported by all region types.
 Return type:
 _trueContainsPoint(point)[source]
Whether or not this region could produce point when sampled.
By default this method calls
containsPoint
, but should be overwritten ifcontainsPoint
does not properly represent the points that can be sampled. Return type:
 static uniformPointIn(region, tag=None)[source]
Get a uniform
Distribution
over points in aRegion
.
 class PointInRegionDistribution(region, tag=None)[source]
Bases:
VectorDistribution
Uniform distribution over points in a Region
 class AllRegion(name, *dependencies, orientation=None)[source]
Bases:
Region
Region consisting of all space.
 class EmptyRegion(name, *dependencies, orientation=None)[source]
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.
 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)[source]
Bases:
Trimesh
A Trimesh object that always returns nonconvex.
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) –
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=1e06, centerMesh=True, onDirection=None, name=None, additionalDeps=[])[source]
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
orMeshSurfaceRegion
.The mesh is first placed so the origin is at the center of the bounding box (unless
centerMesh
isFalse
). The mesh is scaled todimensions
, translated so the center of the bounding box of the mesh is atpositon
, and then rotated torotation
.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 3tuple, 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)[source]
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)[source]
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)[source]
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. theis_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
isFalse
). The mesh is scaled todimensions
, translated so the center of the bounding box of the mesh is atpositon
, and then rotated torotation
.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 3tuple, 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)[source]
Check if this region intersects another.
This function handles intersect calculations for
MeshVolumeRegion
with: *MeshVolumeRegion
*MeshSurfaceRegion
*PolygonalFootprintRegion
 intersect(other, triedReversed=False)[source]
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)[source]
Get a
Region
representing the union of this region with another. This function handles union computation for
MeshVolumeRegion
with:
 This function handles union computation for
 difference(other, debug=False)[source]
Get a
Region
representing the difference of this region with another.This function handles union computation for
MeshVolumeRegion
with: *MeshVolumeRegion
*PolygonalFootprintRegion
 voxelized(pitch, lazy=False)[source]
Returns a VoxelRegion representing a filled voxelization of this mesh
 _erodeOverapproximate(maxErosion, pitch)[source]
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
 class MeshSurfaceRegion(*args, orientation=True, **kwargs)[source]
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
isFalse
). The mesh is scaled todimensions
, translated so the center of the bounding box of the mesh is atpositon
, and then rotated torotation
.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 3tuple, 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)[source]
Check if this region’s surface intersects another.
This function handles intersection computation for
MeshSurfaceRegion
with: *MeshSurfaceRegion
*PolygonalFootprintRegion
 getFlatOrientation(pos)[source]
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 withinself.tolerance
of the surface of the mesh, aRejectionException
is raised.
 class BoxRegion(*args, **kwargs)[source]
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 themesh
parameter which is excluded.
 class SpheroidRegion(*args, **kwargs)[source]
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 themesh
parameter which is excluded.
 class VoxelRegion(voxelGrid, orientation=None, name=None, lazy=False)[source]
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 precomputing 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)[source]
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)[source]
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
orMultiPolygon
, that defines the footprint of this region.name – An optional name to help with debugging.
 intersect(other, triedReversed=False)[source]
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)[source]
Get a
Region
representing the union of this region with another.This function handles union computation for
PolygonalFootprintRegion
with: *PolygonalFootprintRegion
 difference(other)[source]
Get a
Region
representing the difference of this region with another.This function handles difference computation for
PolygonalFootprintRegion
with: *PolygonalFootprintRegion
 containsPoint(point)[source]
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)[source]
Checks if an object is contained in the polygonal footprint.
 Parameters:
obj – An object to be checked for containment.
 class PathRegion(points=None, polylines=None, tolerance=1e08, orientation=True, name=None)[source]
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.
 class PolygonalRegion(points=(), polygon=None, z=0, orientation=None, name=None, additionalDeps=[])[source]
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 (aPolygon
orMultiPolygon
). 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 (orNone
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)[source]
Bases:
PolygonalRegion
A circular region with a possiblyrandom center and radius.
 class SectorRegion(center, radius, heading, angle, resolution=32, name=None)[source]
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)[source]
Bases:
PolygonalRegion
A rectangular region with a possiblyrandom position, heading, and size.
 class PolylineRegion(points=None, polyline=None, orientation=True, name=None)[source]
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 (aLineString
orMultiLineString
). Parameters:
points – sequence of points making up the polyline (or
None
if using the polyline argument instead).polyline –
shapely
polyline or collection of polylines (orNone
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)[source]
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:
 pointAlongBy(distance, normalized=False)[source]
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:
 class PointSetRegion(name, points, kdTree=None, orientation=None, tolerance=1e06)[source]
Bases:
Region
Region consisting of a set of discrete points.
No
Object
can be contained in aPointSetRegion
, 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) – kD tree for the points (one will be computed if none is provided)orientation (
VectorField
; optional) – preferred orientation for the regiontolerance (float; optional) – distance tolerance for checking whether a point lies in the region
 convertToFootprint(region)[source]
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)[source]
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=1e08)[source]
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.