flimkit 0.12.0__py3-none-any.whl

flimkit/utils/misc.py

@@ -0,0 +1,111 @@
+import os
+import logging
+
+def setup_loggers(log_dir: str = '.', log_prefix: str = 'run'):
+    os.makedirs(log_dir, exist_ok=True)
+    loggers = {}
+    
+    # Main run logger
+    run_logger = logging.getLogger('run')
+    run_logger.setLevel(logging.INFO)
+    run_fh = logging.FileHandler(os.path.join(log_dir, f'{log_prefix}.log'))
+    run_fh.setLevel(logging.INFO)
+    run_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+    run_fh.setFormatter(run_formatter)
+    run_logger.handlers = [run_fh]
+    loggers['run'] = run_logger
+
+    # Error logger
+    error_logger = logging.getLogger('error')
+    error_logger.setLevel(logging.ERROR)
+    error_fh = logging.FileHandler(os.path.join(log_dir, 'error.log'))
+    error_fh.setLevel(logging.ERROR)
+    error_fh.setFormatter(run_formatter)
+    error_logger.handlers = [error_fh]
+    loggers['error'] = error_logger
+
+    # Warning logger
+    warning_logger = logging.getLogger('warning')
+    warning_logger.setLevel(logging.WARNING)
+    warning_fh = logging.FileHandler(os.path.join(log_dir, 'warning.log'))
+    warning_fh.setLevel(logging.WARNING)
+    warning_fh.setFormatter(run_formatter)
+    warning_logger.handlers = [warning_fh]
+    loggers['warning'] = warning_logger
+
+    return loggers
+
+def print_summary(summary: dict, strategy: str, n_exp: int):
+    s = summary
+    tcspc_res = s['tcspc_res']
+    is_dist = 'tau_centers_ns' in s
+    is_tail = s.get('fit_model') == 'tail'
+
+    print(f"\n{'─'*60}")
+    if is_tail:
+        print(f"  Fit: {n_exp}-exp tail (no reconvolution)")
+        print(f"{'─'*60}")
+        for i, (tau, amp, frac, inten, ifrac) in enumerate(
+                zip(s['taus_ns'], s['amps'], s['fractions'],
+                    s['intensities'], s['intensity_fractions'])):
+            print(f"  τ{i+1} = {tau:8.4f} ns   A{i+1} = {amp:.3e}   "
+                  f"f{i+1} = {frac:.4f}   I{i+1} = {inten:.3e} ({ifrac:.4f})")
+        print(f"  A_sum = {s['a_sum']:.3e}   I_sum = {s['i_sum']:.3e} cts")
+    elif is_dist:
+        width_label = 'σ' if s['dist_type'] == 'gaussian' else 'Γ'
+        print(f"  Fit: {s['n_components']}-component {s['dist_type']} dist | IRF: {strategy}")
+        print(f"{'─'*60}")
+        for i, (tau_c, w, fwhm, amp, frac) in enumerate(
+                zip(s['tau_centers_ns'], s['widths_ns'], s['fwhms_ns'],
+                    s['amps'], s['fractions'])):
+            print(f"  τ_c{i+1} = {tau_c:7.4f} ns   {width_label}{i+1} = {w:.4f} ns   "
+                  f"FWHM = {fwhm:.4f} ns   f{i+1} = {frac:.4f}")
+    else:
+        print(f"  Fit: {n_exp}-exp | IRF: {strategy}")
+        print(f"{'─'*60}")
+        for i, (tau, amp, frac) in enumerate(
+                zip(s['taus_ns'], s['amps'], s['fractions'])):
+            print(f"  τ{i+1} = {tau:8.4f} ns   α{i+1} = {amp:.3e}   f{i+1} = {frac:.4f}")
+
+    print(f"  τ_mean (amplitude-weighted)  = {s['tau_mean_amp_ns']:.4f} ns")
+    print(f"  τ_mean (intensity-weighted)  = {s['tau_mean_int_ns']:.4f} ns")
+    print(f"  bg (fitted, Tail Offset)     = {s['bg_fit']:.2f} cts/bin")
+    if is_tail:
+        print(f"  t0 (lifetime offset)         = {s['t0_ns']:.4f} ns")
+        print(f"  Fit window                   = {s['fit_window_ns'][0]:.2f}-"
+              f"{s['fit_window_ns'][1]:.2f} ns")
+    else:
+        print(f"  IRF shift                    = {s['irf_shift_bins']:.3f} bins "
+              f"({s['irf_shift_bins'] * tcspc_res * 1e12:.1f} ps)")
+        print(f"  IRF σ (prompt broadening)    = {s['irf_sigma_bins']:.3f} bins")
+        print(f"  IRF FWHM (effective)         = {s['irf_fwhm_eff_ns']:.4f} ns")
+    if not is_dist and not is_tail and s.get('tail_amp', 0) > 0:
+        print(f"  IRF tail amp                 = {s['tail_amp']:.4f}")
+        print(f"  IRF tail τ                   = {s['tail_tau_ns']:.3f} ns")
+        if s['tail_tau_ns'] > 18:
+            print(f"   tail τ near upper bound - consider acquiring a scatter PTU")
+    p_val = s.get('p_val')
+    p_str = f", p={p_val:.4f}" if p_val is not None else ""
+    print(f"  χ²_r = {s['reduced_chi2']:.4f}  "
+          f"(χ²={s['chi2']:.1f}, DoF={s['dof']}{p_str})  [full window, Neyman]")
+    print(f"  χ²_r = {s['reduced_chi2_pearson']:.4f}  "
+          f"[full window, Pearson]")
+    if not is_tail:
+        print(f"  χ²_r = {s['reduced_chi2_tail']:.4f}  "
+              f"(tail only, t>{s['tail_start_bin']*tcspc_res*1e9:.2f} ns)  [Neyman]")
+        print(f"  χ²_r = {s['reduced_chi2_tail_pearson']:.4f}  "
+              f"(tail only, t>{s['tail_start_bin']*tcspc_res*1e9:.2f} ns)  [Pearson]")
+    if p_val is not None:
+        flag = '' if 0.001 < p_val < 0.999 else ''
+        print(f"  {flag} Optimizer: {s['optimizer_msg']}")
+    else:
+        print(f"  Optimizer: {s['optimizer_msg']}")
+
+def check_full_path(path):
+    if os.path.isabs(path) == True:
+        return path
+    else:
+        if os.path.isabs(os.getcwd() + '/' + path) == True:
+            return os.getcwd() + '/' + path
+        else:
+            raise Exception('Path not found')

flimkit/utils/plotting.py

@@ -0,0 +1,190 @@
+import numpy as np
+import matplotlib
+import matplotlib.pyplot as plt
+import matplotlib.gridspec as gridspec
+from matplotlib.colors import LinearSegmentedColormap
+from flimkit.configs import FLIM_CMAP
+
+# Use non-interactive 'Agg' backend for thread-safe file saving
+# This prevents segfaults when matplotlib operations happen in worker threads
+try:
+    matplotlib.use('Agg', force=True)
+except Exception:
+    pass
+
+
+# rcParams for file exports - overrides any dark-theme globals set by the GUI
+_EXPORT_RC = {
+    'text.color':       'black',
+    'axes.labelcolor':  'black',
+    'xtick.color':      'black',
+    'ytick.color':      'black',
+    'axes.titlecolor':  'black',
+}
+
+
+def plot_summed(decay, summary, ptu, xlsx, n_exp, strategy, out_prefix,
+               irf_prompt=None):
+    plt.rcParams.update({'figure.dpi': 130, 'font.size': 10,
+                          'axes.spines.top': False, 'axes.spines.right': False,
+                          **_EXPORT_RC})
+    s    = summary
+    t_ns = np.arange(ptu.n_bins) * ptu.tcspc_res * 1e9
+    fs, fe = s['fit_window_bins']
+
+    fig = plt.figure(figsize=(12, 7))
+    gs  = gridspec.GridSpec(2, 3, height_ratios=[3, 1], hspace=0.08, wspace=0.35)
+    ax1 = fig.add_subplot(gs[0, :2])
+    ax2 = fig.add_subplot(gs[1, :2], sharex=ax1)
+    ax3 = fig.add_subplot(gs[0,  2])
+    ax4 = fig.add_subplot(gs[1,  2])
+    ax4.axis('off')
+
+    ax1.semilogy(t_ns, np.clip(decay, 1, None), '.', color='#aaa',
+                 ms=2, rasterized=True, label='PTU data')
+
+    # IRF - scale to ~10% of decay peak for visibility on log axis.
+    # Mask bins below 0.1% of IRF peak so zeros don't pollute the log axis.
+    if irf_prompt is not None:
+        scale      = decay.max() * 0.1 / irf_prompt.max()
+        irf_scaled = irf_prompt * scale
+        irf_mask   = irf_scaled > irf_scaled.max() * 1e-3
+        t_irf_plot = t_ns[irf_mask]
+        v_irf_plot = irf_scaled[irf_mask]
+        ax1.semilogy(t_irf_plot, v_irf_plot,
+                     color='#f4a261', lw=1.5, ls='-.', alpha=0.85,
+                     label=f"IRF (×{scale:.1e})")
+
+    if xlsx is not None and xlsx.get('fit_t') is not None and xlsx.get('fit_c') is not None:
+        ax1.semilogy(xlsx['fit_t'], np.clip(xlsx['fit_c'], 1, None),
+                     'b-', lw=1.1, alpha=0.55, label='FLIM microscope fit')
+    is_tail = s.get('fit_model') == 'tail'
+    ax1.semilogy(t_ns, np.clip(s['model'], 1, None), 'r-', lw=2,
+                 label=f"{n_exp}-exp {'tail' if is_tail else 'reconv.'}")
+    ax1.set_xlim(0, min(t_ns[-1], 22))
+    ax1.set_ylabel('Counts')
+    ax1.legend(fontsize=8, loc='upper right')
+    ax1.set_title(f"Summed Decay - {n_exp}-exp "
+                  f"{'tail fit (no IRF)' if is_tail else '| IRF: ' + strategy}",
+                  fontweight='bold')
+    ax1.axvspan(s['fit_window_ns'][0], s['fit_window_ns'][1],
+                alpha=0.06, color='green')
+    plt.setp(ax1.get_xticklabels(), visible=False)
+
+    ax2.axhline(0, color='k', lw=0.8, ls='--')
+    ax2.fill_between(t_ns[fs:fe], np.clip(s['residuals'][fs:fe], -5, 5),
+                     alpha=0.5, color='#457b9d')
+    ax2.set_ylim(-5, 5)
+    ax2.set_xlim(0, min(t_ns[-1], 22))
+    ax2.set_xlabel('Time (ns)')
+    ax2.set_ylabel('W. Residuals')
+
+    rv = np.clip(s['residuals'][fs:fe], -5, 5)
+    ax3.hist(rv, bins=60, color='#2a9d8f', edgecolor='none', alpha=0.85)
+    ax3.axvline(0, color='k', lw=0.8)
+    ax3.set_xlabel('Weighted residual')
+    ax3.set_ylabel('Frequency')
+    ax3.set_title(f"Residuals  μ={rv.mean():.3f}  σ={rv.std():.3f}")
+
+    p_val = s.get('p_val')
+    p_line = f"p    = {p_val:.4f}" if p_val is not None else ""
+    lines = [f"χ²_r = {s['reduced_chi2_pearson']:.4f}  (Pearson)",
+             f"χ²_r(tail) = {s['reduced_chi2_tail_pearson']:.4f}  (Pearson)",
+             p_line,
+             f"bg   = {s['bg_fit']:.1f} cts/bin",
+             f"τ_mean(int) = {s['tau_mean_int_ns']:.4f} ns",
+             f"τ_mean(amp) = {s['tau_mean_amp_ns']:.4f} ns",
+             (f"t0 = {s['t0_ns']:.4f} ns" if is_tail
+              else f"IRF FWHM(eff) = {s['irf_fwhm_eff_ns']:.4f} ns"), '']
+    if 'tau_centers_ns' in s:
+        width_label = 'σ' if s['dist_type'] == 'gaussian' else 'Γ'
+        for i, (tau_c, w, frac) in enumerate(
+                zip(s['tau_centers_ns'], s['widths_ns'], s['fractions'])):
+            lines.append(f"τ_c{i+1}={tau_c:.4f} ns  {width_label}={w:.4f} ns  f{i+1}={frac:.4f}")
+    else:
+        for i, (tau, frac) in enumerate(zip(s['taus_ns'], s['fractions'])):
+            lines.append(f"τ{i+1}={tau:.4f} ns  f{i+1}={frac:.4f}")
+    ax4.text(0.05, 0.97, '\n'.join(lines), transform=ax4.transAxes,
+             va='top', fontsize=9, family='monospace',
+             bbox=dict(boxstyle='round,pad=0.4', fc='#f7f7f7', alpha=0.9))
+
+    plt.suptitle(f"FLIM {'Tail' if is_tail else 'Reconvolution'} Fit - "
+                 f"FLIM microscope / PicoHarp",
+                 fontsize=12, fontweight='bold')
+    out = f"{out_prefix}_summed_{n_exp}exp.png"
+    plt.savefig(out, dpi=150, bbox_inches='tight')
+    plt.close()
+    print(f"  Saved: {out}")
+
+
+def plot_pixel_maps(maps, n_exp, out_prefix, binning=1):
+    fig, axes = plt.subplots(2, 3, figsize=(15, 9))
+    fig.patch.set_facecolor('#111')
+
+    def _show(ax, data, title, cmap='viridis', vmin=None, vmax=None, unit='ns'):
+        ax.set_facecolor('#111')
+        if data is None:
+            ax.set_visible(False); return
+        valid = data[np.isfinite(data) & (data > 0)]
+        if len(valid) == 0:
+            ax.set_visible(False); return
+        vlo = vmin if vmin is not None else np.percentile(valid, 2)
+        vhi = vmax if vmax is not None else np.percentile(valid, 98)
+        im  = ax.imshow(data, cmap=cmap, vmin=vlo, vmax=vhi, interpolation='nearest')
+        cb  = plt.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+        cb.set_label(unit, color='white')
+        cb.ax.yaxis.set_tick_params(color='white')
+        plt.setp(cb.ax.yaxis.get_ticklabels(), color='white')
+        ax.set_title(title, color='white', fontweight='bold')
+        ax.set_axis_off()
+
+    _show(axes[0, 0], maps['intensity'],    'Intensity',         'hot',     unit='photons')
+    _show(axes[0, 1], maps['tau_mean_int'], 'τ_mean (int.-wt.)', FLIM_CMAP)
+    _show(axes[0, 2], maps['tau_mean_amp'], 'τ_mean (amp.-wt.)', FLIM_CMAP)
+    for i in range(min(n_exp, 3)):
+        _show(axes[1, i], maps.get(f"frac_{i+1}"), f"f{i+1}",
+              'viridis', vmin=0, vmax=1, unit='fraction')
+
+    plt.suptitle(f"FLIM Pixel Maps - {n_exp}-exp (τ fixed, α free)  "
+                 f"binning={binning}×{binning}",
+                 color='white', fontsize=12, fontweight='bold')
+    plt.tight_layout()
+    out = f"{out_prefix}_pixelmaps_{n_exp}exp.png"
+    plt.savefig(out, dpi=150, bbox_inches='tight', facecolor='#111')
+    plt.close()
+    print(f"  Saved: {out}")
+
+
+def plot_lifetime_histogram(maps, n_exp, out_prefix):
+    plt.rcParams.update(_EXPORT_RC)
+    tau = maps['tau_mean_int']
+    wt  = maps['intensity']
+    ok  = np.isfinite(tau) & (wt > 0)
+    if ok.sum() < 2:
+        return
+    tau_ok = tau[ok]
+    data_range = float(tau_ok.max() - tau_ok.min())
+    # Skip histogram if range is too narrow to bin meaningfully
+    if data_range < 1e-12:
+        print(f"  Skipping lifetime histogram - τ range too narrow ({tau_ok[0]:.4f} ns)")
+        return
+    mu_w = np.average(tau_ok, weights=wt[ok])
+    n_bins = min(100, max(2, int(np.sqrt(ok.sum()))))
+    # Clamp bins so each bin spans at least ~1e-12
+    max_bins = max(1, int(data_range / 1e-12))
+    n_bins = min(n_bins, max_bins)
+    fig, ax = plt.subplots(figsize=(7, 4))
+    ax.hist(tau_ok, bins=n_bins, weights=wt[ok], color='#2a9d8f', alpha=0.85)
+    ax.axvline(mu_w, color='red', ls='--', lw=1.5,
+               label=f"Weighted mean = {mu_w:.3f} ns")
+    ax.set_xlabel('τ_mean (intensity-weighted) [ns]')
+    ax.set_ylabel('Photon-weighted frequency')
+    ax.set_title(f"Lifetime Distribution - {n_exp}-exp", fontweight='bold')
+    ax.legend()
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+    plt.tight_layout()
+    out = f"{out_prefix}_lifetime_hist_{n_exp}exp.png"
+    plt.savefig(out, dpi=150, bbox_inches='tight')
+    plt.close()
+    print(f"  Saved: {out}")

flimkit/utils/roi.py

@@ -0,0 +1,370 @@
+import copy
+import json
+from typing import Any, List, Dict, Optional, Tuple
+import numpy as np
+
+_COLORS = [
+    '#FF6B6B',
+    '#4ECDC4',
+    '#FFE66D',
+    '#95E1D3',
+    '#C7CEEA',
+    '#FF8C42',
+]
+
+class RoiManager:
+
+    def __init__(self):
+        self.regions: List[Dict] = []
+        self._next_id = 0
+        self._selected_id: Optional[int] = None
+
+    def add_region(self, name: str, tool_type: str, coords: List[List[float]],
+                   color_idx: Optional[int] = None) -> int:
+        if tool_type not in ('rect', 'ellipse', 'polygon', 'freehand'):
+            raise ValueError(f'Invalid tool_type: {tool_type}')
+        if not coords or len(coords) == 0:
+            raise ValueError('coords cannot be empty')
+        if color_idx is None:
+            color_idx = len(self.regions) % len(_COLORS)
+        region = {
+            'id': self._next_id,
+            'name': name,
+            'tool': tool_type,
+            'coords': [[float(x), float(y)] for x, y in coords],
+            'color_idx': int(color_idx),
+        }
+        self.regions.append(region)
+        self._next_id += 1
+        return region['id']
+
+    def remove_region(self, region_id: int) -> bool:
+        for i, r in enumerate(self.regions):
+            if r['id'] == region_id:
+                self.regions.pop(i)
+                if self._selected_id == region_id:
+                    self._selected_id = None
+                return True
+        return False
+
+    def get_region(self, region_id: int) -> Optional[Dict]:
+        for r in self.regions:
+            if r['id'] == region_id:
+                return r
+        return None
+
+    def update_region(self, region_id: int, **kwargs) -> bool:
+        for r in self.regions:
+            if r['id'] == region_id:
+                if 'coords' in kwargs:
+                    r['coords'] = [[float(x), float(y)] for x, y in kwargs['coords']]
+                if 'name' in kwargs:
+                    r['name'] = str(kwargs['name'])
+                if 'color_idx' in kwargs:
+                    r['color_idx'] = int(kwargs['color_idx'])
+                if 'tool' in kwargs:
+                    r['tool'] = str(kwargs['tool'])
+                return True
+        return False
+
+    def select_region(self, region_id: Optional[int]) -> None:
+        self._selected_id = region_id
+
+    def get_selected_id(self) -> Optional[int]:
+        return self._selected_id
+
+    def get_all_regions(self) -> List[Dict]:
+        return self.regions
+
+    def clear_all(self) -> None:
+        self.regions = []
+        self._selected_id = None
+        self._next_id = 0
+
+    def to_json(self) -> str:
+        data = {
+            'regions': self.regions,
+            'next_id': self._next_id,
+        }
+        return json.dumps(data, default=str)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> 'RoiManager':
+        manager = cls()
+        try:
+            data = json.loads(json_str)
+            manager.regions = data.get('regions', [])
+            manager._next_id = data.get('next_id', len(manager.regions))
+        except (json.JSONDecodeError, ValueError):
+            pass
+        return manager
+
+    @staticmethod
+    def _geojson_coordinates(values: Any, minimum: int) -> List[List[float]]:
+        if not isinstance(values, list):
+            raise ValueError('GeoJSON coordinates must be a list')
+        coords = []
+        for point in values:
+            if not isinstance(point, (list, tuple)) or len(point) < 2:
+                raise ValueError('GeoJSON coordinates must contain [x, y] points')
+            x, y = float(point[0]), float(point[1])
+            if not np.isfinite(x) or not np.isfinite(y):
+                raise ValueError('GeoJSON coordinates must be finite')
+            coords.append([x, y])
+        if len(coords) < minimum:
+            raise ValueError(f'GeoJSON geometry requires at least {minimum} points')
+        return coords
+
+    @staticmethod
+    def _outer_boundary(ring: List[List[float]]) -> Optional[List[List[float]]]:
+        from shapely.geometry import MultiPolygon, Polygon
+        polygon = Polygon(ring)
+        if polygon.is_valid:
+            return None
+        repaired = polygon.buffer(0)
+        if isinstance(repaired, MultiPolygon):
+            if not repaired.geoms:
+                return None
+            repaired = max(repaired.geoms, key=lambda part: part.area)
+        if repaired.is_empty or repaired.geom_type != 'Polygon':
+            return None
+        out = [[float(x), float(y)] for x, y in repaired.exterior.coords]
+        if len(out) < 4:
+            return None
+        if out[-1] != out[0]:
+            out.append(out[0][:])
+        return out
+
+    @staticmethod
+    def _region_feature(region: Dict) -> Dict:
+        tool = region['tool']
+        coords = [[float(x), float(y)] for x, y in region['coords']]
+        properties = {
+            'id': region.get('id'),
+            'name': region.get('name', ''),
+            'tool_type': tool,
+            'color_idx': region.get('color_idx', 0),
+        }
+        statistic_keys = (
+            'tau_median', 'tau_stdev', 'photon_count', 'photon_stdev',
+        )
+        statistics = {
+            key: region.get('statistics', {}).get(key)
+            for key in statistic_keys
+            if region.get('statistics', {}).get(key) is not None
+        }
+        properties['statistics'] = statistics
+        if tool == 'rect':
+            if len(coords) != 2:
+                raise ValueError('Rectangle regions require two corner points')
+            (x1, y1), (x2, y2) = coords
+            ring = [
+                [x1, y1], [x2, y1], [x2, y2], [x1, y2], [x1, y1],
+            ]
+            properties['bounds'] = coords
+        elif tool == 'ellipse':
+            if len(coords) != 2:
+                raise ValueError('Ellipse regions require two corner points')
+            (x1, y1), (x2, y2) = coords
+            cx, cy = (x1 + x2) / 2, (y1 + y2) / 2
+            rx, ry = abs(x2 - x1) / 2, abs(y2 - y1) / 2
+            angles = np.linspace(0.0, 2.0 * np.pi, 64, endpoint=False)
+            ring = [
+                [float(cx + rx * np.cos(angle)),
+                 float(cy + ry * np.sin(angle))]
+                for angle in angles
+            ]
+            ring.append(ring[0].copy())
+            properties['bounds'] = coords
+        elif tool in ('polygon', 'freehand'):
+            if len(coords) < 3:
+                raise ValueError(f'{tool.capitalize()} regions require at least three points')
+            ring = coords.copy()
+            if ring[-1] != ring[0]:
+                ring.append(ring[0].copy())
+            outer = RoiManager._outer_boundary(ring)
+            if outer is not None:
+                ring = outer
+                properties['repaired'] = 'self-intersecting'
+        else:
+            raise ValueError(f'Unsupported ROI tool: {tool}')
+        return {
+            'type': 'Feature',
+            'properties': properties,
+            'geometry': {'type': 'Polygon', 'coordinates': [ring]},
+        }
+
+    def to_geojson(self, region_ids: Optional[List[int]] = None) -> Dict:
+        if region_ids is None:
+            regions = self.regions
+        else:
+            wanted = set(region_ids)
+            regions = [region for region in self.regions if region['id'] in wanted]
+            found = {region['id'] for region in regions}
+            missing = wanted - found
+            if missing:
+                raise ValueError(f'Region IDs not found: {sorted(missing)}')
+        return {
+            'type': 'FeatureCollection',
+            'features': [self._region_feature(region) for region in regions],
+            'flimkit': {
+                'coordinate_system': 'image-pixel',
+                'axis_order': 'xy',
+                'origin': 'top-left',
+            },
+        }
+
+    @classmethod
+    def _region_from_feature(cls, feature: Dict) -> Dict:
+        if not isinstance(feature, dict) or feature.get('type') != 'Feature':
+            raise ValueError('GeoJSON entries must be Features')
+        properties = feature.get('properties') or {}
+        geometry = feature.get('geometry') or {}
+        if not isinstance(properties, dict) or not isinstance(geometry, dict):
+            raise ValueError('GeoJSON Feature properties and geometry must be objects')
+        geometry_type = geometry.get('type')
+        raw_coordinates = geometry.get('coordinates')
+        tool = properties.get('tool_type')
+        if tool is None:
+            if geometry_type == 'Polygon':
+                tool = 'polygon'
+            elif geometry_type == 'LineString':
+                tool = 'freehand'
+        if tool not in ('rect', 'ellipse', 'polygon', 'freehand'):
+            raise ValueError(f'Unsupported GeoJSON geometry: {geometry_type}')
+        if geometry_type == 'Polygon':
+            if not isinstance(raw_coordinates, list) or not raw_coordinates:
+                raise ValueError('GeoJSON Polygon must contain an outer ring')
+            outer_ring = raw_coordinates[0]
+            if isinstance(outer_ring, list) and len(outer_ring) < 4:
+                raise ValueError(
+                    'GeoJSON Polygon outer rings require at least four '
+                    'positions, including a repeated closing position',
+                )
+            ring = cls._geojson_coordinates(outer_ring, 4)
+            if ring[0] == ring[-1]:
+                ring = ring[:-1]
+            if tool in ('rect', 'ellipse'):
+                bounds = properties.get('bounds')
+                if bounds is not None:
+                    coords = cls._geojson_coordinates(bounds, 2)
+                    if len(coords) != 2:
+                        raise ValueError('GeoJSON ROI bounds require two corner points')
+                else:
+                    xs = [point[0] for point in ring]
+                    ys = [point[1] for point in ring]
+                    coords = [[min(xs), min(ys)], [max(xs), max(ys)]]
+            else:
+                coords = cls._geojson_coordinates(ring, 3)
+        elif geometry_type == 'LineString' and tool in ('polygon', 'freehand'):
+            coords = cls._geojson_coordinates(raw_coordinates, 3)
+        else:
+            raise ValueError(f'Unsupported GeoJSON geometry: {geometry_type}')
+        statistics = properties.get('statistics')
+        if isinstance(statistics, dict):
+            statistics = copy.deepcopy(statistics)
+        else:
+            statistics = {}
+        for key in ('tau_median', 'tau_stdev', 'photon_count', 'photon_stdev'):
+            if key not in statistics and properties.get(key) is not None:
+                statistics[key] = properties[key]
+        color_idx = properties.get('color_idx')
+        return {
+            'name': str(properties.get('name', 'imported-region')),
+            'tool': tool,
+            'coords': coords,
+            'color_idx': int(color_idx) if color_idx is not None else None,
+            'statistics': statistics,
+        }
+
+    def add_geojson(self, payload: Dict, mode: str = 'append') -> List[int]:
+        if mode not in ('append', 'replace'):
+            raise ValueError('mode must be append or replace')
+        if not isinstance(payload, dict):
+            raise ValueError('GeoJSON payload must be an object')
+        if payload.get('type') == 'FeatureCollection':
+            features = payload.get('features')
+            if not isinstance(features, list):
+                raise ValueError('GeoJSON FeatureCollection features must be a list')
+        elif payload.get('type') == 'Feature':
+            features = [payload]
+        else:
+            raise ValueError('GeoJSON must be a Feature or FeatureCollection')
+        pending = [self._region_from_feature(feature) for feature in features]
+        if mode == 'replace':
+            self.clear_all()
+        added = []
+        for item in pending:
+            region_id = self.add_region(
+                item['name'], item['tool'], item['coords'], item['color_idx'],
+            )
+            region = self.get_region(region_id)
+            if region is not None and item['statistics']:
+                region['statistics'] = item['statistics']
+            added.append(region_id)
+        return added
+
+    def compute_region_mask(self, region_id: int, image_shape: Tuple[int, int]) -> Optional[np.ndarray]:
+        from matplotlib.path import Path as MplPath
+        region = self.get_region(region_id)
+        if region is None:
+            return None
+        height, width = image_shape
+        mask = np.zeros((height, width), dtype=bool)
+        coords = np.array(region['coords'], dtype=float)
+        if region['tool'] == 'rect':
+            if len(coords) >= 2:
+                x0, y0 = coords[0]
+                x1, y1 = coords[1]
+                x_min, x_max = int(min(x0, x1)), int(max(x0, x1))
+                y_min, y_max = int(min(y0, y1)), int(max(y0, y1))
+                mask[y_min:y_max+1, x_min:x_max+1] = True
+        elif region['tool'] == 'ellipse':
+            if len(coords) >= 2:
+                x0, y0 = coords[0]
+                x1, y1 = coords[1]
+                cx, cy = (x0 + x1) / 2, (y0 + y1) / 2
+                rx, ry = abs(x1 - x0) / 2, abs(y1 - y0) / 2
+                yy, xx = np.ogrid[:height, :width]
+                mask = ((xx - cx)**2 / (rx**2 + 1e-6) +
+                        (yy - cy)**2 / (ry**2 + 1e-6)) <= 1
+        elif region['tool'] in ('polygon', 'freehand'):
+            if len(coords) >= 3:
+                path = MplPath(coords)
+                yy, xx = np.meshgrid(np.arange(height), np.arange(width), indexing='ij')
+                points = np.column_stack([xx.ravel(), yy.ravel()])
+                mask = path.contains_points(points).reshape((height, width))
+        return mask
+
+    def get_color(self, region_id: int) -> str:
+        region = self.get_region(region_id)
+        if region is None:
+            return '#999999'
+        color_idx = region.get('color_idx', 0) % len(_COLORS)
+        return _COLORS[color_idx]
+
+    @staticmethod
+    def get_color_palette() -> List[str]:
+        return _COLORS.copy()
+
+def get_rectangle_patch(coords, edgecolor, facecolor='none', linewidth=2):
+    from matplotlib.patches import Rectangle
+    x0, y0 = coords[0]
+    x1, y1 = coords[1]
+    width = abs(x1 - x0)
+    height = abs(y1 - y0)
+    xy = (min(x0, x1), min(y0, y1))
+    return Rectangle(xy, width, height, edgecolor=edgecolor, facecolor=facecolor, linewidth=linewidth)
+
+def get_ellipse_patch(coords, edgecolor, facecolor='none', linewidth=2):
+    from matplotlib.patches import Ellipse
+    x0, y0 = coords[0]
+    x1, y1 = coords[1]
+    cx, cy = (x0 + x1) / 2, (y0 + y1) / 2
+    width = abs(x1 - x0)
+    height = abs(y1 - y0)
+    return Ellipse((cx, cy), width, height, edgecolor=edgecolor, facecolor=facecolor, linewidth=linewidth)
+
+def get_polygon_patch(coords, edgecolor, facecolor='none', linewidth=2):
+    from matplotlib.patches import Polygon
+    return Polygon(coords, edgecolor=edgecolor, facecolor=facecolor, linewidth=linewidth, closed=True)