Regions
3-D region definitions for POVME inclusion, exclusion, and seed volumes.
This module defines the abstract Region base class and two concrete
implementations, SphericalRegion and
RectangularRegion,
that generate regular grids of 3D points filling a geometric volume. These
regions are used throughout POVME to specify:
- Inclusion regions: the volume to search for pockets.
- Exclusion regions: sub-volumes to explicitly ignore.
- Contiguous-pocket seed regions: small volumes placed inside the pocket of interest so that only the contiguous pocket is retained.
RectangularRegion(center, lengths)
¶
Bases: Region
A 3D rectangular region defined by its center and dimensions.
This class represents a rectangular box in 3D space, capable of generating a grid of points that fill the box.
Initialize a rectangular region.
| PARAMETER | DESCRIPTION |
|---|---|
|
The x, y, and z coordinates of the center of the box.
TYPE:
|
|
The lengths of the box along the x, y, and z axes.
TYPE:
|
center = np.array(center)
¶
A list of three floats representing the x, y, and z coordinates of the box's center, in Angstroms.
lengths = np.array(lengths)
¶
A list of three floats representing the lengths of the box along the x, y, and z axes, in Angstroms.
__str__()
¶
Returns a string representation of the rectangular region.
get_points(res)
¶
Generates a grid of points filling the rectangular region.
| PARAMETER | DESCRIPTION |
|---|---|
|
The resolution of the grid, defining the spacing between points.
|
| RETURNS | DESCRIPTION |
|---|---|
|
A numpy array of shape (n, 3), where each row is a [x, y, z] |
|
|
coordinate representing a point within the rectangular region. |
Region()
¶
Bases: ABC
Abstract base class representing a 3D region.
This class provides a blueprint for defining specific types of 3D regions. Subclasses must implement methods to provide a string representation of the region and to generate a grid of points filling the region.
__str__()
¶
Returns a string representation of the region.
get_points(res)
¶
Generates a grid of equally spaced points filling the region.
| PARAMETER | DESCRIPTION |
|---|---|
|
The resolution of the grid, defining the spacing between points.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
NDArray[float64]
|
A numpy array of shape (n, 3), where each row is a [x, y, z] |
NDArray[float64]
|
coordinate representing a point in the region. |
SphericalRegion(center, radius)
¶
Bases: Region
A 3D spherical region defined by a center and a radius.
This class represents a sphere in 3D space, capable of generating a grid of points that fill the sphere. Points outside the sphere boundary are excluded.
Initialize a spherical region.
| PARAMETER | DESCRIPTION |
|---|---|
|
The x, y, and z coordinates of the center of the sphere.
TYPE:
|
|
The radius of the sphere in Angstroms.
TYPE:
|
center = np.array(center)
¶
x, y, and z coordinates in Angstroms of the center.
radius = radius
¶
Sphere radius in Angstroms.
__str__()
¶
Returns a string representation of the spherical region.
get_points(res)
¶
Generate grid points filling the sphere.
A cubic grid spanning [center - radius, center + radius] is
constructed along each axis, then points outside the sphere are
removed using a vectorized Euclidean-norm test.
| PARAMETER | DESCRIPTION |
|---|---|
|
The grid spacing (Å).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
NDArray[float64]
|
An |
build_mesh_grid(xs, ys, zs, res)
¶
Creates a 3D grid of points using given x, y, and z coordinate vectors.
This function generates all possible combinations of xs, ys, and zs to create
a rectangular 3D grid, then snaps the resulting points to the nearest fixed grid
using the specified resolution.
| PARAMETER | DESCRIPTION |
|---|---|
|
A 1D numpy array representing the x-coordinates of the grid.
TYPE:
|
|
A 1D numpy array representing the y-coordinates of the grid.
TYPE:
|
|
A 1D numpy array representing the z-coordinates of the grid.
TYPE:
|
|
The resolution of the final snapped grid.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
NDArray[float64]
|
A 2D numpy array of shape (n, 3), where each row is a point on the |
NDArray[float64]
|
3D grid after snapping to the fixed resolution. |
collect_regions(spherical_configs, rectangular_configs)
¶
Creates a collection of 3D regions from spherical and rectangular configurations.
This function takes configurations for spherical and rectangular regions, instantiates the respective region objects, and returns a combined list of these regions. Empty or invalid configurations are skipped.
| PARAMETER | DESCRIPTION |
|---|---|
|
A list of dictionaries, each specifying a spherical region. Each dictionary must have:
If
TYPE:
|
|
A list of dictionaries, each specifying a rectangular region. Each dictionary must have:
If
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[SphericalRegion | RectangularRegion]
|
A list containing |
Example
>>> spherical_configs = [
... {"center": [0.0, 0.0, 0.0], "radius": 5.0},
... {"center": [10.0, 10.0, 10.0], "radius": 3.0},
... ]
>>> rectangular_configs = [
... {"center": [0.0, 0.0, 0.0], "lengths": [10.0, 5.0, 2.0]}
... ]
>>> regions = collect_regions(spherical_configs, rectangular_configs)
>>> for region in regions:
... print(region)
sphere at (0.0, 0.0, 0.0), radius = 5.0
sphere at (10.0, 10.0, 10.0), radius = 3.0
box centered at (0.0, 0.0, 0.0) with dimensions (10.0, 5.0, 2.0)
snap_points(points, res)
¶
Aligns a set of 3D points to the nearest points on a uniform grid.
This function "snaps" each point to the nearest grid point based on a specified grid resolution. It is useful for discretizing continuous 3D coordinates into a fixed grid.
| PARAMETER | DESCRIPTION |
|---|---|
|
A numpy array of shape (n, 3), where
TYPE:
|
|
The resolution of the grid, defining the distance between adjacent grid points.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
NDArray[float64]
|
A numpy array of the same shape as |
NDArray[float64]
|
adjusted to lie on the nearest grid point defined by |