PolygonOfInterest#
- class movement.roi.polygon.PolygonOfInterest(exterior_boundary, holes=None, name=None)[source]#
Bases:
BaseRegionOfInterest
Representation of a two-dimensional region in the x-y plane.
This class can be used to represent polygonal regions or subregions of the area in which the experimental data was gathered. These might include the arms of a maze, a nesting area, a food source, or other similar areas of the experimental enclosure that have some significance.
An instance of this class can be used to represent these regions of interest (RoIs) in an analysis. The basic usage is to construct an instance of this class by passing in a list of points, which will then be joined (in sequence) by straight lines between consecutive pairs of points, to form the exterior boundary of the RoI. Note that the exterior boundary (accessible as via the
.exterior
property) is a (closed)LineOfInterest
, and may be treated accordingly.The class also supports holes - subregions properly contained inside the region that are not part of the region itself. These can be specified by the
holes
argument, and define the interior boundaries of the region. These interior boundaries are accessible via the.interior_boundaries
property, and the polygonal regions that make up the holes are accessible via theholes
property.Methods
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 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.
- compute_allocentric_angle_to_nearest_point(position, boundary_only=False, in_degrees=False, reference_vector=None)#
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. DefaultFalse
.in_degrees (bool) – If
True
, angles are returned in degrees. Otherwise angles are returned in radians. DefaultFalse
.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:
float
See also
compute_approach_vector
The method used to compute the approach vector.
compute_egocentric_angle_to_nearest_point
Related class method for computing the egocentric angle to the region.
movement.utils.vector.compute_signed_angle_2d
The underlying function used to compute the signed angle between the approach vector and the reference vector.
- compute_approach_vector(point, boundary_only=False, unit=False)#
Compute the approach vector from a
point
to the region.The approach vector is defined as the vector directed from the
point
provided, to the closest point that belongs to the region.- Parameters:
point (ArrayLike) – Coordinates of a point to compute the vector to (or from) the region.
boundary_only (bool) – If
True
, the approach vector to the boundary of the region is computed. DefaultFalse
.unit (bool) – If
True
, the approach vector is returned normalised, otherwise it is not normalised. Default isFalse
.
- Returns:
Approach vector from the point to the region.
- Return type:
np.ndarray
See also
compute_allocentric_angle_to_nearest_point
Relies on this method to compute the approach vector.
compute_egocentric_angle_to_nearest_point
Relies on this method to compute the approach vector.
- compute_distance_to(point, boundary_only=False)#
Compute the distance from the region to a point.
- Parameters:
point (ArrayLike) – Coordinates of a point, from which to find the nearest point in the region defined by
self
.boundary_only (bool, optional) – If
True
, compute the distance frompoint
to the boundary of the region, rather than the closest point belonging to the region. DefaultFalse
.
- Returns:
Euclidean distance from the
point
to the (closest point on the) region.- Return type:
float
- compute_egocentric_angle_to_nearest_point(direction, position, boundary_only=False, in_degrees=False)#
Compute the egocentric angle to the nearest point in the region.
With the term “egocentric”, we indicate that we are measuring angles with respect to a reference frame that is varying in time relative to the experimental/camera setup.
The egocentric angle is the signed angle between the approach vector and a
direction
vector (examples include the forward vector of a given individual, or the velocity vector of a given point).- Parameters:
direction (xarray.DataArray) – An array of vectors representing a given direction, e.g., the forward vector(s).
position (xarray.DataArray) – DataArray of spatial positions, considered the origin of the
direction
vector.boundary_only (bool) – Passed to
compute_approach_vector
(see Notes). DefaultFalse
.in_degrees (bool) – If
True
, angles are returned in degrees. Otherwise angles are returned in radians. DefaultFalse
.
- Return type:
See also
compute_allocentric_angle_to_nearest_point
Related class method for computing the egocentric angle to the region.
compute_approach_vector
The method used to compute the approach vector.
movement.utils.vector.compute_signed_angle_2d
The underlying function used to compute the signed angle between the approach vector and the reference vector.
- compute_nearest_point_to(position, boundary_only=False)#
Compute (one of) the nearest point(s) in the region to
position
.If there are multiple equidistant points, one of them is returned.
- Parameters:
position (ArrayLike) – Coordinates of a point, from which to find the nearest point in the region.
boundary_only (bool, optional) – If
True
, compute the nearest point toposition
that is on the boundary ofself
. DefaultFalse
.
- Returns:
Coordinates of the point on
self
that is closest toposition
.- Return type:
np.ndarray
- contains_point(position, include_boundary=True)#
Determine if a position is inside the region of interest.
- Parameters:
position (ArrayLike) – Spatial coordinates [x, y, [z]] to check as being inside the region.
include_boundary (bool) – Whether to treat a position on the region’s boundary as inside the region (True) or outside the region (False). Default True.
- Returns:
True if the
position
provided is within the region of interest. False otherwise.- Return type:
bool
- property coords: CoordinateSequence#
Coordinates of the points that define the region.
These are the points passed to the constructor argument
points
.Note that for Polygonal regions, these are the coordinates of the exterior boundary, interior boundaries must be accessed via
self.region.interior.coords
.
- property dimensions: int#
Dimensionality of the region.
- property exterior_boundary: LineOfInterest#
The exterior boundary of this RoI.
- property holes: tuple[PolygonOfInterest, ...]#
The interior holes of this RoI.
Holes are regions properly contained within the exterior boundary of the RoI that are not part of the RoI itself (like the centre of a doughnut, for example). A region with no holes returns the empty tuple.
- property interior_boundaries: tuple[LineOfInterest, ...]#
The interior boundaries of this RoI.
Interior boundaries are the boundaries of holes contained within the polygon. A region with no holes returns the empty tuple.
- property is_closed: bool#
Return True if the region is closed.
A closed region is either: - A polygon (2D RoI). - A 1D LoI whose final point connects back to its first.
- property name: str#
Name of the instance.
- property region: LinearRing | LineString | Polygon#
shapely.Geometry
representation of the region.