Troubleshooting

Application won’t start

“No module named flametrack”

The package is not installed. Run:

pip install flametrack

or, for a developer install:

pip install -e ".[dev]"

Black screen / window does not appear on Linux

Make sure a display server is running. For headless servers, install Xvfb:

sudo apt-get install xvfb
xvfb-run flametrack

Loading data

“FileNotFoundError” when opening an experiment

FlameTrack looks for raw data under the path configured in config.ini. Check that experiment_folder points to the correct directory and that the experiment sub-folder with exported_data/ exists inside it. See Configuration for details.

HDF5 file cannot be opened

If a previous run crashed mid-write, the HDF5 file may be corrupt. Delete the .h5 file in the processed_data folder and rerun dewarping and edge detection.

Dewarping

Control points snap to wrong position

Zoom in before placing control points — the click target is larger relative to the image when zoomed out. Use the delete button to remove a misplaced point and re-place it.

Dewarped image looks stretched

The source rectangle defined by the four corner points should match the true physical aspect ratio of the wall panel. Re-check the point placement.

Edge detection

Edge detection produces no results / all NaN

• Verify that dewarped data exists (run dewarping first).

• Try a lower threshold value or a different edge method.

• Check that the flame is actually visible in the dewarped frames.

Edge detection is very slow

Edge detection runs one worker thread per frame. On machines with few CPU cores, large datasets take longer. Progress is shown in the status bar.

Tests / development

pytest aborts with “Aborted (core dumped)” on macOS

PyQtGraph widget tests crash in headless terminals because no display is available. The test_imshow_canvas tests are automatically skipped when QT_QPA_PLATFORM=offscreen is set. Run the unit suite instead:

pytest tests/unit/

pre-commit hook fails with ruff errors

Run ruff locally to see and auto-fix the issues:

ruff check --fix src/
ruff format src/

Then stage the changes and commit again.