phasorpy 0.5__cp313-cp313-macosx_11_0_arm64.whl → 0.7__cp313-cp313-macosx_11_0_arm64.whl

phasorpy/__init__.py

@@ -2,9 +2,8 @@
 
 from __future__ import annotations
 
-__all__ = ['__version__', 'versions']
+__all__ = ['__version__']
 
-from .version import __version__, versions
 
-__version__ = __version__  # pylint: disable=self-assigning-variable
+__version__ = '0.7'
 """PhasorPy version string."""

phasorpy/_phasorpy.pyx

@@ -50,6 +50,12 @@ ctypedef fused uint_t:
     uint32_t
     uint64_t
 
+ctypedef fused int_t:
+    int8_t
+    int16_t
+    int32_t
+    int64_t
+
 ctypedef fused signal_t:
     uint8_t
     uint16_t
@@ -482,10 +488,10 @@ cdef (double, double) _phasor_from_fret_donor(
         return 1.0, 0.0
 
     # phasor of pure donor at frequency
-    real, imag = phasor_from_lifetime(donor_lifetime, omega)
+    real, imag = phasor_from_single_lifetime(donor_lifetime, omega)
 
     # phasor of quenched donor
-    quenched_real, quenched_imag = phasor_from_lifetime(
+    quenched_real, quenched_imag = phasor_from_single_lifetime(
         donor_lifetime * (1.0 - fret_efficiency), omega
     )
 
@@ -549,14 +555,14 @@ cdef (double, double) _phasor_from_fret_acceptor(
         acceptor_background = 0.0
 
     # phasor of pure donor at frequency
-    donor_real, donor_imag = phasor_from_lifetime(donor_lifetime, omega)
+    donor_real, donor_imag = phasor_from_single_lifetime(donor_lifetime, omega)
 
     if fret_efficiency == 0.0:
         quenched_real = donor_real
         quenched_imag = donor_imag
     else:
         # phasor of quenched donor
-        quenched_real, quenched_imag = phasor_from_lifetime(
+        quenched_real, quenched_imag = phasor_from_single_lifetime(
             donor_lifetime * (1.0 - fret_efficiency), omega
         )
 
@@ -574,7 +580,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
         )
 
     # phasor of acceptor at frequency
-    acceptor_real, acceptor_imag = phasor_from_lifetime(
+    acceptor_real, acceptor_imag = phasor_from_single_lifetime(
         acceptor_lifetime, omega
     )
 
@@ -640,9 +646,9 @@ cdef inline (double, double) linear_combination(
     )
 
 
-cdef inline (float_t, float_t) phasor_from_lifetime(
-    float_t lifetime,
-    float_t omega,
+cdef inline (double, double) phasor_from_single_lifetime(
+    const double lifetime,
+    const double omega,
 ) noexcept nogil:
     """Return phasor coordinates from single lifetime component."""
     cdef:
@@ -650,7 +656,7 @@ cdef inline (float_t, float_t) phasor_from_lifetime(
         double mod = 1.0 / sqrt(1.0 + t * t)
         double phi = atan(t)
 
-    return <float_t> (mod * cos(phi)), <float_t> (mod * sin(phi))
+    return mod * cos(phi), mod * sin(phi)
 
 
 ###############################################################################
@@ -767,6 +773,33 @@ cdef (float_t, float_t) _phasor_from_apparent_lifetime(
     return <float_t> (mod * cos(phi)), <float_t> (mod * sin(phi))
 
 
+@cython.ufunc
+cdef float_t _phasor_to_normal_lifetime(
+    float_t real,
+    float_t imag,
+    float_t omega,
+) noexcept nogil:
+    """Return normal lifetimes from phasor coordinates."""
+    cdef:
+        double taunorm = INFINITY
+        double t
+
+    if isnan(real) or isnan(imag):
+        return <float_t> NAN
+
+    omega *= omega
+    if omega > 0.0:
+        t = 0.5 * (1.0 + cos(atan2(imag, real - 0.5)))
+        if t <= 0.0:
+            taunorm = INFINITY
+        elif t > 1.0:
+            taunorm = NAN
+        else:
+            taunorm = sqrt((1.0 - t) / (omega * t))
+
+    return <float_t> taunorm
+
+
 @cython.ufunc
 cdef (float_t, float_t) _phasor_from_single_lifetime(
     float_t lifetime,
@@ -1204,6 +1237,44 @@ cdef unsigned char _is_inside_stadium(
 _is_near_segment = _is_inside_stadium
 
 
+@cython.ufunc
+cdef unsigned char _is_inside_semicircle(
+    float_t x,  # point
+    float_t y,
+    float_t r,  # distance
+) noexcept nogil:
+    """Return whether point is inside universal semicircle."""
+    if r < 0.0 or isnan(x) or isnan(y):
+        return False
+    if y < -r:
+        return False
+    if y <= 0.0:
+        if x >= 0.0 and x <= 1.0:
+            return True
+        # near endpoints?
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return x * x + y * y <= r * r
+    return hypot(x - 0.5, y) <= r + 0.5
+
+
+@cython.ufunc
+cdef unsigned char _is_near_semicircle(
+    float_t x,  # point
+    float_t y,
+    float_t r,  # distance
+) noexcept nogil:
+    """Return whether point is near universal semicircle."""
+    if r < 0.0 or isnan(x) or isnan(y):
+        return False
+    if y < 0.0:
+        # near endpoints?
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return x * x + y * y <= r * r
+    return fabs(hypot(x - 0.5, y) - 0.5) <= r
+
+
 @cython.ufunc
 cdef unsigned char _is_near_line(
     float_t x,  # point
@@ -1470,6 +1541,22 @@ cdef float_t _distance_from_line(
     return <float_t> hypot(x, y)
 
 
+@cython.ufunc
+cdef float_t _distance_from_semicircle(
+    float_t x,  # point
+    float_t y,
+) noexcept nogil:
+    """Return distance from universal semicircle."""
+    if isnan(x) or isnan(y):
+        return NAN
+    if y < 0.0:
+        # distance to endpoints
+        if x > 0.5:
+            x -= <float_t> 1.0
+        return <float_t> hypot(x, y)
+    return <float_t> fabs(hypot(x - 0.5, y) - 0.5)
+
+
 @cython.ufunc
 cdef (float_t, float_t, float_t) _segment_direction_and_length(
     float_t x0,  # segment start
@@ -1495,7 +1582,7 @@ cdef (float_t, float_t, float_t) _segment_direction_and_length(
 
 
 @cython.ufunc
-cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
+cdef (float_t, float_t, float_t, float_t) _intersect_circle_circle(
     float_t x0,  # circle 0
     float_t y0,
     float_t r0,
@@ -1541,7 +1628,7 @@ cdef (float_t, float_t, float_t, float_t) _intersection_circle_circle(
 
 
 @cython.ufunc
-cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
+cdef (float_t, float_t, float_t, float_t) _intersect_circle_line(
     float_t x,  # circle
     float_t y,
     float_t r,
@@ -1583,10 +1670,378 @@ cdef (float_t, float_t, float_t, float_t) _intersection_circle_line(
     )
 
 
+@cython.ufunc
+cdef (float_t, float_t, float_t, float_t) _intersect_semicircle_line(
+    float_t x0,  # line start
+    float_t y0,
+    float_t x1,  # line end
+    float_t y1,
+) noexcept nogil:
+    """Return coordinates of intersections of line and universal semicircle."""
+    cdef:
+        double dx, dy, dr, dd, rdd
+
+    if isnan(x0) or isnan(x1) or isnan(y0) or isnan(y1):
+        return NAN, NAN, NAN, NAN
+
+    dx = x1 - x0
+    dy = y1 - y0
+    dr = dx * dx + dy * dy
+    dd = (x0 - 0.5) * y1 - (x1 - 0.5) * y0
+    rdd = 0.25 * dr - dd * dd  # discriminant
+    if rdd < 0.0 or dr <= 0.0:
+        # no intersection
+        return NAN, NAN, NAN, NAN
+    rdd = sqrt(rdd)
+    x0 = <float_t> ((dd * dy - copysign(1.0, dy) * dx * rdd) / dr + 0.5)
+    y0 = <float_t> ((-dd * dx - fabs(dy) * rdd) / dr)
+    x1 = <float_t> ((dd * dy + copysign(1.0, dy) * dx * rdd) / dr + 0.5)
+    y1 = <float_t> ((-dd * dx + fabs(dy) * rdd) / dr)
+    if y0 < 0.0:
+        x0 = NAN
+        y0 = NAN
+    if y1 < 0.0:
+        x1 = NAN
+        y1 = NAN
+    return x0, y0, x1, y1
+
+
+###############################################################################
+# Search functions
+
+
+def _lifetime_search_2(
+    float_t[:, ::] lifetime,  # (num_components, pixels)
+    float_t[:, ::] fraction,  # (num_components, pixels)
+    const float_t[:, ::] real,  # (num_components, pixels)
+    const float_t[:, ::] imag,  # (num_components, pixels)
+    const double[::] candidate,  # real coordinates to scan
+    const double omega_sqr,
+    const int num_threads
+):
+    """Find two lifetime components and fractions in harmonic coordinates.
+
+    https://doi.org/10.1021/acs.jpcb.0c06946
+
+    """
+    cdef:
+        ssize_t i, u
+        double re1, im1, re2, im2
+        double g0, g1, g0h1, s0h1, g1h1, s1h1, g0h2, s0h2, g1h2, s1h2
+        double x, y, dx, dy, dr, dd, rdd
+        double dmin, d, f, t
+
+    if lifetime.shape[0] != 2 or lifetime.shape[1] != real.shape[1]:
+        raise ValueError('lifetime shape invalid')
+    if fraction.shape[0] != 2 or fraction.shape[1] != real.shape[1]:
+        raise ValueError('fraction shape invalid')
+    if real.shape[0] != imag.shape[0] != 2:
+        raise ValueError('phasor harmonics invalid')
+    if real.shape[1] != imag.shape[1]:
+        raise ValueError('phasor size invalid')
+    if candidate.shape[0] < 1:
+        raise ValueError('candidate size < 1')
+
+    with nogil, parallel(num_threads=num_threads):
+
+        for u in prange(real.shape[1]):
+            # loop over phasor coordinates
+            re1 = real[0, u]
+            re2 = real[1, u]
+            im1 = imag[0, u]
+            im2 = imag[1, u]
+
+            if (
+                isnan(re1)
+                or isnan(im1)
+                or isnan(re2)
+                or isnan(im2)
+                # outside semicircle?
+                or re1 < 0.0
+                or re2 < 0.0
+                or re1 > 1.0
+                or re2 > 1.0
+                or im1 < 0.0
+                or im2 < 0.0
+                or im1 * im1 > re1 - re1 * re1 + 1e-9
+                or im2 * im2 > re2 - re2 * re2 + 1e-9
+            ):
+                lifetime[0, u] = NAN
+                lifetime[1, u] = NAN
+                fraction[0, u] = NAN
+                fraction[1, u] = NAN
+                continue
+
+            dmin = INFINITY
+            g0 = NAN
+            g1 = NAN
+            f = NAN
+
+            for i in range(candidate.shape[0]):
+                # scan first component
+                g0h1 = candidate[i]
+                s0h1 = sqrt(g0h1 - g0h1 * g0h1)
+
+                # second component is intersection of semicircle with line
+                # between first component and phasor coordinate
+                dx = re1 - g0h1
+                dy = im1 - s0h1
+                dr = dx * dx + dy * dy
+                dd = (g0h1 - 0.5) * im1 - (re1 - 0.5) * s0h1
+                rdd = 0.25 * dr - dd * dd  # discriminant
+                if rdd < 0.0 or dr <= 0.0:
+                    # no intersection
+                    g0 = g0h1
+                    g1 = g0h1  # NAN?
+                    f = 1.0
+                    break
+                rdd = sqrt(rdd)
+                g0h1 = (dd * dy - copysign(1.0, dy) * dx * rdd) / dr + 0.5
+                s0h1 = (-dd * dx - fabs(dy) * rdd) / dr
+                g1h1 = (dd * dy + copysign(1.0, dy) * dx * rdd) / dr + 0.5
+                s1h1 = (-dd * dx + fabs(dy) * rdd) / dr
+
+                # this check is numerically unstable if candidate=1.0
+                if s0h1 < 0.0 or s1h1 < 0.0:
+                    # no other intersection with semicircle
+                    continue
+
+                if g0h1 < g1h1:
+                    t = g0h1
+                    g0h1 = g1h1
+                    g1h1 = t
+                    t = s0h1
+                    s0h1 = s1h1
+                    s1h1 = t
+
+                # second harmonic component coordinates on semicircle
+                g0h2 = g0h1 / (4.0 - 3.0 * g0h1)
+                s0h2 = sqrt(g0h2 - g0h2 * g0h2)
+                g1h2 = g1h1 / (4.0 - 3.0 * g1h1)
+                s1h2 = sqrt(g1h2 - g1h2 * g1h2)
+
+                # distance of phasor coordinates to line between
+                # components at second harmonic
+                # normalize line coordinates
+                dx = g1h2 - g0h2
+                dy = s1h2 - s0h2
+                x = re2 - g0h2
+                y = im2 - s0h2
+                # square of line length
+                t = dx * dx + dy * dy
+                if t == 0.0:
+                    continue
+                # projection of point on line using dot product
+                t = (x * dx + y * dy) / t
+                # square of distance of point to line
+                dx = x - t * dx
+                dy = y - t * dy
+                d = dx * dx + dy * dy
+
+                if d < dmin:
+                    dmin = d
+                    g0 = g0h1
+                    g1 = g1h1
+                    f = t
+
+            lifetime[0, u] = <float_t> phasor_to_single_lifetime(g0, omega_sqr)
+            lifetime[1, u] = <float_t> phasor_to_single_lifetime(g1, omega_sqr)
+            fraction[0, u] = <float_t> (1.0 - f)
+            fraction[1, u] = <float_t> f
+
+
+cdef inline double phasor_to_single_lifetime(
+    const double real,
+    const double omega_sqr,
+) noexcept nogil:
+    """Return single exponential lifetime from real coordinate."""
+    cdef:
+        double t
+
+    if isnan(real) or real < 0.0 or real > 1.0:
+        return NAN
+    t = real * omega_sqr
+    return sqrt((1.0 - real) / t) if t > 0.0 else INFINITY
+
+
+def _nearest_neighbor_2d(
+    int_t[::1] indices,
+    const float_t[::1] x0,
+    const float_t[::1] y0,
+    const float_t[::1] x1,
+    const float_t[::1] y1,
+    const float_t distance_max,
+    const int num_threads
+):
+    """Find nearest neighbors in 2D.
+
+    For each point in the first set of arrays (x0, y0) find the nearest point
+    in the second set of arrays (x1, y1) and store the index of the nearest
+    point in the second array in the indices array.
+    If any coordinates are NaN, or the distance to the nearest point
+    is larger than distance_max, the index is set to -1.
+
+    """
+    cdef:
+        ssize_t i, j, index
+        float_t x, y, dmin
+        float_t distance_max_squared = distance_max * distance_max
+
+    if (
+        indices.shape[0] != x0.shape[0]
+        or x0.shape[0] != y0.shape[0]
+        or x1.shape[0] != y1.shape[0]
+    ):
+        raise ValueError('input array size mismatch')
+
+    with nogil, parallel(num_threads=num_threads):
+        for i in prange(x0.shape[0]):
+            x = x0[i]
+            y = y0[i]
+            if isnan(x) or isnan(y):
+                indices[i] = -1
+                continue
+            index = -1
+            dmin = INFINITY
+            for j in range(x1.shape[0]):
+                x = x0[i] - x1[j]
+                y = y0[i] - y1[j]
+                x = x * x + y * y
+                if x < dmin:
+                    dmin = x
+                    index = j
+            indices[i] = -1 if dmin > distance_max_squared else <int_t> index
+
+
+###############################################################################
+# Interpolation functions
+
+
+def _mean_value_coordinates(
+    float_t[:, ::1] fraction,  # vertices, points
+    const ssize_t[::1] order,
+    const float_t[::1] px,  # points
+    const float_t[::1] py,
+    const float_t[::1] vx,  # polygon vertices
+    const float_t[::1] vy,
+    const int num_threads
+):
+    """Calculate mean value coordinates of points in polygon.
+
+    https://doi.org/10.1016/j.cagd.2024.102310
+
+    """
+    cdef:
+        ssize_t i, j, k, p, nv
+        double x, y, alpha, weight, weight_sum
+        double* weights = NULL
+        double* sigma = NULL
+        double* length = NULL
+
+    if px.shape[0] != py.shape[0]:
+        raise ValueError('px and py shape mismatch')
+    if vx.shape[0] != vy.shape[0]:
+        raise ValueError('vx and vy shape mismatch')
+    if fraction.shape[0] != vx.shape[0] or fraction.shape[1] != px.shape[0]:
+        raise ValueError('fraction, vx or px shape mismatch')
+    if fraction.shape[0] != order.shape[0]:
+        raise ValueError('fraction and order shape mismatch')
+    if fraction.shape[0] < 3:
+        raise ValueError('not a polygon')
+
+    nv = fraction.shape[0]
+
+    with nogil, parallel(num_threads=num_threads):
+        weights = <double *> malloc(3 * nv * sizeof(double))
+        if weights == NULL:
+            with gil:
+                raise MemoryError('failed to allocate thread-local buffer')
+        sigma = &weights[nv]
+        length = &weights[nv * 2]
+
+        for p in prange(px.shape[0]):
+            x = px[p]
+            y = py[p]
+
+            if isnan(x) or isnan(y):
+                for i in range(nv):
+                    fraction[i, p] = <float_t> NAN
+                continue
+
+            for i in range(nv):
+                j = (i + 1) % nv  # next vertex, wrapped around
+                sigma[i] = (
+                    angle(vx[j], vy[j], vx[i], vy[i], x, y)  # beta
+                    - angle(vx[i], vy[i], vx[j], vy[j], x, y)  # gamma
+                )
+                length[i] = hypot(vx[i] - x, vy[i] - y)
+
+            weight_sum = 0.0
+            for i in range(nv):
+                j = (i + 1) % nv  # next vertex, wrapped around
+                k = (i - 1 + nv) % nv  # previous vertex, wrapped around
+
+                alpha = angle(vx[k], vy[k], x, y, vx[j], vy[j])
+                if sign(alpha) != sign(
+                    M_PI * (sign(sigma[k]) + sign(sigma[i]))
+                    - sigma[k] - sigma[i]
+                ):
+                    alpha = -alpha
+                weight = length[k] * sin(alpha * 0.5)
+                for j in range(nv):
+                    if j != k and j != i:
+                        weight = weight * length[j] * sin(fabs(sigma[j]) * 0.5)
+                weight_sum = weight_sum + weight
+                weights[i] = weight
+
+            if fabs(weight_sum) > 1e-12:
+                for i in range(nv):
+                    fraction[order[i], p] = <float_t> (weights[i] / weight_sum)
+            else:
+                for i in range(nv):
+                    fraction[i, p] = <float_t> NAN
+
+        free(weights)
+
+
+cdef inline int sign(const double x) noexcept nogil:
+    """Return sign of x."""
+    return 0 if fabs(x) < 1e-12 else (1 if x > 0.0 else -1)
+
+
+cdef inline double angle(
+    const double x0,
+    const double y0,
+    const double x1,
+    const double y1,
+    const double x2,
+    const double y2,
+) noexcept nogil:
+    """Return angle at (x1, y1)."""
+    cdef:
+        double ax = x0 - x1
+        double ay = y0 - y1
+        double bx = x2 - x1
+        double by = y2 - y1
+
+    return atan2(ax * by - ay * bx, ax * bx + ay * by)
+
+
 ###############################################################################
 # Blend ufuncs
 
 
+@cython.ufunc
+cdef float_t _blend_and(
+    float_t a,  # base layer
+    float_t b,  # blend layer
+) noexcept nogil:
+    """Return blended layers using `and` mode."""
+    if isnan(a):
+        return NAN
+    return b
+
+
 @cython.ufunc
 cdef float_t _blend_normal(
     float_t a,  # base layer