FLIMKitPlugins / FLIMKit-QuPath-Bridge / Protocol · edit on GitHub
Protocol
Localhost HTTP with a bearer token. The endpoint shapes come from flimkit-fiji-bridge, where they were designed and first implemented.
The two are no longer interchangeable. They report different protocol identifiers, and this one adds a discovery file for pairing and refuses requests whose Host header is not localhost. A client written for one needs those three differences accounted for before it will work against the other.
protocol is flimkit-qupath and protocol_version is 1.
Endpoints
| Method | Path | Auth | Returns |
|---|---|---|---|
| GET | /v1/status |
none | {"protocol": ..., "protocol_version": 1} |
| GET | /v1/images/{id}.tif |
token | float32 TIFF |
| GET | /v1/rois |
token | GeoJSON FeatureCollection |
| POST | /v1/rois |
token | {"received_features": n} |
{id} is intensity or lifetime. An image that has not been calculated gives 404.
Image responses carry X-FLIMKit-Value-Unit, which is photons or ns. QuPath stores it as the image's calibration value unit.
Authentication
Every endpoint except /v1/status requires:
Authorization: Bearer <token>
The token is generated fresh each time FLIMKit starts and written to ~/.flimkit/qupath-bridge.json along with the address and the FLIMKit process id.
Coordinates
ROIs are image pixels, [x, y], origin top-left, fractional coordinates preserved. FLIMKit's own exports carry a flimkit block stating exactly that.
Polygon rings are closed, so the first and last positions are equal and a triangle has four. This is what RFC 7946 requires and what QuPath's JTS-backed parser insists on.
Why localhost only
The server binds 127.0.0.1 and refuses any request whose Host header is not localhost. Without that check a web page you visit could resolve its own hostname to your machine and reach the bridge, which is a real attack rather than a theoretical one. The token is the second line of defence.
Both programs therefore have to be on the same machine. If they are not, forward the port over SSH rather than exposing the service:
ssh -L 8765:127.0.0.1:8765 you@the-flimkit-machine
QuPath then connects to http://127.0.0.1:8765 as though it were local, and SSH provides the encryption and authentication. Use Connect to a different address..., since the discovery file will not be present on the QuPath machine.