BaseRegionOfInterest#

class movement.roi.base.BaseRegionOfInterest(points, dimensions=2, closed=False, holes=None, name=None)[source]#

Bases: object

Base class for regions of interest (RoIs).

Regions of interest can be either 1 or 2 dimensional, and are represented by corresponding shapely.Geometry objects.

To avoid the complexities of subclassing shapely objects (due to them relying on __new__() methods, see shapely/shapely#1233), we simply wrap the relevant shapely object in the _shapely_geometry attribute of the class. This is accessible via the property region. This also allows us to forbid certain operations and make the manipulation of shapely objects more user friendly.

Although this class can be instantiated directly, it is not designed for this. Its primary purpose is to reduce code duplication.

Notes

A region of interest includes the points that make up its boundary and the points contained in its interior. This convention means that points inside the region will be treated as having zero distance to the region, and the approach vector from these points to the region will be the null vector.

This may be undesirable in certain situations, when we explicitly want to find the distance of a point to the boundary of a region, for example. To accommodate this, most methods of this class accept a keyword argument that forces the method to perform all computations using only the boundary of the region, rather than the region itself. For polygons, this will force the method in question to only consider distances or closest points on the segments that form the (interior and exterior) boundaries. For segments, the boundary is considered to be just the two endpoints of the segment.

Methods

`compute_allocentric_angle_to_nearest_point`(...)	Compute the allocentric angle to the nearest point in the region.
`compute_approach_vector`(point[, ...])	Compute the approach vector from a `point` to the region.
`compute_distance_to`(point[, boundary_only])	Compute the distance from the region to a point.
`compute_egocentric_angle_to_nearest_point`(...)	Compute the egocentric angle to the nearest point in the region.
`compute_nearest_point_to`(position[, ...])	Compute (one of) the nearest point(s) in the region to `position`.
`contains_point`(position[, include_boundary])	Determine if a position is inside the region of interest.
`plot`([ax])	Plot the region of interest on a new or existing axis.

compute_allocentric_angle_to_nearest_point(position, boundary_only=False, in_degrees=False, reference_vector=None)[source]#

Compute the allocentric angle to the nearest point in the region.

With the term “allocentric”, we indicate that we are measuring angles with respect to a reference frame that is fixed relative to the experimental/camera setup. By default, we assume this is the positive x-axis of the coordinate system in which position is.

The allocentric angle is the signed angle between the approach vector and a given reference vector.

Parameters:

position (xarray.DataArray) – DataArray of spatial positions.
boundary_only (bool) – If True, the allocentric angle to the closest boundary point of the region is computed. Default False.
in_degrees (bool) – If True, angles are returned in degrees. Otherwise angles are returned in radians. Default False.
reference_vector (ArrayLike | xr.DataArray) – The reference vector to be used. Dimensions must be compatible with the argument of the same name that is passed to compute_signed_angle_2d(). Default (1., 0.).

Return type:

DataArray

BaseRegionOfInterest#

This Page