tme-quant

Python translation of CurveAlign with the goal of unifying cell and collagen analysis, provided as a modern Python src/ package and a napari plugin.

About this repo

• src/pycurvelets: Python implementation using the curvelet transform
• src/napari_curvealign: napari plugin surface for interactive use
• tests/: pytest suite (data-driven tests and headless napari smoke test)
• .github/workflows/ci.yml: GitHub Actions workflow (runs core tests only)

Licensing and prerequisites

This project depends on code that cannot be redistributed here:

• CurveLab (FDCT/FDCT3D) and FFTW 2.x are separately licensed. You must accept their licenses and build them locally if you want the optional curvelet backend (curvelops).

Base requirements:

• macOS, Linux, or Windows (see notes below)
• Conda (recommended) or Python 3.10–3.13
• For napari: a Qt binding (PyQt or PySide)

Quick start (without curvelets)

Install the package and the napari GUI. This path avoids the native curvelet build.

conda create -y -n napari-env -c conda-forge python=3.11 pip
conda activate napari-env

# project install (editable)
pip install -e .

# napari + Qt
conda install -y -c conda-forge napari pyqt qtpy

Optional: curvelet backend (curvelops)

To enable curvelet-powered features and tests you must build and install FFTW 2.1.5 and CurveLab, then install curvelops.

macOS/Linux outline:

# 1) Build FFTW 2.1.5 (C only)
curl -L -O http://www.fftw.org/fftw-2.1.5.tar.gz
 tar xzf fftw-2.1.5.tar.gz
 cd fftw-2.1.5
 # If configure fails on macOS due to outdated config.{sub,guess}, update them from your system
 ./configure --prefix="$HOME/opt/fftw-2.1.5" --disable-fortran
 make -j$(sysctl -n hw.logicalcpu 2>/dev/null || nproc)
 make install
 export FFTW="$HOME/opt/fftw-2.1.5"

# 2) Build CurveLab 2.1.x
export FDCT="/path/to/CurveLab-2.1.x"
 cd "$FDCT/fdct_wrapping_cpp/src" && make
 cd "$FDCT/fdct/src" && make
 cd "$FDCT/fdct3d/src" && make

# 3) Install build tooling and curvelops
conda activate napari-env
 python -m pip install -U pip
 pip install pybind11 scikit-build-core cmake ninja
 export FFTW="$HOME/opt/fftw-2.1.5"
 export FDCT="/path/to/CurveLab-2.1.x"
 pip install -v "curvelops @ git+https://github.com/PyLops/[email protected]"

Windows options:

• Recommended: use WSL2 (Ubuntu). Follow the macOS/Linux steps inside WSL.
• Native Windows: use MSYS2 (for gcc, make) or Visual Studio toolchain; build FFTW 2.1.5 and CurveLab from source, set FFTW and FDCT env vars to their install roots, then install curvelops as above. Supervisors can validate these steps on a Windows host.

Development: running the tests

• Headless (no GUI): set Qt to offscreen

  • macOS/Linux: export QT_QPA_PLATFORM=offscreen
  • Windows/PowerShell: $env:QT_QPA_PLATFORM = 'offscreen'

• Core tests (no curvelets):

pytest -q

• Full tests with curvelets (after installing curvelops):

export TMEQ_RUN_CURVELETS=1
pytest -q

Notes:

• The napari test is an import-only smoke test (no Viewer is created); it runs headless.

Testing policy:

• Tests must not write files to the repository root. Use a system temporary directory instead (e.g., tempfile.TemporaryDirectory).
• If a deterministic artifact is needed across runs, commit it under tests/test_resources/ and read from there during tests.

Continuous integration

• CI installs the package without curvelops to avoid building FFTW/CurveLab on runners.
• CI environment:
  • TMEQ_RUN_CURVELETS=0 (curvelet tests skipped)
  • QT_QPA_PLATFORM=offscreen (headless napari import)

Working with secrets in GitHub Actions

This project uses GitHub Actions secrets for tasks that require authentication or access to private resources. Secrets can be configured in the Settings tab of the repostiory. For more information about secrets, see:

• Secrets as a concept
• Secrets in actions.

Manual testing workflow

The manual-test workflow allows developers to manually trigger workflows from the GitHub UI without committing changes to main. This is useful for testing workflows that require secrets on topic branches.

How to use it:

1. Create or edit .github/workflows/test-action.yml to define your workflow's structure and declare which secrets it needs via the secrets: input in workflow_call:

on:
  workflow_call:
    secrets:
      MY_SECRET_NAME:
      ANOTHER_SECRET:

jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Use a secret
        run: echo "Secret is ${{ secrets.MY_SECRET_NAME }}"

2. The manual-test workflow (.github/workflows/manual-test.yml) will call test-action.yml and pass repository secrets to it via secrets: inherit.

3. To trigger the workflow:

   • Push your branch with the updated test-action.yml to GitHub.
   • Go to the Actions tab in the repository and select the Manual Testing Stub workflow.
   • Click Run workflow and select your branch.
   • The workflow will execute with access to all secrets configured for the repository.

NOTE

• Never hardcode secrets or access tokens in workflow files; always use the secrets: context.

Troubleshooting

• Qt error ("No Qt bindings could be found"): install pyqt (or pyside2) from conda-forge.
• Segfault on Viewer creation: avoid creating a napari.Viewer() in tests; we only import napari and run offscreen.
• curvelops build errors: ensure FFTW and FDCT point to your install roots and the 2D/3D libraries were built.