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 :doc:`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.