acoular 25.10__py3-none-any.whl → 26.1__py3-none-any.whl

acoular/tbeamform.py

@@ -83,19 +83,19 @@ class BeamformerTime(TimeOut):
     #: Data source; :class:`~acoular.base.SamplesGenerator` or derived object.
     source = Instance(SamplesGenerator)
 
-    # Instance of :class:`~acoular.fbeamform.SteeringVector` or its derived classes
-    # that contains information about the steering vector. This is a private trait.
-    # Do not set this directly, use `steer` trait instead.
+    #: Instance of :class:`~acoular.fbeamform.SteeringVector` or its derived classes
+    #: that contains information about the steering vector. This is a private trait.
+    #: Do not set this directly, use :attr:`steer` trait instead.
     steer = Instance(SteeringVector, args=())
 
     #: Number of channels in output (=number of grid points).
     num_channels = Property()
 
     #: Spatial weighting function.
-    weights = Map(possible_weights, default_value='none', desc='spatial weighting function')
+    weights = Map(possible_weights, default_value='none')
     # (from timedomain.possible_weights)
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=['steer.digest', 'source.digest', 'weights'],
     )
@@ -231,9 +231,9 @@ class BeamformerTimeSq(BeamformerTime):
     """
 
     #: Boolean flag, if 'True' (default), the main diagonal is removed before beamforming.
-    r_diag = Bool(True, desc='removal of diagonal')
+    r_diag = Bool(True)
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=['steer.digest', 'source.digest', 'r_diag', 'weights'],
     )
@@ -275,18 +275,18 @@ class BeamformerTimeTraj(BeamformerTime):
 
     #: :class:`~acoular.trajectory.Trajectory` or derived object.
     #: Start time is assumed to be the same as for the samples.
-    trajectory = Instance(Trajectory, desc='trajectory of the grid center')
+    trajectory = Instance(Trajectory)
 
     #: Reference vector, perpendicular to the y-axis of moving grid.
-    rvec = CArray(dtype=float, shape=(3,), value=np.array((0, 0, 0)), desc='reference vector')
+    rvec = CArray(dtype=float, shape=(3,), value=np.array((0, 0, 0)))
 
     #: Considering of convective amplification in beamforming formula.
-    conv_amp = Bool(False, desc='determines if convective amplification of source is considered')
+    conv_amp = Bool(False)
 
     #: Floating point and integer precision
-    precision = Enum(64, 32, desc='numeric precision')
+    precision = Enum(64, 32)
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=[
             'steer.digest',
@@ -325,7 +325,7 @@ class BeamformerTimeTraj(BeamformerTime):
                 tpos = gpos + np.array(g)[:, np.newaxis]
                 yield tpos
         else:
-            for g, g1 in zip(trajg, trajg1):
+            for g, g1 in zip(trajg, trajg1, strict=True):
                 # grid is both translated and rotated
                 loc = np.array(g)  # translation array([0., 0.4, 1.])
                 dx = np.array(g1)  # direction vector (new x-axis)
@@ -520,7 +520,7 @@ class BeamformerTimeSqTraj(BeamformerTimeSq, BeamformerTimeTraj):
     removal for a grid moving along a trajectory.
     """
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=[
             'steer.digest',
@@ -571,16 +571,16 @@ class BeamformerCleant(BeamformerTime):
     """
 
     #: Boolean flag, always False
-    r_diag = Enum(False, desc='False, as we do not remove autopower in this beamformer')
+    r_diag = Enum(False)
 
     #: iteration damping factor also referred as loop gain in Cousson et al.
     #: defaults to 0.6
-    damp = Range(0.01, 1.0, 0.6, desc='damping factor (loop gain)')
+    damp = Range(0.01, 1.0, 0.6)
 
     #: max number of iterations
-    n_iter = Int(100, desc='maximum number of iterations')
+    n_iter = Int(100)
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=['steer.digest', 'source.digest', 'weights', 'damp', 'n_iter'],
     )
@@ -623,9 +623,9 @@ class BeamformerCleantSq(BeamformerCleant):
     """
 
     #: Boolean flag, if 'True' (default), the main diagonal is removed before beamforming.
-    r_diag = Bool(True, desc='removal of diagonal')
+    r_diag = Bool(True)
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=['steer.digest', 'source.digest', 'weights', 'damp', 'n_iter', 'r_diag'],
     )
@@ -668,9 +668,9 @@ class BeamformerCleantTraj(BeamformerCleant, BeamformerTimeTraj):
     """
 
     #: Floating point and integer precision
-    precision = Enum(32, 64, desc='numeric precision')
+    precision = Enum(32, 64)
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=[
             'steer.digest',
@@ -723,9 +723,9 @@ class BeamformerCleantSqTraj(BeamformerCleantTraj, BeamformerTimeSq):
     """
 
     #: Boolean flag, if 'True' (default), the main diagonal is removed before beamforming.
-    r_diag = Bool(True, desc='removal of diagonal')
+    r_diag = Bool(True)
 
-    # internal identifier
+    #: A unique identifier for the beamformer, based on its properties. (read-only)
     digest = Property(
         depends_on=[
             'steer.digest',
@@ -777,7 +777,7 @@ class IntegratorSectorTime(TimeOut):
     source = Instance(SamplesGenerator)
 
     #: :class:`~acoular.grids.RectGrid` object that provides the grid locations.
-    grid = Instance(RectGrid, desc='beamforming grid')
+    grid = Instance(RectGrid)
 
     #: List of sectors in grid
     sectors = List()
@@ -788,7 +788,7 @@ class IntegratorSectorTime(TimeOut):
     #: Number of channels in output (= number of sectors).
     num_channels = Property(depends_on=['sectors'])
 
-    # internal identifier
+    #: A unique identifier for the integrator, based on its properties. (read-only)
     digest = Property(
         depends_on=['sectors', 'clip', 'grid.digest', 'source.digest'],
     )

acoular/tools/helpers.py

@@ -144,7 +144,7 @@ def return_result(source, nmax=-1, num=128):
 
     if nmax > 0:
         nblocks = (nmax - 1) // num + 1
-        return np.concatenate([res for _, res in zip(range(nblocks), resulter)])[:nmax]
+        return np.concatenate([res for _, res in zip(range(nblocks), resulter, strict=True)])[:nmax]
     return np.concatenate(list(resulter))
 
 

acoular/tools/utils.py

@@ -6,6 +6,7 @@
     get_file_basename
     find_basename
     mole_fraction_of_water_vapor
+    Polygon
 """
 
 from pathlib import Path
@@ -13,6 +14,173 @@ from pathlib import Path
 import numpy as np
 
 
+def _det(xvert, yvert):
+    xvert = np.asarray(xvert, dtype=float)
+    yvert = np.asarray(yvert, dtype=float)
+    x_prev = np.concatenate(([xvert[-1]], xvert[:-1]))
+    y_prev = np.concatenate(([yvert[-1]], yvert[:-1]))
+    return np.sum(yvert * x_prev - xvert * y_prev, axis=0)
+
+
+class Polygon:
+    """
+    Create an object representing a general polygon in a 2D plane.
+
+    This class allows defining a polygon by specifying the coordinates of its vertices and provides
+    methods for checking whether a set of points lies inside the polygon, or if a point is closer to
+    a side or vertex of the polygon.
+
+    Parameters
+    ----------
+    x : array_like
+        Array of x-coordinates of the vertices that define the polygon. These coordinates should
+        form a closed shape (i.e., the last point should be the same as the first point).
+
+    y : array_like
+        Array of y-coordinates of the vertices that define the polygon. These coordinates should
+        correspond to the x-coordinates, forming a closed shape.
+
+    Attributes
+    ----------
+    x : :class:`numpy.ndarray`
+        Array of x-coordinates of the polygon vertices.
+
+    y : :class:`numpy.ndarray`
+        Array of y-coordinates of the polygon vertices.
+    """
+
+    def __init__(self, x, y):
+        if len(x) != len(y):
+            msg = 'x and y must be equally sized.'
+            raise IndexError(msg)
+        self.x = np.asarray(x, dtype=float)
+        self.y = np.asarray(y, dtype=float)
+        # Closes the polygon if it were open
+        x1, y1 = x[0], y[0]
+        xn, yn = x[-1], y[-1]
+        if x1 != xn or y1 != yn:
+            self.x = np.concatenate((self.x, [x1]))
+            self.y = np.concatenate((self.y, [y1]))
+        # Anti-clockwise coordinates
+        if _det(self.x, self.y) < 0:
+            self.x = self.x[::-1]
+            self.y = self.y[::-1]
+
+    def is_inside(self, xpoint, ypoint, smalld=1e-12):
+        """
+        Check if a point or set of points are inside the polygon.
+
+        Parameters
+        ----------
+        xpoint : :class:`float` or array_like
+            Array of x-coordinates of the points to be tested.
+
+        ypoint : :class:`float` or array_like
+            Array of y-coordinates of the points to be tested.
+
+        smalld : :class:`float`, optional
+            Tolerance used for floating point comparisons when checking if a point is exactly on a
+            polygon's edge. The default value is ``1e-12``.
+
+        Returns
+        -------
+        :class:`float` or array_like
+            The distance from the point to the nearest point on the polygon. The values returned
+            have the following meanings:
+            - ``mindst < 0``: Point is outside the polygon.
+            - ``mindst = 0``: Point is on an edge of the polygon.
+            - ``mindst > 0``: Point is inside the polygon.
+
+        Notes
+        -----
+        The method uses an improved algorithm based on Nordbeck and Rydstedt for determining
+        whether a point is inside a polygon :cite:`SLOAN198545`.
+        """
+        xpoint = np.asarray(xpoint, dtype=float)
+        ypoint = np.asarray(ypoint, dtype=float)
+        # Scalar to array
+        if xpoint.shape == ():
+            xpoint = np.array([xpoint], dtype=float)
+            ypoint = np.array([ypoint], dtype=float)
+            scalar = True
+        else:
+            scalar = False
+        # Check consistency
+        if xpoint.shape != ypoint.shape:
+            msg = 'x and y have different shapes'
+            raise IndexError(msg)
+        # If snear = True: Dist to nearest side < nearest vertex
+        # If snear = False: Dist to nearest vertex < nearest side
+        snear = np.ma.masked_all(xpoint.shape, dtype=bool)
+        # Initialize arrays
+        mindst = np.ones_like(xpoint, dtype=float) * np.inf
+        j = np.ma.masked_all(xpoint.shape, dtype=int)
+        x = self.x
+        y = self.y
+        n = len(x) - 1  # Number of sides/vertices defining the polygon
+        # Loop over each side defining polygon
+        for i in range(n):
+            d = np.ones_like(xpoint, dtype=float) * np.inf
+            # Start of side has coords (x1, y1)
+            # End of side has coords (x2, y2)
+            # Point has coords (xpoint, ypoint)
+            x1 = x[i]
+            y1 = y[i]
+            x21 = x[i + 1] - x1
+            y21 = y[i + 1] - y1
+            x1p = x1 - xpoint
+            y1p = y1 - ypoint
+            # Points on infinite line defined by
+            #     x = x1 + t * (x1 - x2)
+            #     y = y1 + t * (y1 - y2)
+            # where
+            #     t = 0    at (x1, y1)
+            #     t = 1    at (x2, y2)
+            # Find where normal passing through (xpoint, ypoint) intersects
+            # infinite line
+            t = -(x1p * x21 + y1p * y21) / (x21**2 + y21**2)
+            tlt0 = t < 0
+            tle1 = (t >= 0) & (t <= 1)
+            # Normal intersects side
+            d[tle1] = (x1p[tle1] + t[tle1] * x21) ** 2 + (y1p[tle1] + t[tle1] * y21) ** 2
+            # Normal does not intersects side
+            # Point is closest to vertex (x1, y1)
+            # Compute square of distance to this vertex
+            d[tlt0] = x1p[tlt0] ** 2 + y1p[tlt0] ** 2
+            # Store distances
+            mask = d < mindst
+            mindst[mask] = d[mask]
+            j[mask] = i
+            # Point is closer to (x1, y1) than any other vertex or side
+            snear[mask & tlt0] = False
+            # Point is closer to this side than to any other side or vertex
+            snear[mask & tle1] = True
+        if np.ma.count(snear) != snear.size:
+            msg = 'Error computing distances'
+            raise IndexError(msg)
+        mindst **= 0.5
+        # Point is closer to its nearest vertex than its nearest side, check if
+        # nearest vertex is concave.
+        # If the nearest vertex is concave then point is inside the polygon,
+        # else the point is outside the polygon.
+        jo = j.copy()
+        jo[j == 0] -= 1
+        area = _det([x[j + 1], x[j], x[jo - 1]], [y[j + 1], y[j], y[jo - 1]])
+        mindst[~snear] = np.copysign(mindst, area)[~snear]
+        # Point is closer to its nearest side than to its nearest vertex, check
+        # if point is to left or right of this side.
+        # If point is to left of side it is inside polygon, else point is
+        # outside polygon.
+        area = _det([x[j], x[j + 1], xpoint], [y[j], y[j + 1], ypoint])
+        mindst[snear] = np.copysign(mindst, area)[snear]
+        # Point is on side of polygon
+        mindst[np.fabs(mindst) < smalld] = 0
+        # If input values were scalar then the output should be too
+        if scalar:
+            mindst = float(mindst[0])
+        return mindst
+
+
 def get_file_basename(file, alternative_basename='void'):
     """Return the basename of the file.