flimkit 0.12.0__py3-none-any.whl

flimkit/UI/phasor_panel.py

@@ -0,0 +1,1087 @@
+import tkinter as tk
+from tkinter import ttk, filedialog, messagebox
+from pathlib import Path
+
+import numpy as np
+
+import matplotlib
+from flimkit.mpl_backend import select_backend
+select_backend()
+from matplotlib.backends.backend_tkagg import FigureCanvasTkAgg, NavigationToolbar2Tk
+from matplotlib.figure import Figure
+from matplotlib.patches import Ellipse, Polygon as MplPolygon
+from matplotlib.path import Path as MplPath
+
+from phasorpy.cursor import mask_from_elliptic_cursor, pseudo_color
+from phasorpy.lifetime import phasor_to_apparent_lifetime, phasor_semicircle_intersect
+from phasorpy.component import phasor_component_fraction
+from phasorpy.plot import PhasorPlot
+
+_COLORS = ['#d62728', '#1f77b4', '#2ca02c', '#ff7f0e', '#9467bd', '#8c564b']
+
+def _hex_to_rgb01(h):
+    h = h.lstrip('#')
+    return (int(h[0:2], 16) / 255.0,
+            int(h[2:4], 16) / 255.0,
+            int(h[4:6], 16) / 255.0)
+
+def _tau_phi_scalar(g, s, freq_mhz):
+    """Return τ_φ (ns) for a single (G, S) point.
+
+    phasorpy.phasor_to_apparent_lifetime returns a scalar (not array) when
+    the inputs are Python floats - avoids the float(1-element-array) TypeError.
+    """
+    tau_phi, _ = phasor_to_apparent_lifetime(float(g), float(s), freq_mhz)
+    return float(tau_phi)
+
+class PhasorViewPanel:
+
+    def __init__(self, parent, max_cursors=6):
+        self.max_cursors = max_cursors
+        self.on_change = None
+
+        self._real = None
+        self._imag = None
+        self._real_raw = None
+        self._imag_raw = None
+        self._mean = None
+        self._disp = None
+        self._freq = 80.0
+        self._valid = None
+
+        self._filter_method = tk.StringVar(value='none')
+        self._filter_sigma = tk.DoubleVar(value=1.0)
+        self._filter_size = tk.IntVar(value=3)
+
+        self._cursors = []
+        self._cursor_artists = []
+
+        self._fret_trajectory = None
+        self._peak_results = None
+
+        self._mode_var = tk.StringVar(value='ellipse')
+        self._poly_pts = []
+        self._poly_line = None
+
+        self._drag_idx = None
+        self._drag_last = (0.0, 0.0)
+
+        self._ptu_path = None
+        self._channel = None
+        self._last_fit_result = None
+        self.run_with_progress = None
+        self.get_fit_params = None
+
+        self._radius = tk.DoubleVar(value=0.05)
+        self._ratio = tk.DoubleVar(value=0.60)
+
+        self.frame = ttk.Frame(parent)
+        self.frame.columnconfigure(0, weight=1)
+        self.frame.rowconfigure(1, weight=1)
+
+        self._build_controls()
+        self._build_figure()
+
+        self._status_var = tk.StringVar(
+            value='Load a PTU file to begin phasor analysis.')
+        ttk.Label(self.frame, textvariable=self._status_var,
+                  foreground='grey', font=('Courier', 8)).grid(
+            row=2, column=0, sticky='w', padx=4, pady=(0, 2))
+
+    def _build_controls(self):
+        ctrl = ttk.Frame(self.frame)
+        ctrl.grid(row=0, column=0, sticky='ew', padx=4, pady=(4, 2))
+
+        row0 = ttk.Frame(ctrl)
+        row0.pack(side='top', fill='x')
+
+        ttk.Button(row0, text='✕  Clear all',
+                   command=self._on_clear).pack(side='left', padx=(0, 4))
+        ttk.Button(row0, text='↩  Undo',
+                   command=self._on_undo).pack(side='left', padx=(0, 8))
+        ttk.Button(row0, text='Save session',
+                   command=self._on_save).pack(side='left', padx=(0, 12))
+
+        ttk.Separator(row0, orient='vertical').pack(
+            side='left', fill='y', padx=(0, 8))
+        ttk.Label(row0, text='Mode:').pack(side='left')
+        ttk.Radiobutton(row0, text='Ellipse', variable=self._mode_var,
+                        value='ellipse',
+                        command=self._on_mode_change).pack(
+            side='left', padx=(2, 2))
+        ttk.Radiobutton(row0, text='Polygon', variable=self._mode_var,
+                        value='poly',
+                        command=self._on_mode_change).pack(
+            side='left', padx=(0, 8))
+
+        row_params = ttk.Frame(ctrl)
+        row_params.pack(side='top', fill='x', pady=(2, 0))
+        self._ellipse_ctrl_frame = ttk.Frame(row_params)
+        self._ellipse_ctrl_frame.pack(side='left')
+        ttk.Label(self._ellipse_ctrl_frame, text='Radius:').pack(side='left')
+        ttk.Scale(self._ellipse_ctrl_frame, variable=self._radius,
+                  from_=0.01, to=0.15, orient='horizontal', length=90,
+                  command=lambda _: self._on_param_change()).pack(
+            side='left', padx=(2, 4))
+        self._radius_lbl = ttk.Label(self._ellipse_ctrl_frame,
+                                     text='0.050', width=5)
+        self._radius_lbl.pack(side='left', padx=(0, 14))
+
+        ttk.Label(self._ellipse_ctrl_frame, text='Minor/major:').pack(
+            side='left')
+        ttk.Scale(self._ellipse_ctrl_frame, variable=self._ratio,
+                  from_=0.10, to=1.00, orient='horizontal', length=70,
+                  command=lambda _: self._on_param_change()).pack(
+            side='left', padx=(2, 4))
+        self._ratio_lbl = ttk.Label(self._ellipse_ctrl_frame,
+                                    text='0.60', width=4)
+        self._ratio_lbl.pack(side='left')
+
+        self._radius.trace_add('write', lambda *_: self._update_param_labels())
+        self._ratio.trace_add('write',  lambda *_: self._update_param_labels())
+
+        row1 = ttk.Frame(ctrl)
+        row1.pack(side='top', fill='x', pady=(2, 0))
+        ttk.Button(row1, text='⚗ Fit Cursor Decay',
+                   command=self._fit_cursor_decay).pack(side='left', padx=(0, 4))
+        ttk.Button(row1, text='View Fit',
+                   command=self._view_last_fit_result).pack(side='left')
+
+        row_filt = ttk.Frame(ctrl)
+        row_filt.pack(side='top', fill='x', pady=(2, 0))
+        ttk.Label(row_filt, text='Phasor filter:').pack(side='left')
+        ttk.Combobox(
+            row_filt, textvariable=self._filter_method,
+            values=['none', 'gaussian', 'median', 'wavelet'],
+            state='readonly', width=9,
+        ).pack(side='left', padx=(2, 6))
+        self._filter_method.trace_add('write', lambda *_: self._on_filter_method_change())
+
+        self._filt_sigma_frame = ttk.Frame(row_filt)
+        self._filt_sigma_frame.pack(side='left')
+        ttk.Label(self._filt_sigma_frame, text='σ:').pack(side='left')
+        ttk.Spinbox(self._filt_sigma_frame, textvariable=self._filter_sigma,
+                    from_=0.5, to=10.0, increment=0.5, width=5).pack(side='left', padx=(2, 6))
+
+        self._filt_size_frame = ttk.Frame(row_filt)
+        self._filt_size_frame.pack(side='left')
+        ttk.Label(self._filt_size_frame, text='size:').pack(side='left')
+        ttk.Spinbox(self._filt_size_frame, textvariable=self._filter_size,
+                    from_=3, to=15, increment=2, width=4).pack(side='left', padx=(2, 6))
+        self._filt_size_frame.pack_forget()
+
+        ttk.Button(row_filt, text='Apply',
+                   command=self._on_filter_apply).pack(side='left', padx=(0, 4))
+        ttk.Button(row_filt, text='Reset',
+                   command=self._on_filter_reset).pack(side='left')
+
+    def _update_param_labels(self):
+        self._radius_lbl.configure(text=f"{self._radius.get():.3f}")
+        self._ratio_lbl.configure(text=f"{self._ratio.get():.2f}")
+
+    def _on_filter_method_change(self):
+        method = self._filter_method.get()
+        if method == 'gaussian':
+            self._filt_sigma_frame.pack(side='left')
+            self._filt_size_frame.pack_forget()
+        elif method in ('median', 'wavelet'):
+            self._filt_sigma_frame.pack_forget()
+            self._filt_size_frame.pack(side='left')
+        else:
+            self._filt_sigma_frame.pack_forget()
+            self._filt_size_frame.pack_forget()
+
+    def _on_filter_apply(self):
+        if self._real_raw is None:
+            return
+        method = self._filter_method.get()
+        if method == 'none':
+            return
+        from flimkit.phasor.filters import phasor_filter
+        kwargs = {}
+        if method == 'gaussian':
+            kwargs['sigma'] = float(self._filter_sigma.get())
+        elif method in ('median', 'wavelet'):
+            kwargs['size'] = int(self._filter_size.get())
+        try:
+            self._real, self._imag = phasor_filter(
+                self._real_raw.copy(), self._imag_raw.copy(), method,
+                mean=self._mean, **kwargs)
+        except Exception as exc:
+            messagebox.showerror('Filter error', str(exc))
+            return
+        self._redraw_phasor()
+        self._redraw_cursors()
+        self._canvas.draw_idle()
+        self._status_var.set(
+            f"Phasor filter applied: {method}  "
+            + (f"(\u03c3={kwargs.get('sigma', '')})" if method == 'gaussian'
+               else f"(size={kwargs.get('size', '')})"))
+
+    def _on_filter_reset(self):
+        if self._real_raw is None:
+            return
+        self._real = self._real_raw.copy()
+        self._imag = self._imag_raw.copy()
+        self._filter_method.set('none')
+        self._redraw_phasor()
+        self._redraw_cursors()
+        self._canvas.draw_idle()
+        self._status_var.set('Phasor filter reset.')
+
+    def _build_figure(self):
+        fig_frame = ttk.Frame(self.frame)
+        fig_frame.grid(row=1, column=0, sticky='nsew')
+        fig_frame.columnconfigure(0, weight=1)
+        fig_frame.rowconfigure(0, weight=1)
+
+        self._fig = Figure(figsize=(5, 7), dpi=100, facecolor='black')
+        gs = self._fig.add_gridspec(
+            2, 1, height_ratios=[1, 1.8],
+            hspace=0.38, left=0.10, right=0.95, top=0.95, bottom=0.07)
+        self._ax_img = self._fig.add_subplot(gs[0])
+        self._ax_ph = self._fig.add_subplot(gs[1])
+
+        self._draw_placeholder()
+
+        self._canvas = FigureCanvasTkAgg(self._fig, master=fig_frame)
+        self._canvas.get_tk_widget().grid(row=0, column=0, sticky='nsew')
+
+        tb_frame = ttk.Frame(fig_frame)
+        tb_frame.grid(row=1, column=0, sticky='ew')
+        self._toolbar = NavigationToolbar2Tk(self._canvas, tb_frame,
+                                              pack_toolbar=True)
+        self._toolbar.update()
+
+        self._cid = self._canvas.mpl_connect('button_press_event',
+                                               self._on_click)
+        self._canvas.mpl_connect('motion_notify_event',   self._on_motion)
+        self._canvas.mpl_connect('button_release_event',  self._on_release)
+        self._canvas.mpl_connect('key_press_event',       self._on_key)
+
+    def _draw_placeholder(self):
+        for ax in (self._ax_img, self._ax_ph):
+            ax.set_facecolor('black')
+            ax.tick_params(left=False, bottom=False,
+                           labelleft=False, labelbottom=False)
+        self._ax_img.set_title(
+            'FOV image  (pseudo-colour overlay once cursors are placed)',
+            fontsize=9, color='#999999')
+        self._ax_ph.set_title(
+            'Phasor plot  -  load a file to begin',
+            fontsize=9, color='#999999')
+
+    def set_data(self,
+                 real_cal,
+                 imag_cal,
+                 mean,
+                 frequency,
+                 display_image=None,
+                 min_photons=0.01):
+        """Load phasor arrays and render the phasor histogram.
+        Must be called from the Tk main thread.
+        """
+        self._real_raw = np.asarray(real_cal, dtype=float).squeeze()
+        self._imag_raw = np.asarray(imag_cal, dtype=float).squeeze()
+        self._real = self._real_raw.copy()
+        self._imag = self._imag_raw.copy()
+        self._mean = np.asarray(mean,          dtype=float).squeeze()
+        self._disp = (np.asarray(display_image, dtype=float).squeeze()
+                       if display_image is not None else self._mean.copy())
+        self._freq = float(frequency)
+        self._valid = (self._mean >= min_photons) & ~np.isnan(self._real)
+
+        self._cursors.clear()
+        self._cursor_artists.clear()
+
+        self._redraw_phasor()
+        self._redraw_image(masks=None)
+        self._canvas.draw_idle()
+
+        n_valid = int(self._valid.sum())
+        self._status_var.set(
+            f"✓ {n_valid} valid pixels  |  {frequency:.1f} MHz  "
+            f"|  click phasor to place cursor")
+
+    def load_session(self, session, min_photons=0.01):
+        self.set_data(
+            session['real_cal'], session['imag_cal'],
+            session['mean'], session['frequency'],
+            display_image=session.get('display_image'),
+            min_photons=min_photons,
+        )
+        for c in session.get('cursors', []):
+            if c.get('type') == 'poly':
+                self._cursors.append(dict(
+                    type='poly',
+                    vertices=[(float(v[0]), float(v[1]))
+                               for v in c['vertices']],
+                    color=c['color']))
+            else:
+                self._cursors.append(dict(
+                    type='ellipse',
+                    center_g=float(c['center_g']),
+                    center_s=float(c['center_s']),
+                    color=c['color']))
+        p = session.get('params', {})
+        if 'radius' in p:
+            self._radius.set(float(p['radius']))
+        if 'radius_minor' in p and p.get('radius', 0) > 0:
+            self._ratio.set(float(p['radius_minor']) / float(p['radius']))
+        if self._cursors:
+            self._redraw_cursors()
+            self._analyse()
+
+    def get_session_dict(self):
+        r = self._radius.get()
+        rm = r * self._ratio.get()
+        cursors = []
+        for c in self._cursors:
+            if c.get('type', 'ellipse') == 'poly':
+                cursors.append(dict(type='poly',
+                                    vertices=c['vertices'],
+                                    color=c['color']))
+            else:
+                cursors.append(dict(type='ellipse',
+                                    center_g=c['center_g'],
+                                    center_s=c['center_s'],
+                                    color=c['color']))
+        return dict(
+            real_cal=self._real,
+            imag_cal=self._imag,
+            mean=self._mean,
+            frequency=self._freq,
+            display_image=self._disp,
+            cursors=cursors,
+            params=dict(radius=r, radius_minor=rm, angle_mode='semicircle'),
+        )
+
+    def _redraw_phasor(self):
+        self._ax_ph.cla()
+        if self._real is None:
+            return
+        g = self._real[self._valid]
+        s = self._imag[self._valid]
+
+        pp = PhasorPlot(ax=self._ax_ph, frequency=self._freq)
+        pp.hist2d(g, s, cmap='inferno', bins=256)
+        self._ax_ph.set_facecolor('black')
+        self._ax_ph.set_title(
+            f"Phasor  ({self._freq:.1f} MHz)  -  click to place cursor",
+            fontsize=9)
+        self._redraw_fret_overlay()
+        self._redraw_peaks_overlay()
+
+    def _redraw_cursors(self):
+        for art in self._cursor_artists:
+            try:
+                art.remove()
+            except Exception:
+                pass
+        self._cursor_artists.clear()
+
+        if self._poly_line is not None:
+            for art in self._poly_line:
+                try:
+                    art.remove()
+                except Exception:
+                    pass
+            self._poly_line = None
+
+        r = self._radius.get()
+        r_min = r * self._ratio.get()
+        ax = self._ax_ph
+
+        for i, cur in enumerate(self._cursors):
+            col = cur['color']
+            ctype = cur.get('type', 'ellipse')
+
+            if ctype == 'poly':
+                verts = cur['vertices']
+                poly_patch = MplPolygon(
+                    verts, closed=True,
+                    facecolor=col, alpha=0.18,
+                    edgecolor=col, linewidth=2,
+                    linestyle='--', zorder=8)
+                ax.add_patch(poly_patch)
+                self._cursor_artists.append(poly_patch)
+                cx = float(np.mean([v[0] for v in verts]))
+                cy = float(np.mean([v[1] for v in verts]))
+            else:
+                cg, cs = cur['center_g'], cur['center_s']
+                ang = float(np.degrees(np.arctan2(cs, cg - 0.5) + np.pi / 2.0))
+                ell = Ellipse((cg, cs), 2 * r, 2 * r_min,
+                              angle=ang, facecolor=col, alpha=0.18,
+                              edgecolor=col, linewidth=2,
+                              linestyle='--', zorder=8)
+                ax.add_patch(ell)
+                self._cursor_artists.append(ell)
+                cx, cy = cg, cs
+
+            (dot,) = ax.plot(cx, cy, 'o', color=col, ms=7, zorder=10)
+            self._cursor_artists.append(dot)
+            txt = ax.text(cx + 0.015, cy + 0.015, f'C{i+1}',
+                          color=col, fontsize=9, fontweight='bold', zorder=11)
+            self._cursor_artists.append(txt)
+
+        if len(self._cursors) >= 2:
+            c0 = self._cursors[0]
+            c1 = self._cursors[1]
+            if (c0.get('type', 'ellipse') == 'ellipse' and
+                    c1.get('type', 'ellipse') == 'ellipse'):
+                g0, s0 = c0['center_g'], c0['center_s']
+                g1, s1 = c1['center_g'], c1['center_s']
+                gi0, si0, gi1, si1 = phasor_semicircle_intersect(g0, s0, g1, s1)
+                if not np.isnan(float(gi0)):
+                    (ln,)  = ax.plot([float(gi0), float(gi1)],
+                                     [float(si0), float(si1)],
+                                     'w-', lw=1.5, alpha=0.7, zorder=7)
+                    (pt1,) = ax.plot(float(gi0), float(si0),
+                                     'g*', ms=11, zorder=12)
+                    (pt2,) = ax.plot(float(gi1), float(si1),
+                                     'm*', ms=11, zorder=12)
+                    self._cursor_artists.extend([ln, pt1, pt2])
+
+        if self._poly_pts:
+            self._update_poly_artist()
+
+    def _redraw_image(self, masks):
+        self._ax_img.cla()
+        self._ax_img.set_facecolor('black')
+        disp = np.asarray(self._disp) if self._disp is not None else None
+        if disp is None or disp.ndim != 2 or min(disp.shape) < 2:
+            self._ax_img.text(0.5, 0.5, 'No image available\n(point measurement)',
+                              ha='center', va='center', color='white', fontsize=9,
+                              transform=self._ax_img.transAxes)
+            self._ax_img.set_title('FOV image', fontsize=9)
+            self._ax_img.set_xticks([])
+            self._ax_img.set_yticks([])
+            return
+
+        if masks is not None and len(masks) > 0 and self._cursors:
+            colors_rgb = np.array([_hex_to_rgb01(c['color'])
+                                   for c in self._cursors])
+            mask_list = [masks[i] for i in range(len(self._cursors))]
+            pc = pseudo_color(*mask_list,
+                              intensity=self._disp,
+                              colors=colors_rgb)
+            self._ax_img.imshow(pc, origin='upper', interpolation='nearest')
+            counts = ', '.join(
+                f'C{i+1}:{int(masks[i].sum())}px'
+                for i in range(len(self._cursors)))
+            title = f"FOV overlay  ({counts})"
+        else:
+            self._ax_img.imshow(self._disp, cmap='inferno',
+                                origin='upper', interpolation='nearest')
+            title = 'FOV image  (place cursors on phasor to colourize)'
+
+        self._ax_img.set_title(title, fontsize=9)
+        self._ax_img.set_xlabel('X (px)', fontsize=8)
+        self._ax_img.set_ylabel('Y (px)', fontsize=8)
+        self._ax_img.tick_params(labelsize=7)
+
+    def overlay_fret_trajectory(self, traj):
+        self._fret_trajectory = traj
+        self._redraw_phasor()
+        self._redraw_cursors()
+        self._canvas.draw_idle()
+
+    def clear_fret_overlay(self):
+        self._fret_trajectory = None
+        self._peak_results = None
+        self._redraw_phasor()
+        self._redraw_cursors()
+        self._canvas.draw_idle()
+
+    def _redraw_fret_overlay(self):
+        if self._fret_trajectory is None:
+            return
+        traj = self._fret_trajectory
+        dg = traj['donor_g']
+        ds = traj['donor_s']
+        self._ax_ph.plot(dg, ds, color='cyan', lw=2, alpha=0.85, zorder=6)
+        self._ax_ph.plot(dg[0],  ds[0],  'co', ms=7, zorder=7)
+        self._ax_ph.plot(dg[-1], ds[-1], 'c^', ms=7, zorder=7)
+        if traj.get('acceptor_g') is not None:
+            ag = traj['acceptor_g']
+            as_ = traj['acceptor_s']
+            self._ax_ph.plot(ag, as_, color='magenta', lw=2, alpha=0.85, zorder=6)
+            self._ax_ph.plot(ag[0],  as_[0],  'mo', ms=7, zorder=7)
+            self._ax_ph.plot(ag[-1], as_[-1], 'm^', ms=7, zorder=7)
+
+    def overlay_peaks(self, peaks):
+        self._peak_results = peaks
+        self._redraw_phasor()
+        self._redraw_cursors()
+        self._canvas.draw_idle()
+
+    def _redraw_peaks_overlay(self):
+        if self._peak_results is None:
+            return
+        peaks = self._peak_results
+        for i in range(peaks['n_peaks']):
+            g = peaks['peak_g'][i]
+            s = peaks['peak_s'][i]
+            tau = float(peaks['tau_phase'][i])
+            self._ax_ph.plot(g, s, 'y*', ms=14, zorder=15,
+                             markeredgecolor='k', markeredgewidth=0.5)
+            self._ax_ph.text(g + 0.015, s + 0.015, f'{tau:.1f} ns',
+                             color='yellow', fontsize=8,
+                             fontweight='bold', zorder=16)
+
+    def _analyse(self):
+        if self._real is None or not self._cursors:
+            self._redraw_image(None)
+            self._canvas.draw_idle()
+            return
+
+        r = self._radius.get()
+        r_min = r * self._ratio.get()
+        n = len(self._cursors)
+
+        mask_list = []
+        for cur in self._cursors:
+            if cur.get('type', 'ellipse') == 'poly':
+                m = self._mask_from_polygon(cur['vertices'])
+            else:
+                cg = np.array([cur['center_g']])
+                cs = np.array([cur['center_s']])
+                m = mask_from_elliptic_cursor(
+                    self._real, self._imag, cg, cs,
+                    radius=r, radius_minor=r_min, angle='semicircle')
+                if m.ndim > self._real.ndim:
+                    m = m[0]
+            mask_list.append(m & self._valid)
+        masks = np.stack(mask_list, axis=0)
+
+        self._redraw_image(masks)
+
+        print(f"\n{'─' * 50}")
+        for ci in range(n):
+            m = masks[ci]
+            n_px = int(m.sum())
+            if n_px == 0:
+                print(f"  C{ci+1}: no pixels selected")
+                continue
+            tau_phi, _ = phasor_to_apparent_lifetime(
+                self._real[m], self._imag[m], self._freq)
+            med = float(np.nanmedian(tau_phi))
+            lo = float(np.nanpercentile(tau_phi, 5))
+            hi = float(np.nanpercentile(tau_phi, 95))
+            print(f"  C{ci+1} ({self._cursors[ci]['color']}):  "
+                  f"{n_px} px  |  τ_φ = {lo:.2f}-{hi:.2f} ns  "
+                  f"(median {med:.2f} ns)")
+
+        ellipse_curs = [c for c in self._cursors
+                        if c.get('type', 'ellipse') == 'ellipse']
+        if len(ellipse_curs) >= 2:
+            g0, s0 = ellipse_curs[0]['center_g'], ellipse_curs[0]['center_s']
+            g1, s1 = ellipse_curs[1]['center_g'], ellipse_curs[1]['center_s']
+            gi0, si0, gi1, si1 = phasor_semicircle_intersect(g0, s0, g1, s1)
+            if not np.isnan(float(gi0)):
+                tau1 = _tau_phi_scalar(gi0, si0, self._freq)
+                tau2 = _tau_phi_scalar(gi1, si1, self._freq)
+                combined = np.any(masks, axis=0)
+                frac = phasor_component_fraction(
+                    self._real[combined],
+                    self._imag[combined],
+                    np.array([float(gi0), float(gi1)]),
+                    np.array([float(si0), float(si1)]),
+                )
+                print(f"\n  ↳ 2-component (C1↔C2 ellipse):")
+                print(f"     τ₁ = {tau1:.3f} ns  "
+                      f"τ₂ = {tau2:.3f} ns  "
+                      f"mean frac(C1) = {float(np.mean(frac)):.3f}")
+
+        print(f"{'─' * 50}")
+        self._canvas.draw_idle()
+
+    def _mask_from_polygon(self, vertices):
+        verts = np.asarray(vertices, dtype=float)
+        pts = np.column_stack([self._real.ravel(), self._imag.ravel()])
+        inside = MplPath(verts).contains_points(pts)
+        return inside.reshape(self._real.shape)
+
+    def _on_click(self, event):
+        if self._real is None:
+            return
+        if self._toolbar.mode != '':
+            return
+
+        if event.button == 3 and self._mode_var.get() == 'poly':
+            self._on_click_poly(event)
+            return
+
+        if event.button != 1:
+            return
+        if event.inaxes is not self._ax_ph:
+            return
+        if event.xdata is None or event.ydata is None:
+            return
+
+        if not self._poly_pts:
+            hit = self._hit_test(event.xdata, event.ydata)
+            if hit is not None:
+                self._drag_idx = hit
+                self._drag_last = (event.xdata, event.ydata)
+                self._status_var.set(f"Dragging C{hit + 1} - release to drop.")
+                return
+
+        if self._mode_var.get() == 'poly':
+            self._on_click_poly(event)
+        else:
+            self._on_click_ellipse(event)
+
+    def _on_click_ellipse(self, event):
+        if len(self._cursors) >= self.max_cursors:
+            self._status_var.set(
+                f"Max {self.max_cursors} cursors - clear or undo first.")
+            return
+        idx = len(self._cursors) % len(_COLORS)
+        self._cursors.append(dict(
+            type='ellipse',
+            center_g=event.xdata,
+            center_s=event.ydata,
+            color=_COLORS[idx]))
+        self._redraw_cursors()
+        self._analyse()
+        self._notify_change()
+        self._status_var.set(
+            f"{len(self._cursors)} cursor(s)  |  "
+            f"G={event.xdata:.4f}  S={event.ydata:.4f}")
+
+    def _on_click_poly(self, event):
+        if event.button == 3:
+            if len(self._poly_pts) >= 3:
+                self._commit_polygon()
+            elif self._poly_pts:
+                self._cancel_polygon()
+            return
+        if event.button != 1:
+            return
+        if event.inaxes is not self._ax_ph:
+            return
+        if event.xdata is None or event.ydata is None:
+            return
+        if not self._poly_pts and len(self._cursors) >= self.max_cursors:
+            self._status_var.set(
+                f"Max {self.max_cursors} cursors - clear or undo first.")
+            return
+        self._poly_pts.append((event.xdata, event.ydata))
+        self._update_poly_artist()
+        n = len(self._poly_pts)
+        self._status_var.set(
+            f"Polygon: {n} vert{'ex' if n == 1 else 'ices'}  "
+            f"- right-click or Enter to close (need ≥ 3)")
+
+    def _on_motion(self, event):
+
+        if self._drag_idx is not None:
+            if event.inaxes is self._ax_ph and event.xdata is not None:
+                self._do_drag(event.xdata, event.ydata)
+            return
+
+        if (event.inaxes is self._ax_ph and event.xdata is not None
+                and not self._poly_pts):
+            hit = self._hit_test(event.xdata, event.ydata)
+            self._canvas.get_tk_widget().configure(
+                cursor='fleur' if hit is not None else '')
+
+        if not self._poly_pts:
+            return
+        if event.inaxes is not self._ax_ph:
+            return
+        if event.xdata is None or event.ydata is None:
+            return
+        self._update_poly_artist(live_pt=(event.xdata, event.ydata))
+        self._canvas.draw_idle()
+
+    def _on_release(self, event):
+        if self._drag_idx is None:
+            return
+        idx = self._drag_idx
+
+        if event.inaxes is self._ax_ph and event.xdata is not None:
+            self._do_drag(event.xdata, event.ydata)
+        self._drag_idx = None
+        self._canvas.get_tk_widget().configure(cursor='')
+        self._redraw_phasor()
+        self._redraw_cursors()
+        self._analyse()
+        self._notify_change()
+        self._status_var.set(
+            f"C{idx + 1} moved.  {len(self._cursors)} cursor(s) active.")
+
+    def _do_drag(self, g: float, s: float):
+        dx = g - self._drag_last[0]
+        dy = s - self._drag_last[1]
+        cur = self._cursors[self._drag_idx]
+        if cur.get('type', 'ellipse') == 'poly':
+            cur['vertices'] = [(v[0] + dx, v[1] + dy)
+                               for v in cur['vertices']]
+        else:
+            cur['center_g'] += dx
+            cur['center_s'] += dy
+        self._drag_last = (g, s)
+        self._redraw_cursors()
+        self._canvas.draw_idle()
+
+    def _hit_test(self, g, s):
+        r = self._radius.get()
+        for i, cur in enumerate(self._cursors):
+            if cur.get('type', 'ellipse') == 'poly':
+                verts = np.asarray(cur['vertices'], dtype=float)
+                if MplPath(verts).contains_point((g, s)):
+                    return i
+            else:
+                tol = max(r * 1.2, 0.04)
+                if np.hypot(g - cur['center_g'], s - cur['center_s']) < tol:
+                    return i
+        return None
+
+    def _on_key(self, event):
+        if event.key == 'escape':
+            self._cancel_polygon()
+        elif event.key in ('enter', 'return'):
+            if len(self._poly_pts) >= 3:
+                self._commit_polygon()
+
+    def _on_mode_change(self):
+        if self._mode_var.get() == 'poly':
+            self._ellipse_ctrl_frame.pack_forget()
+            self._status_var.set(
+                'Polygon mode: left-click to add vertices, '
+                'right-click or Enter to close (need ≥ 3), Esc to cancel.')
+        else:
+            self._cancel_polygon()
+            self._ellipse_ctrl_frame.pack(side='left')
+            self._status_var.set('Ellipse mode: click phasor to place cursor.')
+
+    def _update_poly_artist(self, live_pt=None):
+        if self._poly_line is not None:
+            for art in self._poly_line:
+                try:
+                    art.remove()
+                except Exception:
+                    pass
+            self._poly_line = None
+        pts = list(self._poly_pts)
+        if live_pt is not None:
+            pts = pts + [live_pt]
+        if not pts:
+            return
+        idx = len(self._cursors) % len(_COLORS)
+        col = _COLORS[idx]
+        artists = []
+        if len(pts) >= 2:
+            xs = [p[0] for p in pts] + [pts[0][0]]
+            ys = [p[1] for p in pts] + [pts[0][1]]
+            (line,) = self._ax_ph.plot(xs, ys, color=col, lw=1.5,
+                                        linestyle='--', alpha=0.85, zorder=9)
+            artists.append(line)
+        for p in self._poly_pts:
+            (dot,) = self._ax_ph.plot(p[0], p[1], 'o', color=col,
+                                       ms=4, zorder=10)
+            artists.append(dot)
+        if live_pt is not None:
+            (tip,) = self._ax_ph.plot(live_pt[0], live_pt[1], '+',
+                                       color=col, ms=8, zorder=10)
+            artists.append(tip)
+        self._poly_line = artists
+
+    def _commit_polygon(self):
+        if len(self._poly_pts) < 3:
+            return
+        if self._poly_line is not None:
+            for art in self._poly_line:
+                try:
+                    art.remove()
+                except Exception:
+                    pass
+            self._poly_line = None
+        idx = len(self._cursors) % len(_COLORS)
+        self._cursors.append(dict(
+            type='poly',
+            vertices=list(self._poly_pts),
+            color=_COLORS[idx]))
+        self._poly_pts.clear()
+        self._redraw_cursors()
+        self._analyse()
+        self._notify_change()
+        n = len(self._cursors)
+        self._status_var.set(
+            f"{n} region(s)  |  polygon C{n} committed. "
+            f"Left-click to start another.")
+
+    def _cancel_polygon(self):
+        if self._poly_line is not None:
+            for art in self._poly_line:
+                try:
+                    art.remove()
+                except Exception:
+                    pass
+            self._poly_line = None
+        self._poly_pts.clear()
+        self._canvas.draw_idle()
+        self._status_var.set(
+            'Polygon cancelled. Left-click to start a new one.')
+
+    def _build_cursor_union_mask(self):
+        """Return a boolean (Y×X) union mask for all current cursors.
+
+        Returns None if there are no cursors or no phasor data loaded.
+        """
+        if self._real is None or not self._cursors:
+            return None
+        r = self._radius.get()
+        r_min = r * self._ratio.get()
+        union = np.zeros_like(self._real, dtype=bool)
+        for cur in self._cursors:
+            if cur.get('type', 'ellipse') == 'poly':
+                m = self._mask_from_polygon(cur['vertices'])
+            else:
+                cg = np.array([cur['center_g']])
+                cs = np.array([cur['center_s']])
+                m = mask_from_elliptic_cursor(
+                    self._real, self._imag, cg, cs,
+                    radius=r, radius_minor=r_min, angle='semicircle')
+                if m.ndim > self._real.ndim:
+                    m = m[0]
+            union |= (m & self._valid)
+        return union
+
+    def _fit_cursor_decay(self):
+        from tkinter import messagebox
+        from pathlib import Path
+        from flimkit.UI.roi_tools import _ask_roi_fit_options
+
+        if self._real is None:
+            messagebox.showwarning('No Phasor Data',
+                                   'Load a PTU file and compute phasors first.')
+            return
+        if not self._cursors:
+            messagebox.showwarning('No Cursors',
+                                   'Place at least one cursor on the phasor plot first.')
+            return
+        if not self._ptu_path or not Path(self._ptu_path).exists():
+            messagebox.showwarning('No PTU',
+                                   'PTU file path not found.\n'
+                                   'Re-load the phasor data and try again.')
+            return
+        if not callable(getattr(self, 'run_with_progress', None)) or \
+           not callable(getattr(self, 'get_fit_params', None)):
+            messagebox.showwarning('Not Ready',
+                                   'Fitting callbacks are not wired.\n'
+                                   'Run a whole-FOV fit first to initialise parameters.')
+            return
+
+        params = self.get_fit_params()
+        params['ptu_path'] = self._ptu_path
+        params['channel'] = self._channel
+
+        params = _ask_roi_fit_options(params)
+        if params is None:
+            return
+
+        ptu_path = self._ptu_path
+        channel = self._channel
+        irf_cached = params.get('irf_prompt') or params.get('irf')
+        n_cursors = len(self._cursors)
+        label = (f"Cursor {self._cursors[0]['color']}"
+                       if n_cursors == 1
+                       else f"{n_cursors} cursors (union)")
+
+        union_mask_snapshot = self._build_cursor_union_mask()
+        if union_mask_snapshot is None or not union_mask_snapshot.any():
+            messagebox.showwarning('Empty Selection',
+                                   'The current cursor(s) select no valid pixels.')
+            return
+
+        def task(progress_callback=None, cancel_event=None):
+            import numpy as _np
+            from flimkit.formats import FLIMFile
+            from flimkit.FLIM.fitters import fit_summed
+
+            ptu = FLIMFile(ptu_path, verbose=False)
+            n_bins = ptu.n_bins
+            tcspc_res = ptu.tcspc_res
+
+            if progress_callback:
+                progress_callback(1, 4)
+
+            native_h, native_w = ptu.n_y, ptu.n_x
+            ph_h,     ph_w     = union_mask_snapshot.shape
+            if native_h % ph_h != 0 or native_w % ph_w != 0:
+                raise ValueError(
+                    f"PTU native size {native_h}×{native_w} is not an integer "
+                    f"multiple of phasor size {ph_h}×{ph_w}.")
+            inferred_binning = native_h // ph_h
+            stack = ptu.pixel_stack(channel=channel, binning=inferred_binning)
+            gated_decay = stack[union_mask_snapshot].sum(axis=0).astype(float)
+            if gated_decay.max() == 0:
+                raise ValueError('Cursor gate contains no photons.')
+
+            if progress_callback:
+                progress_callback(2, 4)
+
+            irf_prompt = irf_cached
+            if (irf_prompt is None
+                    or not hasattr(irf_prompt, '__len__')
+                    or len(irf_prompt) != n_bins):
+                from flimkit.FLIM.irf_tools import gaussian_irf
+                peak_bin = int(_np.argmax(gated_decay))
+                fwhm_bins = max(1.0, 0.2e-9 / tcspc_res)
+                irf_prompt = gaussian_irf(n_bins, peak_bin, fwhm_bins)
+                irf_source = 'gaussian (no IRF cached)'
+            else:
+                irf_source = 'from main fit'
+
+            if progress_callback:
+                progress_callback(3, 4)
+
+            popt, summary = fit_summed(
+                decay = gated_decay,
+                tcspc_res = tcspc_res,
+                n_bins = n_bins,
+                irf_prompt = irf_prompt,
+                has_tail = False,
+                fit_bg = True,
+                fit_sigma = False,
+                n_exp = params['n_exp'],
+                tau_min_ns = params['tau_min'],
+                tau_max_ns = params['tau_max'],
+                cost_function = params['cost_function'],
+            )
+
+            if progress_callback:
+                progress_callback(4, 4)
+
+            return {
+                'region_name': label,
+                'region_id':   -1,
+                'region_ids':  [],
+                'decay':       gated_decay,
+                'time_ns':     ptu.time_ns,
+                'irf_prompt':  irf_prompt,
+                'irf_source':  irf_source,
+                'popt':        popt,
+                'summary':     summary,
+                'n_exp':       params['n_exp'],
+            }
+
+        def on_done(result):
+            if result is None:
+                return
+            self._last_fit_result = result
+            from flimkit.UI.roi_tools import _show_roi_fit_result_standalone
+            _show_roi_fit_result_standalone(result)
+
+        self.run_with_progress(
+            task_fn = task,
+            task_name = f"Fitting cursor-gated decay ({label})...",
+            on_done = on_done,
+        )
+
+    def _view_last_fit_result(self):
+        from tkinter import messagebox
+        if self._last_fit_result is None:
+            messagebox.showinfo(
+                'No Fit Cached',
+                'No fit result cached yet.\n'
+                'Run ⚗ Fit Cursor Decay first.')
+            return
+        from flimkit.UI.roi_tools import _show_roi_fit_result_standalone
+        _show_roi_fit_result_standalone(self._last_fit_result)
+
+    def _on_clear(self):
+        if self._real is None:
+            return
+        self._cursors.clear()
+        self._fret_trajectory = None
+        self._peak_results = None
+        self._poly_pts.clear()
+        if self._poly_line is not None:
+            for art in self._poly_line:
+                try:
+                    art.remove()
+                except Exception:
+                    pass
+            self._poly_line = None
+        self._redraw_phasor()
+        self._redraw_image(masks=None)
+        self._canvas.draw_idle()
+        self._notify_change()
+        self._status_var.set('Cleared.  Click phasor to place cursors.')
+
+    def _on_undo(self):
+        if self._real is None:
+            return
+        if self._poly_pts:
+            self._poly_pts.pop()
+            if self._poly_pts:
+                self._update_poly_artist()
+            else:
+                if self._poly_line is not None:
+                    for art in self._poly_line:
+                        try:
+                            art.remove()
+                        except Exception:
+                            pass
+                    self._poly_line = None
+            self._canvas.draw_idle()
+            n = len(self._poly_pts)
+            self._status_var.set(
+                f"Polygon: {n} vert{'ex' if n == 1 else 'ices'}  "
+                f"(vertex removed).")
+            return
+        if not self._cursors:
+            return
+        self._cursors.pop()
+        self._redraw_phasor()
+        self._redraw_cursors()
+        self._analyse()
+        self._notify_change()
+        self._status_var.set(
+            f"{len(self._cursors)} cursor(s)  |  last cursor removed.")
+
+    def _notify_change(self):
+        if self.on_change is not None:
+            try:
+                self.on_change(self)
+            except Exception as e:
+                print(f"[PhasorViewPanel] on_change callback error: {e}")
+
+    def _on_param_change(self):
+        if self._cursors and self._real is not None:
+            self._redraw_phasor()
+            self._redraw_cursors()
+            self._analyse()
+            self._notify_change()
+
+    def _on_save(self):
+        if self._real is None:
+            messagebox.showwarning('No data', 'No phasor data loaded yet.')
+            return
+        path = filedialog.asksaveasfilename(
+            title='Save phasor session',
+            defaultextension='.npz',
+            initialfile='phasor_session.npz',
+            filetypes=[('NumPy archive', '*.npz'), ('All files', '*')])
+        if not path:
+            return
+        try:
+            from flimkit.phasor_launcher import save_session
+            sd = self.get_session_dict()
+            save_session(
+                path,
+                real_cal=sd['real_cal'],
+                imag_cal=sd['imag_cal'],
+                mean=sd['mean'],
+                frequency=sd['frequency'],
+                cursors=sd['cursors'],
+                params=sd['params'],
+                display_image=sd.get('display_image'),
+            )
+            self._status_var.set(f"Session saved → {Path(path).name}")
+        except Exception as exc:
+            messagebox.showerror('Save failed', str(exc))