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)
• Python 3.11+
• uv (recommended) or pip
• napari uses PyQt6 (included in dependencies)

Quick start (without curvelets)

uv sync
uv run napari

Optional: curvelet backend (curvelops)

To enable curvelet-powered features and tests you must build FFTW 2.1.5 and CurveLab, then install with curvelops. Use the automated script:

Prerequisites: Clone this repo, install uv, and download CurveLab to ../utils (see doc/INSTALL.md).

macOS/Linux:

bash bin/install.sh
# or: make setup

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 use uv commands as above.

Development

See doc/DEVELOPMENT.md for plugin setup and troubleshooting. Running 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):

make test

• Full tests with curvelets (after installing curvelops): make test — curvelet tests run automatically when curvelops is available; otherwise skipped.

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:
  • Curvelet tests skipped (curvelops not installed on CI)
  • 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"): ensure uv sync completed; pyproject includes PyQt6.
• 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.