Merge openptv

[alexlib]

This pull request modernizes the development, testing, and installation workflows for openptv-python, focusing on Python version updates, backend flexibility, and improved documentation. It introduces support for Python 3.12 and 3.13, adds a compatibility layer for native optv bindings, and significantly enhances the README and developer documentation to clarify backend selection and installation methods. The CI/CD pipeline is updated for newer GitHub Actions and Python versions, and pre-commit hooks are refreshed for better code quality.

Python Version and Backend Support

• Updated the project to support Python 3.12 and 3.13 throughout all workflows, Dockerfile, and documentation, making these the primary supported versions (>=3.12,<3.14). [1] [2] [3] [4]
• Added a new _native_compat.py module to provide an optional compatibility layer for native optv bindings, enabling automatic delegation to native implementations for image preprocessing and target recognition when available.
• Enhanced the README and documentation to clearly explain backend options (pure Python, Python+Numba, native optv), installation methods (uv, pip, conda), and backend capability matrix. (F6466639L1R1, [1] [2]

CI/CD and Tooling Modernization

• Updated all GitHub Actions in .github/workflows to their latest major versions (e.g., actions/checkout@v6, actions/setup-python@v6, actions/download-artifact@v7, actions/upload-artifact@v6), and switched CI jobs to use Python 3.12/3.13. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]
• Upgraded pre-commit hooks and related dependencies to their latest versions for improved code quality and compatibility. [1] [2]
• Added types-PyYAML to development dependencies for better type checking.
• Improved Makefile to allow specifying the Python interpreter and to use python -m for all tooling calls, ensuring compatibility with virtual environments.

Documentation and Linting

• Expanded documentation to clarify installation, backend selection, and developer workflow, including new sections in README.md and docs/index.md. (F6466639L1R1, [1] [2]
• Made the Sphinx autoapi extension optional via an environment variable to avoid unnecessary build requirements for users.
• Updated mypy.ini to exclude build and temporary directories from type checks.

Template and Dependency Updates

• Synced the project template to the latest commit from the upstream cookiecutter-conda-package. [1] [2]

These changes collectively make the project easier to install, develop, and contribute to, while ensuring robust backend flexibility and modern development practices.

[Copilot]

Pull request overview

This large PR modernizes openptv-python by updating Python version support (3.12/3.13), adding a native optv compatibility layer for optional delegation of image preprocessing and target recognition, rewriting core image processing functions to match native C behavior, fixing multi-layer multimedia refraction and angle computation bugs, adding a synthetic test cavity case for bundle adjustment validation, and updating CI/CD workflows and tooling.

Changes:

• Added _native_compat.py and _native_convert.py for optional native optv backend delegation, rewriting image_processing.py (box blur, lowpass, subtract) and segmentation.py to match liboptv behavior, with parity tests.
• Fixed multimed.py per-layer refraction loop, parameters.py set_layers nlay sync, and track.py angle_acc cosine clamping and zero-norm guard.
• Added comprehensive synthetic cavity test case data, calibration_compare.py utility, new tests, and updated CI to Python 3.12/3.13 with modernized GitHub Actions and pre-commit hooks.

Reviewed changes

Copilot reviewed 95 out of 98 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
openptv_python/_native_compat.py	New optional import layer for optv native modules
openptv_python/_native_convert.py	Conversion helpers between Python and native optv objects
openptv_python/calibration_compare.py	New CLI tool for comparing calibration folders
openptv_python/image_processing.py	Rewritten box blur, lowpass, subtract to match native C; native delegation
openptv_python/segmentation.py	Native target recognition delegation for full-frame case
openptv_python/parameters.py	Fix set_layers to update nlay
openptv_python/multimed.py	Fix per-layer refraction loop for multi-layer case
openptv_python/track.py	Fix angle_acc with cosine clamping and zero-norm guard
openptv_python/tracking_frame_buf.py	Pre-check file existence in Frame.read
tests/test_synthetic_cavity_case.py	Bundle adjustment recovery tests on synthetic data
tests/test_segmentation.py	Native vs Python parity test for target recognition
tests/test_image_processing.py	Corrected expected values; native parity test
tests/test_point_positions.py	Multi-camera reconstruction parity tests
tests/test_multimedia_n_lay.py	Multi-layer refraction and reconstruction parity tests
tests/test_calibration_compare.py	Tests for calibration comparison utility
tests/test_read_frame.py	Test for missing linkage file handling
tests/test_tracking.py	Additional angle_acc test case
tests/testing_fodder/test_cavity_synthetic/*	Synthetic test fixture data files
tests/testing_fodder/test_cavity/parameters_Run1.yaml	YAML parameters for test cavity
pyproject.toml	Updated Python versions, dependencies, optional extras
Makefile	Configurable Python interpreter
Dockerfile	Updated to Python 3.12
.pre-commit-config.yaml	Updated hook versions
.github/workflows/*	Updated Actions versions and Python versions
docs/conf.py, docs/index.md	Optional autoapi, updated docs
README.md	Expanded backend/installation documentation
mypy.ini, .gitignore, .cruft.json, ci/environment-ci.yml	Minor config updates

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.