Skip to main content

flimkit-bridge

The local HTTP server that FLIMKit image analysis clients talk to.

Two add-ons use it. The QuPath extension and the Fiji add-on are both clients of this one server, so a fix here reaches both and neither carries its own copy of the API.

It started inside the QuPath add-on and moved out once there were two clients. The wire protocol it speaks was designed and first implemented in flimkit-fiji-bridge by Zhen Yuan Yeo (https://doi.org/10.5281/zenodo.21951612).

Running it

The server starts with FLIMKit. Tools > FLIMKit Bridge... shows its address and whether anything has connected.

It also runs without the desktop app, which is what you want on a headless machine or when QuPath or Fiji is the only front end:

pip install flimkit-bridge
flimkit-bridge

--port and --token are there if you need them, --force takes over from a bridge that has been left running, and --no-announce serves alongside one instead.

Pairing

The server writes its address and a generated token to ~/.flimkit/bridge.json, and clients read that file, so there is nothing to type in. Each start mints a new token, so a client re-reads the file before every call.

It writes ~/.flimkit/qupath-bridge.json alongside it, carrying the same address under the older protocol name. QuPath extensions built before the server moved out check for that name and stop pairing without it. The second file goes when those versions are retired.

Z-stacks

POST /v1/zstack runs FLIMKit's z-stack fit over a folder of slices, one file per slice named region_z1.ptu, region_z2.ptu and so on. A folder holding several regions is fitted as several stacks in one run.

POST /v1/zstack/scan   {"ptu_dir": "/path/slices"}
POST /v1/zstack        {"ptu_dir": "/path/slices", "params": {"n_exp": 2, "z_step_um": 2.0}}
GET  /v1/zstack/defaults
POST /v1/zstack/export {"group_dir": "/path/out/RegionA", "format": "ome-tiff"}

The scan is there so a client can say what it found before offering any settings, and refuse an empty folder without starting a job. The fit itself runs as a job, so GET /v1/jobs/{id} reports progress by slice and DELETE cancels at the next one.

Each stack is fitted as one FOV: the decay is pooled over every slice, the lifetimes are fitted once from the pooled decay and locked, and each slice then gets a per-pixel fit with only the amplitudes free. A single slice rarely carries the photons to identify two lifetimes; the stack usually does.

Each stack comes back as an OME-Zarr store, a (C, Z, Y, X) volume with a channel per map: intensity in photons, tau_mean_int and tau_mean_amp in ns, an alpha_N per component, and the bound fraction and chi-squared maps when they were computed. zarr and ome-zarr are dependencies of this package, not an extra, so the store is always what a client gets unless it asks for something else. ome-tiff is that something else, same channels and same axes, for a viewer that will not read the store; /v1/zstack/export rewrites a finished run in either format without fitting it again, which is also how to correct a z step entered wrong.

The store carries one resolution level on purpose. A pyramid is built by interpolating between neighbours, and a lifetime map is mostly NaN where nothing was fitted, so the coarse levels a viewer shows when zoomed out would smear that NaN over the pixels that did fit. Chunking, one chunk per slice per channel, is what keeps a large volume readable.

FLIMKit's own per-slice .npy maps, _zseries.csv and _zseries.json are left where it writes them, and the reply names them. Its per-slice PNGs and detail plots are off by default here, since each one costs a second summed fit per slice; save_plots turns them back on.

When the client cannot see the disk

The reply names a path, so a client on the same machine opens the store itself and nothing large goes over HTTP. Over a forwarded port that path means nothing locally, and for that there is:

GET /v1/zstack/volume.ome.tif?group_dir=/path/out/RegionA&z_step_um=2.0

which builds the volume from the same slice maps and streams it as one OME-TIFF, in blocks out of a temporary file rather than through one bytes object, since a fitted stack is routinely larger than memory. The temporary file goes whether the transfer finished or not. Shape, channels, units and voxel size ride on X-FLIMKit-Volume-* headers, and the store on the server is left alone.

The slices themselves are still a server-side path: ptu_dir is opened by FLIMKit, not uploaded. A forwarded client picking a local folder gets a 404 naming the folder, before any job starts.

Versions

GET /v1/status reports protocol_version, bridge_version and flimkit_version. A client checks protocol_version, which is what governs whether the two can talk. bridge_version is for display: the server and each client version independently now, so a difference between them is ordinary rather than a problem.

Security

The server listens on 127.0.0.1 only, and refuses any request whose Host header is not localhost, which stops a web page reaching it by resolving its own hostname to your machine. Every endpoint except the status check requires the token.

Both programs therefore have to be on the same machine. If they are not, forward the port over SSH rather than exposing it:

ssh -L 8765:127.0.0.1:8765 you@the-flimkit-machine

Licence

MIT. See LICENSE.md.

Metadata

Release files for flimkit-bridge 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flimkit-bridge 0.9.0
File Size Uploaded Provenance Actions
flimkit_bridge-0.9.0.tar.gz 77.1 kB With provenance Details for flimkit_bridge-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flimkit-bridge 0.9.0
File Interpreter ABI Platform Actions
flimkit_bridge-0.9.0-py3-none-any.whl Python 3 none any Details for flimkit_bridge-0.9.0-py3-none-any.whl

Total release size: 124.0 kB

Release files / flimkit_bridge-0.9.0.tar.gz

Download URL flimkit_bridge-0.9.0.tar.gz
Size 77.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b42f25e30a1444a55bcbad7b79ee9b777bff15522020fe6f3b1d263a46d6167c
BLAKE2b-256 checksum
How to use checksums
86888845d58f822557bba16ce168114ec29ca09871d79cf6b3983af346511e62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / flimkit_bridge-0.9.0-py3-none-any.whl

Download URL flimkit_bridge-0.9.0-py3-none-any.whl
Size 46.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
19f5e58be09d7d8e96b60a3323cb94869473ca3417f778b5fd3676b2704fae71
BLAKE2b-256 checksum
How to use checksums
da78d13d782b76ee63e31defa5251d2f5289f7b7d8bd85fec5c0ea542bf8b1cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for flimkit-bridge 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for flimkit_bridge-0.9.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page