Flatten pyptv into subfolder

Author: alexlib

src/pyptv

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to PyPTV are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.3] - 2026-03-13
+
+### Added
+- `ptv.clone_calibration` helper for calibration workflows
+- Marimo-based UI additions for interactive workflows
+- Tests covering writable output folder behavior
+
+### Changed
+- Widened `_ensure_target_output_writable` type annotations to accept `Sequence[str | os.PathLike]`
+- Updated release helper scripts to report the current PyPTV version consistently
+
+### Fixed
+- Results directory test handling
+- Skipped test behavior in the automated test suite
+- Misleading version messages in Windows installation helpers
+
+## [0.4.2] - 2026-03-01
+
+### Added
+- NumPy 2.0+ support with full compatibility for NumPy 2.x series
+- `build_wheels.sh` script for building universal wheels
+- Local wheel installation support in `wheels/` folder
+- Installation scripts now support installing from pre-built wheels
+
+### Changed
+- **NumPy**: Updated from `==1.26.4` to `>=2.0.0,<2.7` (supports NumPy 2.x)
+- **optv**: Updated from `>=0.3.0` to `>=0.3.2` (includes NumPy 2.0+ support)
+- **chaco**: Updated from `>=5.1.0` to `>=6.1.0` (NumPy 2 compatible)
+- **enable**: Updated from `>=5.3.0` to `>=6.1.0` (NumPy 2 compatible)
+- Installation scripts (`install_pyptv.sh`, `install_pyptv.bat`) now install optv from local wheel first
+- Test version checks updated to validate NumPy >=2.0.0
+
+### Fixed
+- Version checks in `tests/test_environment.py` now accept version range instead of exact version
+- Version checks in `scripts/verify_environment.py` updated for NumPy 2.x compatibility
+
+### Technical Details
+- pyptv is now distributed as a universal wheel (`py3-none-any`) compatible with Python 3.10+
+- optv 0.3.2 requires NumPy >=2.0.0 (handled by local wheel in `wheels/` folder)
+- All GUI dependencies (traitsui 8.0.0, pyface 8.0.0, chaco 6.1.1, enable 6.1.0) verified compatible with NumPy 2.x
+
+### Installation
+```bash
+# Using uv (recommended)
+uv venv --python 3.11
+source .venv/bin/activate
+uv pip install wheels/optv-0.3.2-*.whl
+uv pip install wheels/pyptv-0.4.2-py3-none-any.whl
+
+# Or install in editable mode
+uv pip install -e .
+```
+
+### Migration Notes
+- **Minimum NumPy version**: 2.0.0 (NumPy 1.x no longer supported)
+- **optv requirement**: 0.3.2+ with NumPy 2.0+ support
+- Existing installations should update optv to 0.3.2 or later
+
+---
+
+## [0.4.1] - Previous Release
+
+See git history for details of previous releases.

src/pyptv/CHANGES.md

@@ -0,0 +1,32 @@
+# Slim Dockerfile for local testing of pyptv (mimics GitHub Actions)
+FROM python:3.11-slim
+
+# Install system dependencies for Qt, traitsui, and scientific stack
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libxkbcommon-x11-0 \
+    libxcb-xinerama0 \
+    git \
+    xvfb \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set workdir
+WORKDIR /workspace
+
+# Copy repo
+COPY . /workspace
+
+# Install pip, wheel, and setuptools
+RUN pip install --upgrade pip wheel setuptools
+
+# Install pyptv and dependencies
+RUN pip install .
+RUN pip install -r requirements-dev.txt || true
+
+# Optionally install test dependencies for Qt
+RUN pip install PySide6 traits traitsui pytest
+
+# Run all tests
+CMD ["xvfb-run", "pytest", "-v", "-x", "--tb=short"]

src/pyptv/Dockerfile

@@ -0,0 +1,20 @@
+Copyright (c) 2011-2022 Alex Liberzon
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

src/pyptv/LICENSE.txt

@@ -0,0 +1,162 @@
+# Project Title
+
+[![Python application](https://github.com/alexlib/pyptv/actions/workflows/python-app.yml/badge.svg)](https://github.com/alexlib/pyptv/actions/workflows/python-app.yml)
+[![DOI](https://zenodo.org/badge/121291437.svg)](https://zenodo.org/badge/latestdoi/121291437)
+[![PyPI - Version](https://img.shields.io/pypi/v/pyptv)](https://pypi.org/project/pyptv/)
+
+
+
+
+
+**PyPTV** or otherwise called **OpenPTV-Python** is the Python GUI for [OpenPTV](http://www.openptv.net). It is based on `traits`, `traitsui`, `chaco`, `enable` and `pyface` from Enthought Inc. and provides an UI *interface* the OpenPTV library that includes all the core algorithms (correspondence, tracking, calibration, etc.) written in ANSI C and has Python bindings using Cython.  
+
+Both PyPTV and the OpenPTV library are in the development phase and continuously refactored. Please follow the development on the community mailing list:
+
+  openptv@googlegroups.com
+
+
+## Documentation:
+
+ 👉 **[View PyPTV documentation](https://alexlib.github.io/pyptv)**
+ 👉 **[View OpenPTV documentation](https://openptv-python.readthedocs.io/en/latest/))**
+
+## Installation instructions
+
+### Using uv (recommended for development)
+
+This project uses [uv](https://github.com/astral-sh/uv) for fast dependency management. A local wheel of `optv>=0.3.2` is included in the `wheels/` directory until it's available on PyPI.
+
+```bash
+# Install uv if you haven't already
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv sync
+
+# Or to create environment from scratch
+rm -rf .venv && uv sync
+```
+
+The `uv.toml` configuration automatically uses the local wheel from `wheels/`. The `uv.lock` file pins all dependencies for reproducible builds.
+
+### Using pip
+
+Short version:
+
+    pip install numpy
+    python -m pip install pyptv --index-url https://pypi.fury.io/pyptv --extra-index-url https://pypi.org/simple
+
+**Note:** If `optv>=0.3.2` is not yet available on PyPI, install it from the local wheel first:
+
+    pip install wheels/optv-0.3.2-*.whl
+    python -m pip install pyptv --index-url https://pypi.fury.io/pyptv --extra-index-url https://pypi.org/simple
+
+Detailed instructions for various platforms are in our documentation:
+https://openptv-python.readthedocs.io/en/latest/installation_instruction.html
+
+
+
+
+
+Follow the instructions in our **screencasts and tutorials**:
+  
+  *  Tutorial 1: <http://youtu.be/S2fY5WFsFwo>  
+  
+  *  Tutorial 2: <http://www.youtube.com/watch?v=_JxFxwVDSt0>   
+  
+  *  Tutorial 3: <http://www.youtube.com/watch?v=z1eqFL5JIJc>  
+  
+  
+Ask for help on our mailing list:
+
+  openptv@googlegroups.com
+
+
+
+## Working with plugins
+
+Plugins is a system of extensions to PyPTV without the need to change the GUI
+
+1. copy the `sequence_plugins.txt` and `tracking_plugins.txt` to the working folder
+2. copy the `plugins/` directory to the working folder
+3. modify the code so it performs instead of the default sequence or default tracker
+4. Open the GUI and Plugins -> Choose , then run the rest: Init -> Sequence 
+
+
+Note, the specific branch `plugin_remback` requires installation of the `pip install rembg[cpu]` or `pip install rembg[gpu]`
+
+
+### Developers:
+
+**Version Management:**
+- Bump version: ```python bump_version.py --patch```
+
+**Publishing to PyPI:**
+- See [DEPLOYMENT.md](DEPLOYMENT.md) for comprehensive deployment instructions using GitHub Actions and trusted publishing
+
+**Legacy Manual Publishing:**
+```bash
+pip install build
+python -m build
+pip install dist/pyptv-*.whl  # Install the built wheel
+pip install twine
+python -m twine upload dist/*
+```
+
+## Compatibility Notes
+
+### NumPy Compatibility
+- Supported NumPy versions: >=2.0.0,<2.7
+- NumPy 2.x required for optv 0.3.2+
+- Tested with NumPy arrays in both float64 and uint8 formats
+- Array operations maintained for image processing and coordinate transformations
+- NumPy 2.x support requires chaco>=6.1.0 and enable>=6.1.0
+
+### OpenPTV (optv) Compatibility
+- Compatible with optv 0.3.2+
+- optv 0.3.2+ requires NumPy >=2.0.0
+- Core functionality tested with latest optv release
+- Calibration and tracking functions verified
+
+## Development Setup
+For development work with latest NumPy:
+
+```bash
+conda create -n pyptv python=3.11
+conda activate pyptv
+conda install numpy>=1.23.5 optv>=0.3.0
+pip install -e .
+```
+
+## Marimo UIs (uv)
+
+This repo includes Marimo-based interactive UIs.
+
+Run the Detection UI:
+
+```bash
+uv pip install marimo
+uv run marimo run pyptv/marimo_ui_detection.py
+```
+
+Or use the helper script:
+
+```bash
+./run_marimo_detection.sh
+```
+
+Run the Parameters UI:
+
+```bash
+uv pip install marimo
+uv run marimo run pyptv/marimo_ui_parameters.py
+```
+
+Or use the helper script:
+
+```bash
+./run_marimo_parameters.sh
+```
+
+
+This is a detailed description of the project...

src/pyptv/README.md

@@ -0,0 +1,22 @@
+# Dumbbell orientation notes
+
+## Error context
+- SciPy minimize reports: "Desired error not necessarily achieved due to precision loss."
+- The optimizer returns almost the same parameters as the initial guess.
+
+## Call path
+- GUI button: calibration_gui.py -> _button_orient_dumbbell_fired -> ptv.py_calibration(12, self)
+- Dispatch: ptv.py -> py_calibration -> calib_dumbbell
+- Objective + optimizer: ptv.py -> dumbbell_target_func, calib_convergence, minimize
+
+## Likely cause
+- Poor scaling and weak constraints (all cameras free).
+- Objective mixes positions (~1e3) and angles (~1e0), plus abs() term for length.
+
+## Improvement ideas
+1) Fix at least one camera (anchor the gauge) or allow fixed cameras in the GUI flow.
+2) Scale parameters (e.g., optimize positions in meters or divide by 1000).
+3) Use a more robust optimizer (Powell or L-BFGS-B with bounds) or least_squares on residuals.
+4) Replace abs() in dumbbell length error with squared or Huber loss.
+5) Ensure enough valid frames with exactly 2 targets per camera; use cleaner subset.
+6) Tune dumbbell_penalty_weight to avoid dominating/flattening the objective.