photonsfile 2026.7.8__tar.gz

photonsfile-2026.7.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Hunt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

photonsfile-2026.7.8/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: photonsfile
+Version: 2026.7.8
+Summary: Read Photonscore LINCam .photons (D7) files
+Author: Alex Hunt
+License: MIT
+Project-URL: Homepage, https://github.com/alex1075/photonsfile
+Project-URL: D7 format, https://github.com/photonscore/d7
+Keywords: Photonscore,LINCam,D7,photons,TCSPC,FLIM
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: all
+Requires-Dist: numba; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: numba; extra == "test"
+Dynamic: license-file
+
+# photonsfile
+
+Pure-Python reader for Photonscore LINCam `.photons` files (the **D7** container).
+numpy only, with optional numba acceleration for the varint decode.
+
+Photonscore LINCam is a position-sensitive single-photon detector: every photon
+carries an `(x, y)` detector position, a TCSPC micro time (`dt`), and a macro time
+in milliseconds (`ms`). This library decodes those per-photon streams and can bin
+them into an intensity image, a TCSPC decay, or a `(Y, X, H)` FLIM cube.
+
+## The D7 format
+
+A `.photons` file is a paged container: 16 KB pages, each carrying a 2-byte page
+marker, holding a protobuf-style header, a per-dataset index, and an epilogue. Each
+dataset (`/photons/x`, `/photons/y`, `/photons/dt`, `/photons/ms`, and on dual-TDC
+detectors `/start/time` and `/stop/time`) is stored as a seed value followed by
+zigzag-varint delta blocks. `dt` to time is calibrated from the file's
+`/photons/TacChannel` attribute (picoseconds per raw unit).
+
+The format is documented at [github.com/photonscore/d7](https://github.com/photonscore/d7)
+(Apache-2.0). This reader was written from that specification and **validated
+bit-exact against the Photonscore SDK**. No vendor source is redistributed.
+
+## Install
+
+```bash
+pip install photonsfile          # numpy only
+pip install photonsfile[all]     # + numba, for a faster varint decode
+```
+
+## Usage
+
+```python
+from photonsfile import PhotonsFile, imread
+
+with PhotonsFile('sample.photons') as f:
+    ph = f.photons()               # {'x', 'y', 'dt', 'ms'} arrays, one per photon
+    img = f.image(pixels=512)      # (Y, X) intensity image
+    decay = f.decay(bins=256)      # summed TCSPC histogram
+    cube = f.flim_image(512, 256)  # (Y, X, H) FLIM cube
+    dt_res = f.tcspc_resolution(256)   # seconds per bin, from TacChannel
+    print(f.attributes)            # D7 file attributes
+
+img = imread('sample.photons')     # shortcut for the intensity image
+```
+
+Low-level access to the decoder is also exported: `read_header`,
+`read_attributes`, `read_photons`, `dataset_names`, `has_dual_tdc`.
+
+numba is optional; without it the varint decode uses a vectorised numpy fallback.
+`photonsfile.have_numba()` reports which path is active.
+
+## Provenance
+
+Reverse-engineered from the public D7 specification and checked bit-exact against
+the Photonscore SDK on a 284-million-photon sample. Thanks to Photonscore for
+open-sourcing the D7 format.
+
+## License
+
+MIT - see `LICENSE`.

photonsfile-2026.7.8/README.md

@@ -0,0 +1,61 @@
+# photonsfile
+
+Pure-Python reader for Photonscore LINCam `.photons` files (the **D7** container).
+numpy only, with optional numba acceleration for the varint decode.
+
+Photonscore LINCam is a position-sensitive single-photon detector: every photon
+carries an `(x, y)` detector position, a TCSPC micro time (`dt`), and a macro time
+in milliseconds (`ms`). This library decodes those per-photon streams and can bin
+them into an intensity image, a TCSPC decay, or a `(Y, X, H)` FLIM cube.
+
+## The D7 format
+
+A `.photons` file is a paged container: 16 KB pages, each carrying a 2-byte page
+marker, holding a protobuf-style header, a per-dataset index, and an epilogue. Each
+dataset (`/photons/x`, `/photons/y`, `/photons/dt`, `/photons/ms`, and on dual-TDC
+detectors `/start/time` and `/stop/time`) is stored as a seed value followed by
+zigzag-varint delta blocks. `dt` to time is calibrated from the file's
+`/photons/TacChannel` attribute (picoseconds per raw unit).
+
+The format is documented at [github.com/photonscore/d7](https://github.com/photonscore/d7)
+(Apache-2.0). This reader was written from that specification and **validated
+bit-exact against the Photonscore SDK**. No vendor source is redistributed.
+
+## Install
+
+```bash
+pip install photonsfile          # numpy only
+pip install photonsfile[all]     # + numba, for a faster varint decode
+```
+
+## Usage
+
+```python
+from photonsfile import PhotonsFile, imread
+
+with PhotonsFile('sample.photons') as f:
+    ph = f.photons()               # {'x', 'y', 'dt', 'ms'} arrays, one per photon
+    img = f.image(pixels=512)      # (Y, X) intensity image
+    decay = f.decay(bins=256)      # summed TCSPC histogram
+    cube = f.flim_image(512, 256)  # (Y, X, H) FLIM cube
+    dt_res = f.tcspc_resolution(256)   # seconds per bin, from TacChannel
+    print(f.attributes)            # D7 file attributes
+
+img = imread('sample.photons')     # shortcut for the intensity image
+```
+
+Low-level access to the decoder is also exported: `read_header`,
+`read_attributes`, `read_photons`, `dataset_names`, `has_dual_tdc`.
+
+numba is optional; without it the varint decode uses a vectorised numpy fallback.
+`photonsfile.have_numba()` reports which path is active.
+
+## Provenance
+
+Reverse-engineered from the public D7 specification and checked bit-exact against
+the Photonscore SDK on a 284-million-photon sample. Thanks to Photonscore for
+open-sourcing the D7 format.
+
+## License
+
+MIT - see `LICENSE`.

photonsfile-2026.7.8/photonsfile/__init__.py

@@ -0,0 +1,2 @@
+from .photonsfile import *
+from .photonsfile import __version__, __all__

photonsfile-2026.7.8/photonsfile/_d7.py

@@ -0,0 +1,323 @@
+import numpy as np
+
+try:
+    from numba import njit as _njit
+    _HAVE_NUMBA = True
+except Exception:
+    _HAVE_NUMBA = False
+
+MAGIC = b'D7 Photons Data'
+_DEFAULT_PAGE = 16384
+
+_DTYPES = {
+    0: np.int8, 1: np.int16, 2: np.int32, 3: np.int64,
+    4: np.uint8, 5: np.uint16, 6: np.uint32, 7: np.uint64,
+    8: np.single, 9: np.double,
+}
+
+def _read_varint(buf, i):
+    shift = 0
+    val = 0
+    while True:
+        c = buf[i]
+        i += 1
+        val |= (c & 0x7f) << shift
+        if not (c & 0x80):
+            return val, i
+        shift += 7
+
+def _zigzag(v):
+    return (v >> 1) ^ -(v & 1)
+
+def _strip_markers(raw, phys_start, page):
+    b = np.frombuffer(raw, dtype=np.uint8)
+    n = b.shape[0]
+    first = (-phys_start) % page
+    if first >= n:
+        return b
+    m0 = np.arange(first, n, page)
+    keep = np.ones(n, dtype=bool)
+    keep[m0] = False
+    m1 = m0[m0 + 1 < n] + 1
+    keep[m1] = False
+    return b[keep]
+
+def _clean_pos(phys, region_start, page):
+    markers = (phys // page) - (region_start // page)
+    return (phys - region_start) - 2 * markers
+
+def _parse_descriptor(payload):
+    name = None
+    code = None
+    k = 0
+    while k < len(payload):
+        tag = payload[k]
+        k += 1
+        field = tag >> 3
+        wt = tag & 7
+        if wt == 2:
+            ln, k = _read_varint(payload, k)
+            chunk = payload[k:k + ln]
+            k += ln
+            if field == 1:
+                name = chunk.decode('ascii', 'replace')
+        elif wt == 0:
+            val, k = _read_varint(payload, k)
+            if field == 2:
+                code = val
+        else:
+            break
+    return name, _DTYPES.get(code, None)
+
+def read_header(path):
+    with open(path, 'rb') as fh:
+        head = fh.read(_DEFAULT_PAGE)
+    if MAGIC not in head[:64]:
+        raise ValueError(f'Not a D7 .photons file (magic {MAGIC!r} not found): {path}')
+    i = 2
+    tag, i = _read_varint(head, i)
+    hlen, i = _read_varint(head, i)
+    end = i + hlen
+    header = {'magic': MAGIC.decode(), 'version': None, 'index_step': None,
+              'page_size': _DEFAULT_PAGE, 'datasets': []}
+    while i < end:
+        tag, i = _read_varint(head, i)
+        field = tag >> 3
+        wt = tag & 7
+        if wt == 2:
+            ln, i = _read_varint(head, i)
+            payload = head[i:i + ln]
+            i += ln
+            if field == 7:
+                name, dtype = _parse_descriptor(payload)
+                header['datasets'].append({'name': name, 'dtype': dtype})
+        elif wt == 0:
+            val, i = _read_varint(head, i)
+            if field == 2:
+                header['version'] = val
+            elif field == 6:
+                header['index_step'] = val
+            elif field == 8 and val > 0:
+                header['page_size'] = val
+        else:
+            break
+    header['header_end'] = end
+    return header
+
+def dataset_names(path):
+    return [d['name'] for d in read_header(path)['datasets']]
+
+def _read_epilogue(fh, filesize, page):
+    n = min(filesize, 8192)
+    fh.seek(filesize - n)
+    tail = _strip_markers(fh.read(n), filesize - n, page).tobytes()
+    e = tail.rfind(b'End of D7 Photons Data File')
+    if e < 0:
+        raise ValueError('D7 epilogue signature not found')
+    j = e - 3
+    while j - 1 >= 0 and (tail[j - 1] & 0x80):
+        j -= 1
+    giof, _ = _read_varint(tail, j)
+    return giof
+
+def _parse_index(fh, index_off, filesize, page, n_datasets):
+    fh.seek(index_off)
+    idx = _strip_markers(fh.read(filesize - index_off), index_off, page).tobytes()
+    _tag, p = _read_varint(idx, 0)
+    ln, p = _read_varint(idx, p)
+    body = idx[p:p + ln]
+    offsets = {}
+    i = 0
+    n = len(body)
+    while i < n - 2:
+        if body[i] == 0x0a:
+            l = body[i + 1]
+            pay = body[i + 2:i + 2 + l]
+            if len(pay) >= 3 and pay[0] == 0x08 and pay[1] < n_datasets and pay[2] == 0x10:
+                did = pay[1]
+                off, _ = _read_varint(pay, 3)
+                offsets.setdefault(did, []).append(off)
+                i += 2 + l
+                continue
+        i += 1
+    for did in offsets:
+        offsets[did].sort()
+    return offsets
+
+def read_attributes(path):
+    import os
+    header = read_header(path)
+    page = header['page_size']
+    filesize = os.path.getsize(path)
+    with open(path, 'rb') as fh:
+        index_off = _read_epilogue(fh, filesize, page)
+        fh.seek(index_off)
+        idx = _strip_markers(fh.read(filesize - index_off), index_off, page).tobytes()
+        _tag, p = _read_varint(idx, 0)
+        ln, p = _read_varint(idx, p)
+        body = idx[p:p + ln]
+    attrs = {}
+    i = 0
+    n = len(body)
+    while i < n:
+        tag, i = _read_varint(body, i)
+        f = tag >> 3
+        wt = tag & 7
+        if wt == 2:
+            l, i = _read_varint(body, i)
+            ent = body[i:i + l]
+            i += l
+            if f == 2:
+                key = val = None
+                k = 0
+                while k < len(ent):
+                    etag, k = _read_varint(ent, k)
+                    if etag & 7 != 2:
+                        break
+                    el, k = _read_varint(ent, k)
+                    s = ent[k:k + el].decode('utf8', 'replace')
+                    k += el
+                    if etag >> 3 == 1:
+                        key = s
+                    elif etag >> 3 == 2:
+                        val = s
+                if key:
+                    attrs[key] = val
+        elif wt == 0:
+            _, i = _read_varint(body, i)
+        else:
+            break
+    return attrs
+
+if _HAVE_NUMBA:
+    @_njit(cache=True)
+    def _decode_varints_zigzag_nb(b):
+        n = b.shape[0]
+        out = np.empty(n, dtype=np.int64)
+        m = 0
+        val = np.uint64(0)
+        shift = np.uint64(0)
+        for i in range(n):
+            c = b[i]
+            val |= np.uint64(c & 0x7f) << shift
+            if c & 0x80:
+                shift += np.uint64(7)
+            else:
+                out[m] = np.int64(val >> np.uint64(1)) ^ -np.int64(val & np.uint64(1))
+                m += 1
+                val = np.uint64(0)
+                shift = np.uint64(0)
+        return out[:m]
+
+def _decode_varints_zigzag_np(b):
+    cont = (b & 0x80) != 0
+    term = ~cont
+    payload = (b & 0x7f).astype(np.uint64)
+    n = b.shape[0]
+    newgrp = np.empty(n, dtype=bool)
+    newgrp[0] = True
+    newgrp[1:] = term[:-1]
+    starts = np.flatnonzero(newgrp)
+    within = (np.arange(n) - np.repeat(starts, np.diff(np.append(starts, n)))).astype(np.uint64)
+    contrib = payload << (np.uint64(7) * within)
+    summed = np.add.reduceat(contrib, starts)
+    return (summed >> np.uint64(1)).astype(np.int64) ^ -(summed & np.uint64(1)).astype(np.int64)
+
+def _decode_varints_zigzag(b):
+    if b.shape[0] == 0:
+        return np.zeros(0, dtype=np.int64)
+    if _HAVE_NUMBA:
+        return _decode_varints_zigzag_nb(b)
+    return _decode_varints_zigzag_np(b)
+
+def _decode_data_block(buf, cp, n, n_datasets):
+    q = cp - 1
+    while True:
+        q = buf.find(b'\x12', q + 1, cp + 16)
+        if q < 0:
+            return None
+        msg_len, k = _read_varint(buf, q + 1)
+        if (k + 2 < n and buf[k] == 0x08 and buf[k + 1] < n_datasets
+                and buf[k + 2] in (0x18, 0x22, 0x2a)):
+            break
+    msg = buf[k:k + msg_len]
+    seed = 0
+    src = None
+    m = 0
+    while m < len(msg):
+        tag, m = _read_varint(msg, m)
+        f = tag >> 3
+        wt = tag & 7
+        if wt == 0:
+            v, m = _read_varint(msg, m)
+            if f == 3:
+                seed = _zigzag(v)
+        elif wt == 2:
+            l, m = _read_varint(msg, m)
+            if f in (4, 5):
+                src = msg[m:m + l]
+            m += l
+        else:
+            break
+    if src is None:
+        return None
+    deltas = _decode_varints_zigzag(np.frombuffer(src, dtype=np.uint8))
+    vals = np.empty(deltas.shape[0] + 1, dtype=np.int64)
+    vals[0] = seed
+    np.cumsum(deltas, out=vals[1:])
+    vals[1:] += seed
+    return vals
+
+def _decode_region(fh, offsets, region_start, region_end, page, n_datasets):
+    fh.seek(region_start)
+    clean = _strip_markers(fh.read(region_end - region_start), region_start, page)
+    buf = clean.tobytes()
+    n = len(buf)
+    parts = []
+    for phys in offsets:
+        vals = _decode_data_block(buf, _clean_pos(phys, region_start, page), n, n_datasets)
+        if vals is not None:
+            parts.append(vals)
+    if not parts:
+        return np.zeros(0, dtype=np.int64)
+    return np.concatenate(parts)
+
+def has_dual_tdc(path):
+    names = set(dataset_names(path))
+    return '/start/time' in names and '/stop/time' in names
+
+def read_photons(path, wanted=('x', 'y', 'dt', 'ms')):
+    header = read_header(path)
+    page = header['page_size']
+    datasets = header['datasets']
+    n_datasets = len(datasets)
+    id_by_name = {d['name']: i for i, d in enumerate(datasets)}
+    dtype_by_id = {i: d['dtype'] for i, d in enumerate(datasets)}
+    import os
+    filesize = os.path.getsize(path)
+    with open(path, 'rb') as fh:
+        index_off = _read_epilogue(fh, filesize, page)
+        offsets = _parse_index(fh, index_off, filesize, page, n_datasets)
+        def decode(full):
+            did = id_by_name.get(full)
+            if did is None or did not in offsets or not offsets[did]:
+                return None
+            v = offsets[did]
+            start, end = min(v), min(index_off, max(v) + 65536)
+            vals = _decode_region(fh, v, start, end, page, n_datasets)
+            return vals.astype(dtype_by_id.get(did) or np.int64, copy=False)
+        # newer LINCam files carry two TDCs: dt = photon /stop/time - laser /start/time
+        dual = '/start/time' in id_by_name and '/stop/time' in id_by_name
+        out = {}
+        for name in wanted:
+            if name == 'dt' and dual:
+                start_t = decode('/start/time')
+                stop_t = decode('/stop/time')
+                if start_t is not None and stop_t is not None:
+                    m = min(start_t.shape[0], stop_t.shape[0])
+                    out['dt'] = (stop_t[:m].astype(np.int64) - start_t[:m].astype(np.int64))
+                    continue
+            vals = decode('/photons/' + name)
+            if vals is not None:
+                out[name] = vals
+    return out

photonsfile-2026.7.8/photonsfile/photonsfile.py

@@ -0,0 +1,174 @@
+"""Read Photonscore LINCam .photons files.
+
+Photonscore LINCam detectors write time- and space-resolved single-photon data
+to a `.photons` file, the D7 container. This is a pure-Python reader for it:
+numpy only, with optional numba acceleration for the varint decode.
+
+The D7 container is a paged file (16 KB pages, each carrying a 2-byte page
+marker), holding a protobuf-style header, a per-dataset index, and an epilogue.
+Each photon dataset (`/photons/x`, `/photons/y`, `/photons/dt`, `/photons/ms`,
+and on dual-TDC detectors `/start/time` and `/stop/time`) is stored as a seed
+value followed by zigzag varint delta blocks. `x`/`y` are detector positions,
+`dt` is the TCSPC micro time, and `ms` is the macro time in milliseconds.
+
+The D7 format is documented at https://github.com/photonscore/d7 (Apache-2.0).
+This reader was written from that specification and validated bit-exact against
+the Photonscore SDK. No vendor source is redistributed.
+
+Examples
+--------
+>>> from photonsfile import PhotonsFile
+>>> with PhotonsFile('sample.photons') as f:      # doctest: +SKIP
+...     ph = f.photons()                          # dict of x, y, dt, ms arrays
+...     image = f.image(pixels=512)               # (Y, X) intensity image
+...     decay = f.decay(bins=256)                 # TCSPC histogram
+
+"""
+
+import numpy as np
+
+from ._d7 import (
+    MAGIC,
+    read_header,
+    read_attributes,
+    read_photons,
+    dataset_names,
+    has_dual_tdc,
+    _HAVE_NUMBA,
+)
+
+__version__ = '2026.7.8'
+
+__all__ = [
+    'PhotonsFile',
+    'imread',
+    'read_header',
+    'read_attributes',
+    'read_photons',
+    'dataset_names',
+    'has_dual_tdc',
+    'have_numba',
+    'MAGIC',
+]
+
+def have_numba():
+    """Return True if the varint decode is numba-accelerated."""
+    return _HAVE_NUMBA
+
+class PhotonsFile:
+    """A Photonscore LINCam `.photons` (D7) file.
+
+    Parameters:
+        filename: Name of the `.photons` file to open.
+
+    """
+
+    def __init__(self, filename):
+        self.filename = str(filename)
+        self.header = read_header(self.filename)
+        self.attributes = read_attributes(self.filename)
+        self.version = self.header['version']
+        self.datasets = [d['name'] for d in self.header['datasets']]
+        self.dual_tdc = has_dual_tdc(self.filename)
+        self.position_bits = int(self.attributes.get('/photons/PositionBits', 12))
+        self.tac_bits = int(self.attributes.get('/photons/TacBits', 12))
+        self.position_range = 1 << self.position_bits
+        self.tac_range = 1 << self.tac_bits
+        self.tac_channel = self.attributes.get('/photons/TacChannel')
+        self._photons = None
+
+    def photons(self, wanted=('x', 'y', 'dt', 'ms')):
+        """Return a dict of per-photon arrays for the requested datasets.
+
+        Keys are the short names (`'x'`, `'y'`, `'dt'`, `'ms'`). On dual-TDC
+        detectors `dt` is `stop - start` in picoseconds and `tac_range` is
+        updated from the data.
+        """
+        if self._photons is None:
+            self._photons = read_photons(self.filename, wanted)
+            if self.dual_tdc and 'dt' in self._photons:
+                dt = np.asarray(self._photons['dt'])
+                dt = dt[dt >= 0]
+                if dt.size:
+                    self.tac_range = int(dt.max()) + 1
+        return self._photons
+
+    def tcspc_resolution(self, bins):
+        """Return the TCSPC bin width in seconds for a given number of bins.
+
+        Uses the `/photons/TacChannel` attribute (picoseconds per raw dt unit),
+        or 1 ps per unit for dual-TDC detectors. Returns 0.0 if unknown.
+        """
+        if self.dual_tdc:
+            period_s = self.tac_range * 1e-12
+        elif self.tac_channel:
+            period_s = self.tac_range * float(self.tac_channel) * 1e-12
+        else:
+            return 0.0
+        return period_s / bins if bins else 0.0
+
+    def _binned(self, pixels, binning):
+        s = self.photons()
+        x = np.asarray(s['x']).astype(np.int64)
+        y = np.asarray(s['y']).astype(np.int64)
+        dt = np.asarray(s['dt']).astype(np.int64)
+        n = min(x.shape[0], y.shape[0], dt.shape[0])
+        x, y, dt = x[:n], y[:n], dt[:n]
+        valid = ((x >= 0) & (x < self.position_range)
+                 & (y >= 0) & (y < self.position_range)
+                 & (dt >= 0) & (dt < self.tac_range))
+        return x[valid], y[valid], dt[valid]
+
+    def image(self, pixels=512, binning=1):
+        """Return the `(Y, X)` intensity image, photon positions binned to a grid."""
+        x, y, _ = self._binned(pixels, binning)
+        p = int(pixels)
+        xi = (x * p) // self.position_range
+        yi = (y * p) // self.position_range
+        if binning > 1:
+            xi //= binning
+            yi //= binning
+            p = (p + binning - 1) // binning
+        if p == 0:
+            return np.zeros((0, 0), dtype=np.uint32)
+        flat = yi * p + xi
+        return np.bincount(flat, minlength=p * p).reshape(p, p).astype(np.uint32)
+
+    def decay(self, bins=256):
+        """Return the summed TCSPC histogram of length `bins`."""
+        s = self.photons()
+        dt = np.asarray(s['dt']).astype(np.int64)
+        dt = dt[(dt >= 0) & (dt < self.tac_range)]
+        di = (dt * bins) // self.tac_range
+        return np.bincount(di, minlength=bins)[:bins].astype(np.uint32)
+
+    def flim_image(self, pixels=512, bins=256, binning=1):
+        """Return the `(Y, X, H)` FLIM cube: intensity image with a TCSPC axis."""
+        x, y, dt = self._binned(pixels, binning)
+        p = int(pixels)
+        b = int(bins)
+        xi = (x * p) // self.position_range
+        yi = (y * p) // self.position_range
+        di = (dt * b) // self.tac_range
+        if binning > 1:
+            xi //= binning
+            yi //= binning
+            p = (p + binning - 1) // binning
+        if p == 0 or b == 0:
+            return np.zeros((p, p, b), dtype=np.uint32)
+        flat = (yi * p + xi) * b + di
+        return np.bincount(flat, minlength=p * p * b).reshape(p, p, b).astype(np.uint32)
+
+    def close(self):
+        self._photons = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+
+def imread(filename, pixels=512, binning=1):
+    """Read a `.photons` file and return the `(Y, X)` intensity image."""
+    with PhotonsFile(filename) as f:
+        return f.image(pixels=pixels, binning=binning)

photonsfile-2026.7.8/photonsfile.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: photonsfile
+Version: 2026.7.8
+Summary: Read Photonscore LINCam .photons (D7) files
+Author: Alex Hunt
+License: MIT
+Project-URL: Homepage, https://github.com/alex1075/photonsfile
+Project-URL: D7 format, https://github.com/photonscore/d7
+Keywords: Photonscore,LINCam,D7,photons,TCSPC,FLIM
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: all
+Requires-Dist: numba; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: numba; extra == "test"
+Dynamic: license-file
+
+# photonsfile
+
+Pure-Python reader for Photonscore LINCam `.photons` files (the **D7** container).
+numpy only, with optional numba acceleration for the varint decode.
+
+Photonscore LINCam is a position-sensitive single-photon detector: every photon
+carries an `(x, y)` detector position, a TCSPC micro time (`dt`), and a macro time
+in milliseconds (`ms`). This library decodes those per-photon streams and can bin
+them into an intensity image, a TCSPC decay, or a `(Y, X, H)` FLIM cube.
+
+## The D7 format
+
+A `.photons` file is a paged container: 16 KB pages, each carrying a 2-byte page
+marker, holding a protobuf-style header, a per-dataset index, and an epilogue. Each
+dataset (`/photons/x`, `/photons/y`, `/photons/dt`, `/photons/ms`, and on dual-TDC
+detectors `/start/time` and `/stop/time`) is stored as a seed value followed by
+zigzag-varint delta blocks. `dt` to time is calibrated from the file's
+`/photons/TacChannel` attribute (picoseconds per raw unit).
+
+The format is documented at [github.com/photonscore/d7](https://github.com/photonscore/d7)
+(Apache-2.0). This reader was written from that specification and **validated
+bit-exact against the Photonscore SDK**. No vendor source is redistributed.
+
+## Install
+
+```bash
+pip install photonsfile          # numpy only
+pip install photonsfile[all]     # + numba, for a faster varint decode
+```
+
+## Usage
+
+```python
+from photonsfile import PhotonsFile, imread
+
+with PhotonsFile('sample.photons') as f:
+    ph = f.photons()               # {'x', 'y', 'dt', 'ms'} arrays, one per photon
+    img = f.image(pixels=512)      # (Y, X) intensity image
+    decay = f.decay(bins=256)      # summed TCSPC histogram
+    cube = f.flim_image(512, 256)  # (Y, X, H) FLIM cube
+    dt_res = f.tcspc_resolution(256)   # seconds per bin, from TacChannel
+    print(f.attributes)            # D7 file attributes
+
+img = imread('sample.photons')     # shortcut for the intensity image
+```
+
+Low-level access to the decoder is also exported: `read_header`,
+`read_attributes`, `read_photons`, `dataset_names`, `has_dual_tdc`.
+
+numba is optional; without it the varint decode uses a vectorised numpy fallback.
+`photonsfile.have_numba()` reports which path is active.
+
+## Provenance
+
+Reverse-engineered from the public D7 specification and checked bit-exact against
+the Photonscore SDK on a 284-million-photon sample. Thanks to Photonscore for
+open-sourcing the D7 format.
+
+## License
+
+MIT - see `LICENSE`.

photonsfile-2026.7.8/photonsfile.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+photonsfile/__init__.py
+photonsfile/_d7.py
+photonsfile/photonsfile.py
+photonsfile.egg-info/PKG-INFO
+photonsfile.egg-info/SOURCES.txt
+photonsfile.egg-info/dependency_links.txt
+photonsfile.egg-info/requires.txt
+photonsfile.egg-info/top_level.txt
+tests/test_photonsfile.py

photonsfile-2026.7.8/photonsfile.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

photonsfile-2026.7.8/photonsfile.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy
+
+[all]
+numba
+
+[test]
+pytest
+numba

photonsfile-2026.7.8/photonsfile.egg-info/top_level.txt

@@ -0,0 +1 @@
+photonsfile

photonsfile-2026.7.8/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ['setuptools>=61']
+build-backend = 'setuptools.build_meta'
+
+[project]
+name = 'photonsfile'
+version = '2026.7.8'
+description = 'Read Photonscore LINCam .photons (D7) files'
+readme = 'README.md'
+requires-python = '>=3.10'
+license = { text = 'MIT' }
+authors = [{ name = 'Alex Hunt' }]
+keywords = ['Photonscore', 'LINCam', 'D7', 'photons', 'TCSPC', 'FLIM']
+dependencies = ['numpy']
+
+[project.optional-dependencies]
+all = ['numba']
+test = ['pytest', 'numba']
+
+[project.urls]
+Homepage = 'https://github.com/alex1075/photonsfile'
+'D7 format' = 'https://github.com/photonscore/d7'
+
+[tool.setuptools]
+packages = ['photonsfile']

photonsfile-2026.7.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

photonsfile-2026.7.8/tests/test_photonsfile.py

@@ -0,0 +1,62 @@
+import os
+import glob
+import numpy as np
+import pytest
+import photonsfile
+from photonsfile import PhotonsFile, imread, read_header, have_numba
+
+def _find_sample():
+    pats = [
+        os.path.expanduser('~/Downloads/**/*.photons'),
+        os.path.expanduser('~/Downloads/*.photons'),
+        os.path.join(os.path.dirname(__file__), 'data', '*.photons'),
+    ]
+    for p in pats:
+        hits = sorted(glob.glob(p, recursive=True))
+        if hits:
+            return hits[0]
+    return None
+
+_SAMPLE = _find_sample()
+
+def test_api_surface():
+    for name in ('PhotonsFile', 'imread', 'read_header', 'read_attributes',
+                 'read_photons', 'dataset_names', 'has_dual_tdc', 'MAGIC'):
+        assert hasattr(photonsfile, name)
+    assert isinstance(have_numba(), bool)
+    assert photonsfile.MAGIC == b'D7 Photons Data'
+
+@pytest.mark.skipif(_SAMPLE is None, reason='no .photons sample present')
+def test_read_real_sample():
+    f = PhotonsFile(_SAMPLE)
+    assert f.header['magic'] == 'D7 Photons Data'
+    assert f.position_range >= 2
+    assert isinstance(f.attributes, dict)
+
+    ph = f.photons()
+    assert 'x' in ph and 'y' in ph and 'dt' in ph
+    n = min(len(ph['x']), len(ph['y']), len(ph['dt']))
+    assert n > 0
+
+    img = f.image(pixels=256)
+    assert img.shape == (256, 256)
+    assert int(img.sum()) > 0
+
+    decay = f.decay(bins=256)
+    assert decay.shape == (256,)
+    assert int(decay.sum()) > 0
+
+    cube = f.flim_image(pixels=128, bins=256)
+    assert cube.shape == (128, 128, 256)
+    assert int(cube.sum()) > 0
+    assert int(cube.sum(axis=2).sum()) == int(f.image(pixels=128).sum())
+
+    res = f.tcspc_resolution(256)
+    assert res >= 0.0
+    f.close()
+
+@pytest.mark.skipif(_SAMPLE is None, reason='no .photons sample present')
+def test_imread_matches_method():
+    img = imread(_SAMPLE, pixels=128)
+    assert img.shape == (128, 128)
+    assert np.array_equal(img, PhotonsFile(_SAMPLE).image(pixels=128))