phasorpy 0.4__cp312-cp312-win_amd64.whl → 0.6__cp312-cp312-win_amd64.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.6'
 """PhasorPy version string."""

phasorpy/_phasorpy.pyx

@@ -4,15 +4,10 @@
 # cython: wraparound = False
 # cython: cdivision = True
 # cython: nonecheck = False
+# cython: freethreading_compatible = True
 
 """Cython implementation of low-level functions for the PhasorPy library."""
 
-# TODO: replace short with unsigned char when Cython supports it
-# https://github.com/cython/cython/pull/6196#issuecomment-2209509572
-
-# TODO: use fused return types for functions returning more than two items
-# https://github.com/cython/cython/issues/6328
-
 cimport cython
 
 from cython.parallel import parallel, prange
@@ -55,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
@@ -451,7 +452,7 @@ cdef (double, double) _phasor_from_fret_donor(
     double omega,
     double donor_lifetime,
     double fret_efficiency,
-    double donor_freting,
+    double donor_fretting,
     double donor_background,
     double background_real,
     double background_imag,
@@ -471,16 +472,16 @@ cdef (double, double) _phasor_from_fret_donor(
     elif fret_efficiency > 1.0:
         fret_efficiency = 1.0
 
-    if donor_freting < 0.0:
-        donor_freting = 0.0
-    elif donor_freting > 1.0:
-        donor_freting = 1.0
+    if donor_fretting < 0.0:
+        donor_fretting = 0.0
+    elif donor_fretting > 1.0:
+        donor_fretting = 1.0
 
     if donor_background < 0.0:
         donor_background = 0.0
 
-    f_pure = 1.0 - donor_freting
-    f_quenched = (1.0 - fret_efficiency) * donor_freting
+    f_pure = 1.0 - donor_fretting
+    f_quenched = (1.0 - fret_efficiency) * donor_fretting
     sum = f_pure + f_quenched + donor_background
     if sum < 1e-9:
         # no signal in donor channel
@@ -516,7 +517,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
     double donor_lifetime,
     double acceptor_lifetime,
     double fret_efficiency,
-    double donor_freting,
+    double donor_fretting,
     double donor_bleedthrough,
     double acceptor_bleedthrough,
     double acceptor_background,
@@ -541,10 +542,10 @@ cdef (double, double) _phasor_from_fret_acceptor(
     elif fret_efficiency > 1.0:
         fret_efficiency = 1.0
 
-    if donor_freting < 0.0:
-        donor_freting = 0.0
-    elif donor_freting > 1.0:
-        donor_freting = 1.0
+    if donor_fretting < 0.0:
+        donor_fretting = 0.0
+    elif donor_fretting > 1.0:
+        donor_fretting = 1.0
 
     if donor_bleedthrough < 0.0:
         donor_bleedthrough = 0.0
@@ -575,7 +576,7 @@ cdef (double, double) _phasor_from_fret_acceptor(
             quenched_imag,
             1.0,
             1.0 - fret_efficiency,
-            1.0 - donor_freting
+            1.0 - donor_fretting
         )
 
     # phasor of acceptor at frequency
@@ -597,8 +598,8 @@ cdef (double, double) _phasor_from_fret_acceptor(
     sensitized_imag = mod * sin(phi)
 
     # weighted average
-    f_donor = donor_bleedthrough * (1.0 - donor_freting * fret_efficiency)
-    f_acceptor = donor_freting * fret_efficiency
+    f_donor = donor_bleedthrough * (1.0 - donor_fretting * fret_efficiency)
+    f_acceptor = donor_fretting * fret_efficiency
     sum = f_donor + f_acceptor + acceptor_bleedthrough + acceptor_background
     if sum < 1e-9:
         # no signal in acceptor channel
@@ -772,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,
@@ -919,7 +947,7 @@ cdef (float_t, float_t) _phasor_at_harmonic(
     int harmonic,
     int other_harmonic,
 ) noexcept nogil:
-    """Return phasor coordinates on semicircle at other harmonic."""
+    """Return phasor coordinates on universal semicircle at other harmonic."""
     if isnan(real):
         return <float_t> NAN, <float_t> NAN
 
@@ -982,7 +1010,7 @@ cdef (float_t, float_t) _phasor_divide(
 
 
 @cython.ufunc
-cdef short _is_inside_range(
+cdef unsigned char _is_inside_range(
     float_t x,  # point
     float_t y,
     float_t xmin,  # x range
@@ -1002,7 +1030,7 @@ cdef short _is_inside_range(
 
 
 @cython.ufunc
-cdef short _is_inside_rectangle(
+cdef unsigned char _is_inside_rectangle(
     float_t x,  # point
     float_t y,
     float_t x0,  # segment start
@@ -1044,7 +1072,7 @@ cdef short _is_inside_rectangle(
 
 
 @cython.ufunc
-cdef short _is_inside_polar_rectangle(
+cdef unsigned char _is_inside_polar_rectangle(
     float_t x,  # point
     float_t y,
     float_t angle_min,  # phase, -pi to pi
@@ -1054,7 +1082,7 @@ cdef short _is_inside_polar_rectangle(
 ) noexcept nogil:
     """Return whether point is inside polar rectangle.
 
-    Angles should be in range -pi to pi, else performance is degraded.
+    Angles should be in range [-pi, pi], else performance is degraded.
 
     """
     cdef:
@@ -1083,7 +1111,7 @@ cdef short _is_inside_polar_rectangle(
 
 
 @cython.ufunc
-cdef short _is_inside_circle(
+cdef unsigned char _is_inside_circle(
     float_t x,  # point
     float_t y,
     float_t x0,  # circle center
@@ -1100,7 +1128,7 @@ cdef short _is_inside_circle(
 
 
 @cython.ufunc
-cdef short _is_inside_ellipse(
+cdef unsigned char _is_inside_ellipse(
     float_t x,  # point
     float_t y,
     float_t x0,  # ellipse center
@@ -1135,7 +1163,7 @@ cdef short _is_inside_ellipse(
 
 
 @cython.ufunc
-cdef short _is_inside_ellipse_(
+cdef unsigned char _is_inside_ellipse_(
     float_t x,  # point
     float_t y,
     float_t x0,  # ellipse center
@@ -1164,7 +1192,7 @@ cdef short _is_inside_ellipse_(
 
 
 @cython.ufunc
-cdef short _is_inside_stadium(
+cdef unsigned char _is_inside_stadium(
     float_t x,  # point
     float_t y,
     float_t x0,  # line start
@@ -1210,7 +1238,45 @@ _is_near_segment = _is_inside_stadium
 
 
 @cython.ufunc
-cdef short _is_near_line(
+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
     float_t y,
     float_t x0,  # line start
@@ -1476,7 +1542,23 @@ cdef float_t _distance_from_line(
 
 
 @cython.ufunc
-cdef (double, double, double) _segment_direction_and_length(
+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
     float_t y0,
     float_t x1,  # segment end
@@ -1500,7 +1582,7 @@ cdef (double, double, double) _segment_direction_and_length(
 
 
 @cython.ufunc
-cdef (double, double, double, double) _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,
@@ -1538,15 +1620,15 @@ cdef (double, double, double, double) _intersection_circle_circle(
     hd = sqrt(dd) / dr
     ld = ll / dr
     return (
-        ld * dx + hd * dy + x0,
-        ld * dy - hd * dx + y0,
-        ld * dx - hd * dy + x0,
-        ld * dy + hd * dx + y0,
+        <float_t> (ld * dx + hd * dy + x0),
+        <float_t> (ld * dy - hd * dx + y0),
+        <float_t> (ld * dx - hd * dy + x0),
+        <float_t> (ld * dy + hd * dx + y0),
     )
 
 
 @cython.ufunc
-cdef (double, double, double, double) _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,
@@ -1581,17 +1663,113 @@ cdef (double, double, double, double) _intersection_circle_line(
         return NAN, NAN, NAN, NAN
     rdd = sqrt(rdd)
     return (
-        x + (dd * dy + copysign(1.0, dy) * dx * rdd) / dr,
-        y + (-dd * dx + fabs(dy) * rdd) / dr,
-        x + (dd * dy - copysign(1.0, dy) * dx * rdd) / dr,
-        y + (-dd * dx - fabs(dy) * rdd) / dr,
+        x + <float_t> ((dd * dy + copysign(1.0, dy) * dx * rdd) / dr),
+        y + <float_t> ((-dd * dx + fabs(dy) * rdd) / dr),
+        x + <float_t> ((dd * dy - copysign(1.0, dy) * dx * rdd) / dr),
+        y + <float_t> ((-dd * dx - fabs(dy) * rdd) / dr),
     )
 
 
+@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
+
+
+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
+
+
 ###############################################################################
 # 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
@@ -1665,7 +1843,7 @@ cdef float_t _blend_lighten(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_open(
+cdef (float_t, float_t, float_t) _phasor_threshold_open(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1727,7 +1905,7 @@ cdef (double, double, double) _phasor_threshold_open(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_closed(
+cdef (float_t, float_t, float_t) _phasor_threshold_closed(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1789,7 +1967,7 @@ cdef (double, double, double) _phasor_threshold_closed(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_mean_open(
+cdef (float_t, float_t, float_t) _phasor_threshold_mean_open(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1809,7 +1987,7 @@ cdef (double, double, double) _phasor_threshold_mean_open(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_mean_closed(
+cdef (float_t, float_t, float_t) _phasor_threshold_mean_closed(
     float_t mean,
     float_t real,
     float_t imag,
@@ -1829,7 +2007,7 @@ cdef (double, double, double) _phasor_threshold_mean_closed(
 
 
 @cython.ufunc
-cdef (double, double, double) _phasor_threshold_nan(
+cdef (float_t, float_t, float_t) _phasor_threshold_nan(
     float_t mean,
     float_t real,
     float_t imag,
@@ -2171,6 +2349,7 @@ def _median_filter_2d(
 # Decoder functions
 
 
+@cython.boundscheck(True)
 def _flimlabs_signal(
     uint_t[:, :, ::] signal,   # channel, pixel, bin
     list data,  # list[list[list[[int, int]]]]
@@ -2178,6 +2357,7 @@ def _flimlabs_signal(
 ):
     """Return TCSPC histogram image from FLIM LABS JSON intensity data."""
     cdef:
+        uint_t[::] signal_
         list channels, pixels
         ssize_t c, i, h, count
 
@@ -2186,18 +2366,21 @@ def _flimlabs_signal(
         for channels in data:
             i = 0
             for pixels in channels:
+                signal_ = signal[c, i]
                 for h, count in pixels:
-                    signal[c, i, h] = <uint_t> count
+                    signal_[h] = <uint_t> count
                 i += 1
             c += 1
     else:
         i = 0
         for pixels in data[channel]:
+            signal_ = signal[0, i]
             for h, count in pixels:
-                signal[0, i, h] = <uint_t> count
+                signal_[h] = <uint_t> count
             i += 1
 
 
+@cython.boundscheck(True)
 def _flimlabs_mean(
     float_t[:, ::] mean,   # channel, pixel
     list data,  # list[list[list[[int, int]]]]
@@ -2205,6 +2388,7 @@ def _flimlabs_mean(
 ):
     """Return mean intensity image from FLIM LABS JSON intensity data."""
     cdef:
+        float_t[::] mean_
         list channels, pixels
         ssize_t c, i, h, count
         double sum
@@ -2212,19 +2396,21 @@ def _flimlabs_mean(
     if channel < 0:
         c = 0
         for channels in data:
+            mean_ = mean[c]
             i = 0
             for pixels in channels:
                 sum = 0.0
                 for h, count in pixels:
                     sum += <double> count
-                mean[c, i] = <float_t> (sum / 255.0)
+                mean_[i] = <float_t> (sum / 256.0)
                 i += 1
             c += 1
     else:
         i = 0
+        mean_ = mean[0]
         for pixels in data[channel]:
             sum = 0.0
             for h, count in pixels:
                 sum += <double> count
-            mean[0, i] = <float_t> (sum / 255.0)
+            mean_[i] = <float_t> (sum / 256.0)
             i += 1