Troubleshooting

Troubleshooting

Gatekeeper blocks the compiled app on macOS
Right-click → Open on first launch. After that it should run normally.

Machine IRF not found after saving
Restart the app - the default IRF path is resolved at startup and won't update mid-session.

Per-pixel fitting is very slow
That's expected for large FOVs on CPU. Try increasing --binning to aggregate pixels before fitting, or switch to summed-only mode if you don't need spatial maps. If you have a supported GPU (Apple Silicon, NVIDIA, AMD) and ran python install.py, GPU acceleration is detected and used automatically, no extra flags needed. Note that --free-tau-perpixel with n_exp ≥ 2 uses batched Adam on GPU; it only falls back to CPU when no backend is detected.

Tile stitching produces visible seams
Check that the max drift setting isn't too restrictive. If registration looks fine but seams persist, it's likely a sample contrast issue at tile boundaries rather than a registration failure.

ROI holes are lost on GeoJSON import
Known limitation... Only the outer boundary is imported. Donut-shaped ROIs with holes lose the hole geometry on import.

Phasor calibration looks off
Make sure the IRF file is from the same acquisition session. XLSX-based IRFs from FLIM microscope software can vary between sessions, which is why the machine IRF exists.

Lifetimes are slightly higher than FLIM microscope software for the same data
This is expected and systematic. FLIMKit anchors the IRF at the steepest-rise point of the leading edge, which differs from how FLIM microscope software places the IRF. The offset is consistent across acquisitions and does not indicate a fitting problem.