flimkit 0.12.0__py3-none-any.whl

flimkit/formats/BH/reader.py

@@ -0,0 +1,296 @@
+import numpy as np
+from pathlib import Path
+
+_LASER_RATES_HZ = (20e6, 50e6, 80e6)
+_DECAY_CONTENT = (0x10, 0x60)
+_INT_CONTENT = 0xa0
+
+def _load_sdtfile():
+    try:
+        import sdtfile
+    except ImportError:
+        raise ImportError('sdtfile is required to read Becker & Hickl .sdt files '
+                          '(pip install sdtfile)')
+    return sdtfile
+
+def _next_pow2(n):
+    return 1 << (int(n) - 1).bit_length() if n > 1 else 1
+
+def _reshape_cube(arr, image_x, image_y, adc_re):
+    flat = np.ascontiguousarray(arr).reshape(-1)
+    per_pixel = adc_re if adc_re > 0 else 1
+    n_pixels = flat.size // per_pixel
+    if n_pixels == image_x * image_y:
+        out = flat[:image_y * image_x * per_pixel].reshape(image_y, image_x, per_pixel)
+    else:
+        xpad, ypad = _next_pow2(image_x), _next_pow2(image_y)
+        out = flat[:ypad * xpad * per_pixel].reshape(ypad, xpad, per_pixel)
+        out = out[:image_y, :image_x, :]
+    return np.ascontiguousarray(out)
+
+def _reshape_intensity(arr, image_x, image_y):
+    flat = np.ascontiguousarray(arr).reshape(-1)
+    if flat.size == image_x * image_y:
+        out = flat.reshape(image_y, image_x)
+    else:
+        xpad, ypad = _next_pow2(image_x), _next_pow2(image_y)
+        out = flat[:ypad * xpad].reshape(ypad, xpad)[:image_y, :image_x]
+    return np.ascontiguousarray(out)
+
+def _decode_str(value):
+    if isinstance(value, bytes):
+        return value.split(b'\x00', 1)[0].decode('ascii', 'replace').strip()
+    return str(value).strip().strip('\x04').strip()
+
+class BHFile:
+    def __init__(self, path, verbose=True, channel=None, sync_rate=None):
+        self.path = str(path)
+        self.verbose = verbose
+        self._sync_override = float(sync_rate) if sync_rate else None
+        sdtfile = _load_sdtfile()
+        self._sdt = sdtfile.SdtFile(self.path)
+        headers = self._sdt.block_headers
+        self._decay_idx = [i for i, b in enumerate(headers)
+                           if (int(b['block_type']) & 0x00f0) in _DECAY_CONTENT]
+        self._int_idx = [i for i, b in enumerate(headers)
+                         if (int(b['block_type']) & 0x00f0) == _INT_CONTENT]
+        if not self._decay_idx:
+            raise ValueError(f'No FLIM image/decay blocks found in {self.path}')
+        self._cube_cache = {}
+        self.n_x = None
+        self.n_y = None
+        self._total_photons = None
+        self._parse_meta(channel)
+
+    def _measure_info(self, data_idx):
+        mi = self._sdt.measure_info
+        no = int(self._sdt.block_headers[data_idx]['meas_desc_block_no'])
+        return mi[no] if no < len(mi) else mi[0]
+
+    def close(self):
+        try:
+            self._sdt.close()
+        except Exception:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+
+    def _parse_meta(self, channel):
+        self.n_channels = len(self._decay_idx)
+        if channel is not None:
+            self.photon_channel = int(channel)
+        else:
+            self.photon_channel = 1 if self.n_channels == 1 else None
+        mi = self._measure_info(self._decay_idx[0])
+        self.module_type = _decode_str(mi['mod_type'])
+        adc_re = int(mi['adc_re'])
+        self.n_bins = adc_re if adc_re != 0 else 65536
+        tac_r = float(mi['tac_r'])
+        tac_g = int(mi['tac_g'])
+        if tac_g and self.n_bins:
+            self.tcspc_res = tac_r / (tac_g * self.n_bins)
+        else:
+            self.tcspc_res = 0.0
+        self.time_ns = (np.arange(self.n_bins) + 0.5) * self.tcspc_res * 1e9
+        stop = mi['StopInfo']
+        self.min_sync_rate = float(stop['min_sync_rate'])
+        self.max_sync_rate = float(stop['max_sync_rate'])
+        if self._sync_override and self._sync_override > 0:
+            self.sync_rate = self._sync_override
+            self.sync_source = 'user'
+        else:
+            sync = self.max_sync_rate if self.max_sync_rate > 0 else self.min_sync_rate
+            self.sync_rate = float(sync) if sync and sync > 0 else 0.0
+            self.sync_source = 'measured'
+        self.period_ns = (1e9 / self.sync_rate) if self.sync_rate > 0 else 0.0
+        self.n_records = 0
+        self.col_time_s = float(mi['col_t']) or None
+        self.acq_time_s = float(stop['stop_time']) or self.col_time_s
+        if self.sync_rate > 0 and self.acq_time_s:
+            self.n_sync = int(self.sync_rate * self.acq_time_s)
+        else:
+            self.n_sync = None
+        info = self._sdt.info
+        self.tags = {
+            'BH_ID': _decode_str(getattr(info, 'id', '')),
+            'BH_Title': _decode_str(getattr(info, 'title', '')),
+            'BH_Date': _decode_str(getattr(info, 'date', '')),
+            'BH_Time': _decode_str(getattr(info, 'time', '')),
+            'BH_ModuleType': self.module_type,
+            'BH_MeasMode': int(mi['meas_mode']),
+            'BH_ADCResolution': self.n_bins,
+            'BH_TACRange_s': tac_r,
+            'BH_TACGain': tac_g,
+            'BH_ImageX': int(mi['image_x']),
+            'BH_ImageY': int(mi['image_y']),
+            'BH_CollectionTime_s': float(mi['col_t']),
+            'BH_MinSyncRate_Hz': self.min_sync_rate,
+            'BH_MaxSyncRate_Hz': self.max_sync_rate,
+            'BH_SyncRate_Hz': self.sync_rate,
+            'BH_SyncRateSource': self.sync_source,
+            'BH_Channels': self.n_channels,
+        }
+        if self.verbose:
+            print(f"  B&H SPC  : {Path(self.path).name}")
+            print(f"  Module   : {self.module_type}  ({self.n_channels} channel(s))")
+            print(f"  TCSPC    : {self.n_bins} bins x {self.tcspc_res*1e12:.2f} ps")
+            sync_mhz = self.sync_rate / 1e6
+            print(f"  Sync     : {sync_mhz:.2f} MHz  (period {self.period_ns:.3f} ns, {self.sync_source})")
+            if (self.sync_source == 'measured' and self.min_sync_rate > 0
+                    and self.max_sync_rate > 0
+                    and abs(self.max_sync_rate - self.min_sync_rate) > 0.01 * self.max_sync_rate):
+                print(f"  WARNING: min/max sync differ "
+                      f"({self.min_sync_rate/1e6:.3f} vs {self.max_sync_rate/1e6:.3f} MHz), using max")
+            if self.sync_rate > 0:
+                nearest = min(_LASER_RATES_HZ, key=lambda r: abs(r - self.sync_rate))
+                if abs(nearest - self.sync_rate) > 0.02 * nearest:
+                    print(f"  NOTE     : {sync_mhz:.2f} MHz is non-standard "
+                          f"(period {self.period_ns:.3f} ns from measured sync); "
+                          f"pass sync_rate=<Hz> to override if the laser differs")
+            print(' ')
+
+    @property
+    def photons_per_pulse(self):
+        if self._total_photons is None or not self.n_sync:
+            return None
+        return self._total_photons / self.n_sync
+
+    def _norm_channel(self, channel):
+        if channel is None or int(channel) < 1:
+            return self._ensure_photon_channel()
+        return int(channel)
+
+    def _ensure_photon_channel(self):
+        if self.photon_channel is None:
+            self.photon_channel = self._select_photon_channel() if self.n_channels > 1 else 1
+        return self.photon_channel
+
+    def _select_photon_channel(self):
+        best_idx, best_sum, total_all = 1, -1, 0
+        for idx in range(1, self.n_channels + 1):
+            cube = self._decode_cube_for(idx)
+            total = int(cube.sum())
+            total_all += total
+            if total > best_sum:
+                self._cube_cache.pop(best_idx, None)
+                best_idx, best_sum = idx, total
+                self._cube_cache[idx] = cube
+        if self.verbose:
+            share = (100.0 * best_sum / total_all) if total_all > 0 else 0.0
+            print(f"  Channel  : auto-selected {best_idx}/{self.n_channels} "
+                  f"({best_sum:,} photons, {share:.1f}% of total)")
+        return best_idx
+
+    def _decode_cube_for(self, idx):
+        data_idx = self._decay_idx[idx - 1]
+        mi = self._measure_info(data_idx)
+        return _reshape_cube(self._sdt.data[data_idx], int(mi['image_x']),
+                             int(mi['image_y']), self.n_bins)
+
+    def _decode_cube(self, channel):
+        idx = self._norm_channel(channel)
+        if idx in self._cube_cache:
+            return self._cube_cache[idx]
+        if idx < 1 or idx > self.n_channels:
+            raise ValueError(f'Channel {channel} out of range 1..{self.n_channels}')
+        cube = self._decode_cube_for(idx)
+        self._cube_cache[idx] = cube
+        return cube
+
+    def pixel_stack(self, channel=None, binning=1):
+        cube = self._decode_cube(channel)
+        if binning > 1:
+            cube = _bin_cube(cube, binning)
+        self.n_y, self.n_x = cube.shape[0], cube.shape[1]
+        self._total_photons = int(cube.sum())
+        self.n_records = self._total_photons
+        if self.verbose:
+            print(f'  Built cube {cube.shape}  ({self._total_photons:,} photons)')
+        return cube.astype(np.uint32)
+
+    def raw_pixel_stack(self, channel=None, binning=1):
+        return self.pixel_stack(channel=channel, binning=binning)
+
+    def summed_decay(self, channel=None):
+        cube = self._decode_cube(channel)
+        decay = cube.sum(axis=(0, 1)).astype(float)
+        self._total_photons = int(decay.sum())
+        return decay
+
+    def intensity_image(self, channel=None, binning=1):
+        idx = self._norm_channel(channel)
+        decay_idx = self._decay_idx[idx - 1]
+        md = int(self._sdt.block_headers[decay_idx]['meas_desc_block_no'])
+        match = [i for i in self._int_idx
+                 if int(self._sdt.block_headers[i]['meas_desc_block_no']) == md]
+        if match:
+            mi = self._measure_info(match[0])
+            img = _reshape_intensity(self._sdt.data[match[0]],
+                                     int(mi['image_x']), int(mi['image_y'])).astype(np.uint64)
+        else:
+            return self.pixel_stack(channel=idx, binning=binning).sum(axis=2)
+        if binning > 1:
+            ny, nx = img.shape
+            ny2, nx2 = (ny // binning) * binning, (nx // binning) * binning
+            img = img[:ny2, :nx2].reshape(ny2 // binning, binning,
+                                          nx2 // binning, binning).sum(axis=(1, 3))
+        return img
+
+def _bin_cube(cube, binning):
+    if binning <= 1:
+        return cube
+    ny, nx, nh = cube.shape
+    ny2, nx2 = (ny // binning) * binning, (nx // binning) * binning
+    cube = cube[:ny2, :nx2, :]
+    return cube.reshape(ny2 // binning, binning, nx2 // binning, binning, nh).sum(axis=(1, 3))
+
+def _metadata(bh, data):
+    return {
+        'frequency': bh.sync_rate,
+        'tcspc_resolution': bh.tcspc_res,
+        'shape': data.shape,
+        'dims': ('Y', 'X', 'H'),
+        'tags': bh.tags,
+        'x_pixel_size': 0,
+        'y_pixel_size': 0,
+        'n_bins': bh.n_bins,
+        'time_ns': bh.time_ns,
+        'photon_channel': bh.photon_channel,
+    }
+
+def read_bh(path, binning=1, channel=None, verbose=False, sync_rate=None):
+    bh = BHFile(path, verbose=verbose, channel=channel, sync_rate=sync_rate)
+    data = bh.pixel_stack(channel=channel, binning=binning)
+    metadata = _metadata(bh, data)
+    bh.close()
+    return data, metadata
+
+def get_flim_data(path, binning=1, channel=None, sync_rate=None):
+    return read_bh(path, binning=binning, channel=channel, verbose=False, sync_rate=sync_rate)
+
+def get_intensity_image(path, binning=1, channel=None, sync_rate=None):
+    bh = BHFile(path, verbose=False, channel=channel, sync_rate=sync_rate)
+    img = bh.intensity_image(channel=channel, binning=binning)
+    cube_shape = (bh.n_y, bh.n_x, bh.n_bins)
+    metadata = _metadata(bh, np.empty(0))
+    metadata['shape'] = cube_shape
+    bh.close()
+    return img, metadata
+
+def normalise_flim(flim):
+    if flim is None:
+        return None
+    if flim.ndim == 5:
+        return flim[0, :, :, 0, :]
+    if flim.ndim == 4:
+        return flim[0] if flim.shape[0] == 1 else flim[:, :, 0, :]
+    if flim.ndim == 3:
+        return flim
+    return None
+
+def create_time_axis(n_bins, tcspc_resolution):
+    return np.arange(n_bins) * tcspc_resolution * 1e9

flimkit/formats/BH/writer.py

@@ -0,0 +1,86 @@
+import numpy as np
+
+def _records():
+    from sdtfile.sdtfile import FILE_HEADER, BLOCK_HEADER, MEASURE_INFO
+    return (np.dtype(FILE_HEADER), np.dtype(BLOCK_HEADER), np.dtype(MEASURE_INFO))
+
+def _measure_info_bytes(mi_dtype, n_bins, tcspc_res_ns, period_ns, image_x, image_y,
+                        col_time_s, module='SPC-150'):
+    mi = np.zeros(1, mi_dtype)
+    tac_g = 1
+    mi['adc_re'] = int(n_bins)
+    mi['tac_g'] = tac_g
+    mi['tac_r'] = float(tcspc_res_ns * 1e-9 * tac_g * n_bins)
+    mi['image_x'] = int(image_x)
+    mi['image_y'] = int(image_y)
+    mi['scan_x'] = int(image_x)
+    mi['scan_y'] = int(image_y)
+    mi['meas_mode'] = 13
+    mi['col_t'] = float(col_time_s)
+    mi['mod_type'] = module.encode('ascii')[:16]
+    sync = (1e9 / period_ns) if period_ns > 0 else 0.0
+    si = mi['StopInfo']
+    si['stop_time'] = float(col_time_s)
+    si['min_sync_rate'] = float(sync)
+    si['max_sync_rate'] = float(sync)
+    return mi.tobytes()
+
+def _file_info_bytes(title='FLIMKit synthetic', date='2026-01-01', time='00:00:00'):
+    lines = [
+        '*IDENTIFICATION',
+        'ID : SPC Setup & Data File',
+        f'Title : {title}',
+        'Version : 1  850 M',
+        f'Date : {date}',
+        f'Time : {time}',
+        '*END',
+        '',
+    ]
+    return ('\r\n'.join(lines)).encode('windows-1250')
+
+def write_sdt(path, cube, period_ns, tcspc_res_ns, col_time_s=10.0,
+              title='FLIMKit synthetic', module='SPC-150'):
+    cube = np.ascontiguousarray(cube)
+    if cube.ndim != 3:
+        raise ValueError('cube must be (Y, X, H)')
+    ny, nx, nbins = cube.shape
+    data = np.clip(cube, 0, 65535).astype('<u2')
+    data_bytes = data.tobytes()
+    fh_dtype, bh_dtype, mi_dtype = _records()
+    info = _file_info_bytes(title=title)
+    mi_bytes = _measure_info_bytes(mi_dtype, nbins, tcspc_res_ns, period_ns,
+                                   nx, ny, col_time_s, module=module)
+    header_size = fh_dtype.itemsize
+    bh_size = bh_dtype.itemsize
+    info_offs = header_size
+    meas_offs = info_offs + len(info)
+    data_block_offs = meas_offs + len(mi_bytes)
+    data_offs = data_block_offs + bh_size
+    next_block_offs = data_offs + len(data_bytes)
+    bh = np.zeros(1, bh_dtype)
+    bh['data_offs'] = data_offs
+    bh['next_block_offs'] = next_block_offs
+    bh['block_type'] = 0x0061
+    bh['meas_desc_block_no'] = 0
+    bh['lblock_no'] = 1
+    bh['block_length'] = len(data_bytes)
+    fh = np.zeros(1, fh_dtype)
+    fh['revision'] = 15
+    fh['info_offs'] = info_offs
+    fh['info_length'] = len(info)
+    fh['setup_offs'] = 0
+    fh['setup_length'] = 0
+    fh['data_block_offs'] = data_block_offs
+    fh['no_of_data_blocks'] = 1
+    fh['data_block_length'] = len(data_bytes)
+    fh['meas_desc_block_offs'] = meas_offs
+    fh['no_of_meas_desc_blocks'] = 1
+    fh['meas_desc_block_length'] = len(mi_bytes)
+    fh['header_valid'] = 0x5555
+    with open(path, 'wb') as f:
+        f.write(fh.tobytes())
+        f.write(info)
+        f.write(mi_bytes)
+        f.write(bh.tobytes())
+        f.write(data_bytes)
+    return str(path)

flimkit/formats/ISS/fdflim.py

@@ -0,0 +1,86 @@
+import numpy as np
+from lfdfiles import VistaIfli
+
+def _to_hz(f):
+    return float(f) if f > 1e5 else float(f) * 1e6
+
+class ISSFdFlim:
+    modality = 'frequency'
+
+    def __init__(self, path, verbose=True, channel=None, **kwargs):
+        self.path = str(path)
+        self.verbose = verbose
+        self.channel = channel
+        with VistaIfli(self.path) as f:
+            self.header = dict(f.header)
+            self.axes = f.axes
+            data = f.asarray()
+        sizer, sizee, sizet, sizec, sizez, sizey, sizex, sizef, _ = data.shape
+        self.n_x = int(sizex)
+        self.n_y = int(sizey)
+        self.n_z = max(int(sizez), 1)
+        self.n_channels = max(int(sizec), 1)
+        self.n_time_series = max(int(sizet), 1)
+        self.n_freq = max(int(sizef), 1)
+        self.n_positions = max(int(sizer), 1)
+        self.n_spectral = max(int(sizee), 1)
+        self._data = data
+        self._mod_freqs = np.asarray(self.header.get('ModFrequency', ()), dtype=np.float32)
+        self._ref_lifetime_ns = np.asarray(self.header.get('RefLifetime', ()), dtype=np.float32)
+        self._ref_phasor = np.asarray(self.header.get('RefDCPhasor'))
+        if self.verbose:
+            print(f'  ISS FD-FLIM : {self.path}')
+            print(f'  Size     : {self.n_x} x {self.n_y} px, {self.n_channels} ch, '
+                  f'{self.n_freq} freq, {self.n_time_series} time series')
+            print('  Frequency-domain data: loads into phasor analysis, no lifetime fitting')
+
+    def _channel_index(self, channel):
+        if channel is None:
+            return 0
+        c = int(channel)
+        idx = c - 1 if c >= 1 else c
+        return idx if 0 <= idx < self.n_channels else 0
+
+    def phasor(self, channel=None, harmonic=0, calibrate=True, time_series=0):
+        ci = self._channel_index(self.channel if channel is None else channel)
+        fi = int(harmonic) if 0 <= int(harmonic) < self.n_freq else 0
+        ts = int(time_series) if 0 <= int(time_series) < self.n_time_series else 0
+        block = self._data[0, 0, ts, ci].sum(axis=0)
+        dc = block[:, :, fi, 0]
+        gx = block[:, :, fi, 1]
+        gy = block[:, :, fi, 2]
+        freq_hz = _to_hz(self._mod_freqs[fi]) if self._mod_freqs.size else 0.0
+        if calibrate:
+            gx, gy = self._calibrate(gx, gy, ci, fi, freq_hz)
+        return dc.astype(float), gx.astype(float), gy.astype(float), freq_hz / 1e6
+
+    def _calibrate(self, gx, gy, ci, fi, freq_hz):
+        tau_ref = float(self._ref_lifetime_ns[ci]) * 1e-9 if ci < self._ref_lifetime_ns.size else 0.0
+        rx = ry = 0.0
+        if self._ref_phasor is not None and self._ref_phasor.ndim == 3 \
+                and ci < self._ref_phasor.shape[0] and fi < self._ref_phasor.shape[1]:
+            rx = float(self._ref_phasor[ci, fi, 1])
+            ry = float(self._ref_phasor[ci, fi, 2])
+        if tau_ref <= 0 or (rx == 0 and ry == 0) or freq_hz <= 0:
+            return gx, gy
+        w = 2.0 * np.pi * freq_hz
+        denom = 1.0 + (w * tau_ref) ** 2
+        gt, st = 1.0 / denom, (w * tau_ref) / denom
+        scale = np.hypot(gt, st) / np.hypot(rx, ry)
+        dphi = np.arctan2(st, gt) - np.arctan2(ry, rx)
+        cos, sin = np.cos(dphi), np.sin(dphi)
+        return scale * (gx * cos - gy * sin), scale * (gx * sin + gy * cos)
+
+    def pixel_stack(self, *args, **kwargs):
+        raise ValueError('ISS .ifli is frequency-domain (FD-FLIM): there is no '
+                         'time-domain decay to fit. Load it into phasor analysis instead.')
+
+    def summed_decay(self, *args, **kwargs):
+        return self.pixel_stack()
+
+    def raw_pixel_stack(self, *args, **kwargs):
+        return self.pixel_stack()
+
+def phasor_from_ifli(path, channel=None, harmonic=0, calibrate=True, verbose=False):
+    return ISSFdFlim(path, verbose=verbose).phasor(channel=channel, harmonic=harmonic,
+                                                   calibrate=calibrate)

flimkit/formats/ISS/image.py

@@ -0,0 +1,114 @@
+import struct
+import numpy as np
+from pathlib import Path
+
+_HEADER_BYTES = 256
+_SIGNATURE = b'VISTAIMAGE'
+
+def _read_header(buf):
+    h = {}
+    h['signature'] = bytes(buf[0:10])
+    h['file_version'] = buf[10]
+    h['image_type'] = buf[11]
+    h['channel_bits'] = buf[12]
+    h['compression'] = buf[13]
+    h['res_x'] = struct.unpack_from('<H', buf, 14)[0]
+    h['res_y'] = struct.unpack_from('<H', buf, 16)[0]
+    h['res_z'] = struct.unpack_from('<H', buf, 18)[0]
+    region = struct.unpack_from('<6f', buf, 20)
+    h['region'] = {'x': region[0:2], 'y': region[2:4], 'z': region[4:6]}
+    h['pixel_acq_time'] = struct.unpack_from('<f', buf, 44)[0]
+    h['n_channels'] = struct.unpack_from('<H', buf, 93)[0]
+    h['n_time_series'] = struct.unpack_from('<H', buf, 95)[0]
+    h['pixel_interval'] = struct.unpack_from('<f', buf, 97)[0]
+    h['line_interval'] = struct.unpack_from('<f', buf, 101)[0]
+    h['frame_interval'] = struct.unpack_from('<f', buf, 105)[0]
+    h['n_frames_integrated'] = struct.unpack_from('<H', buf, 109)[0]
+    return h
+
+class ISSImage:
+    def __init__(self, path, verbose=True, byteorder='<'):
+        self.path = str(path)
+        self.verbose = verbose
+        with open(self.path, 'rb') as fh:
+            buf = fh.read(_HEADER_BYTES)
+            data = np.frombuffer(fh.read(), dtype=np.dtype(byteorder + 'f4'))
+        if len(buf) < _HEADER_BYTES:
+            raise ValueError(f'ISS .ifi header truncated: {self.path}')
+        self.header = _read_header(buf)
+        if self.header['signature'][:10] != _SIGNATURE and self.verbose:
+            print(f"  WARNING: ISS .ifi signature {self.header['signature']!r} != {_SIGNATURE!r}")
+        self._parse(data)
+
+    def _parse(self, data):
+        h = self.header
+        self.n_x = int(h['res_x'])
+        self.n_y = int(h['res_y'])
+        self.n_z = int(h['res_z'])
+        nc = int(h['n_channels'])
+        if nc <= 0:
+            nc = bin(int(h['channel_bits'])).count('1') or 1
+        per_frame = self.n_x * self.n_y
+        self.n_frames = (data.size // (nc * per_frame)) if nc * per_frame > 0 else 0
+        self.n_channels = nc
+        keep = nc * self.n_frames * per_frame
+        if keep > 0:
+            self.images = data[:keep].reshape(nc, self.n_frames, self.n_y, self.n_x)
+        else:
+            self.images = np.zeros((nc, 0, self.n_y, self.n_x), dtype=np.float32)
+        self.tags = {
+            'ISS_FileVersion': int(h['file_version']),
+            'ISS_ChannelBits': int(h['channel_bits']),
+            'ISS_ResolutionXYZ': (self.n_x, self.n_y, self.n_z),
+            'ISS_NumChannels': self.n_channels,
+            'ISS_NumFrames': self.n_frames,
+            'ISS_NumTimeSeries': int(h['n_time_series']),
+            'ISS_PixelAcqTime': float(h['pixel_acq_time']),
+            'ISS_Region': h['region'],
+        }
+        if self.verbose:
+            print(f'  ISS image : {Path(self.path).stem}')
+            print(f'  Size     : {self.n_x} x {self.n_y} px, {self.n_channels} ch, {self.n_frames} frame(s)')
+            print(' ')
+
+    def _channel_index(self, channel):
+        c = int(channel)
+        idx = c - 1 if c >= 1 else c
+        if idx < 0 or idx >= self.n_channels:
+            return 0
+        return idx
+    
+    def image(self, channel=None, frame=None):
+        if self.n_channels == 0 or self.n_frames == 0:
+            return np.zeros((self.n_y, self.n_x), dtype=np.float32)
+        ci = 0 if channel is None else self._channel_index(channel)
+        if frame is None:
+            return self.images[ci].sum(axis=0)
+        return self.images[ci, frame]
+    
+    @property
+    def intensity_image(self):
+        return self.image()
+    
+    def pixel_stack(self, *args, **kwargs):
+        raise ValueError('ISS .ifi is an intensity image with no lifetime data; use intensity_image / get_intensity_image()')
+    
+    def summed_decay(self, *args, **kwargs):
+        raise ValueError('ISS .ifi is an intensity image with no lifetime data; use intensity_image / get_intensity_image()')
+
+def read_ifi(path, channel=None, verbose=False):
+    iss = ISSImage(path, verbose=verbose)
+    img = iss.image(channel=channel)
+    metadata = {
+        'shape': iss.images.shape,
+        'dims': ('C', 'T', 'Y', 'X'),
+        'n_x': iss.n_x,
+        'n_y': iss.n_y,
+        'n_channels': iss.n_channels,
+        'n_frames': iss.n_frames,
+        'tags': iss.tags,
+    }
+    return img, metadata
+
+def get_intensity_image(path, channel=None):
+    return read_ifi(path, channel=channel, verbose=False)