Add comprehensive GitHub Copilot instructions for OpenPIV development workflow

.github/copilot-instructions.md

@@ -0,0 +1,120 @@
+# OpenPIV Python
+
+OpenPIV is a Python and Cython library for Particle Image Velocimetry (PIV) analysis of fluid flow images. It provides tools for scripting and executing PIV analysis on image pairs to extract velocity fields from particle-seeded flow visualizations. The library includes both computational algorithms and optional Qt/Tk graphical user interfaces.
+
+**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
+
+## Working Effectively
+
+### Bootstrap and Install Dependencies
+- **Primary method (recommended)**: Use Poetry for development:
+  - Install Poetry: `pip install poetry` 
+  - Install dependencies: `poetry install` -- takes ~10 seconds. NEVER CANCEL.
+  - All development commands should use `poetry run <command>`
+
+### Alternative Installation Methods
+- **From PyPI**: `pip install openpiv` -- takes ~33 seconds. NEVER CANCEL.
+- **From conda-forge**: `conda install -c conda-forge openpiv` -- takes ~46 seconds. NEVER CANCEL.
+- **Build from source**: `python setup.py build_ext --inplace` -- takes <1 second (no Cython extensions in current setup)
+
+### Build and Test the Repository
+- **Run tests**: `poetry run pytest openpiv -v` -- takes ~12 seconds, 198 tests pass, 12 skipped. NEVER CANCEL. Set timeout to 30+ minutes for safety.
+- **Test import**: `poetry run python -c "import openpiv; print('OpenPIV imported successfully')"`
+- **Test core functionality**: `poetry run python -c "import openpiv.piv as piv; import numpy as np; frame_a = np.random.rand(64, 64); frame_b = np.random.rand(64, 64); result = piv.simple_piv(frame_a, frame_b); print('PIV analysis completed, returned:', len(result), 'outputs')"`
+
+### Run Example Workflows
+- **Tutorial 1**: `poetry run python openpiv/tutorials/tutorial1.py` -- demonstrates complete PIV analysis workflow
+- **Test data location**: `openpiv/data/test1/` contains sample image pairs (`exp1_001_a.bmp`, `exp1_001_b.bmp`)
+
+## Validation
+
+### ALWAYS run these validation steps after making changes:
+1. **Import test**: Verify basic import works: `poetry run python -c "import openpiv"`
+2. **Core functionality test**: Run simple PIV analysis to ensure algorithms work
+3. **Full test suite**: `poetry run pytest openpiv -v` -- NEVER CANCEL, takes ~12 seconds but allow 30+ minutes timeout
+4. **Tutorial execution**: Run `poetry run python openpiv/tutorials/tutorial1.py` to test complete workflow
+
+### Critical User Scenarios to Test
+After making changes, ALWAYS test these scenarios:
+- **Basic PIV Analysis**: Load two images, run PIV analysis, get velocity fields
+- **Data Loading**: Import test images from `openpiv/data/test1/`
+- **Validation and Filtering**: Apply signal-to-noise filtering and outlier detection
+- **File I/O**: Save and load PIV results in vector field format
+
+### CI/CD Validation
+- The repository has GitHub Actions workflows in `.github/workflows/`:
+  - `testing.yml`: Runs tests on Python 3.10, 3.11, 3.12 with Poetry
+  - `build.yml`: Builds and publishes to PyPI on releases
+- No linting tools are configured (no black, flake8, etc.)
+
+## Common Tasks
+
+### Repository Structure
+```
+openpiv/
+├── __init__.py          # Main package initialization
+├── piv.py              # High-level PIV analysis functions
+├── pyprocess.py        # Core PIV processing algorithms
+├── pyprocess3D.py      # 3D PIV algorithms
+├── tools.py            # Utility functions for I/O and visualization
+├── validation.py       # Signal validation and filtering
+├── filters.py          # Outlier detection and replacement
+├── windef.py           # Window deformation PIV
+├── scaling.py          # Coordinate scaling and transformation
+├── preprocess.py       # Image preprocessing
+├── smoothn.py          # Smoothing algorithms
+├── data/               # Sample test data
+├── test/               # Comprehensive test suite (210 tests)
+├── tutorials/          # Example scripts
+└── docs/              # Documentation source
+```
+
+### Key APIs and Usage Patterns
+- **Simple PIV**: `piv.simple_piv(frame_a, frame_b)` returns `(x, y, u, v, s2n)`
+- **Extended search area**: `pyprocess.extended_search_area_piv()` for higher accuracy
+- **Window deformation**: `windef` module for advanced PIV with iterative refinement
+- **File I/O**: `tools.imread()`, `tools.save()`, `tools.display_vector_field()`
+- **Validation**: `validation.sig2noise_val()`, `validation.global_val()`
+- **Filtering**: `filters.replace_outliers()` for cleaning velocity fields
+
+### Project Management
+- **Dependencies**: Managed via Poetry (`pyproject.toml`) and fallback setuptools (`setup.py`)
+- **Package name**: "OpenPIV" (capital letters)
+- **Version**: 0.25.3 (defined in both `pyproject.toml` and `setup.py`)
+- **Python support**: 3.10, 3.11, 3.12
+- **Key dependencies**: numpy, scipy, scikit-image, matplotlib, imageio
+
+### Development Notes
+- Uses `importlib_resources` for accessing package data files
+- Test configurations in `openpiv/test/conftest.py` disable plotting for CI
+- Sample data includes real PIV image pairs for testing workflows
+- Documentation built with Sphinx (source in `openpiv/docs/`)
+- External examples repository: [OpenPIV-Python-Examples](https://github.com/OpenPIV/openpiv-python-examples)
+
+### Common Command Reference
+```bash
+# Development setup
+poetry install                                          # ~10 seconds
+poetry run pytest openpiv -v                          # ~12 seconds, 198 tests pass
+
+# Testing functionality  
+poetry run python openpiv/tutorials/tutorial1.py      # Complete PIV workflow
+poetry run python -c "import openpiv.piv as piv; ..."  # API test
+
+# Alternative installs
+pip install openpiv                                    # ~33 seconds
+conda install -c conda-forge openpiv                  # ~46 seconds
+
+# Build from source (minimal - no Cython compilation needed)
+python setup.py build_ext --inplace                   # <1 second
+```
+
+### Timing Expectations and Timeouts
+- **Poetry install**: ~10 seconds (set 5+ minute timeout)
+- **Test suite**: ~12 seconds (set 30+ minute timeout for safety)
+- **Tutorial execution**: ~1-2 seconds  
+- **Pip install**: ~33 seconds (set 10+ minute timeout)
+- **Conda install**: ~46 seconds (set 15+ minute timeout)
+- **Build from source**: <1 second (no Cython compilation currently)
+
+**CRITICAL: NEVER CANCEL long-running commands. PIV analysis can be computationally intensive and build systems may take longer than expected.**

openpiv/data/test1/test_data.vec

@@ -1,71 +1,71 @@
-# x	y	u	v	mask
-  0.4041	  3.3983	  0.1059	 -2.7964	  0.0000
-  0.9014	  3.3983	  0.1055	 -2.8239	  0.0000
-  1.3987	  3.3983	  0.0993	 -2.8579	  0.0000
-  1.8960	  3.3983	  0.0847	 -2.9079	  0.0000
-  2.3933	  3.3983	  0.0636	 -2.9569	  0.0000
-  2.8906	  3.3983	  0.0027	 -2.9658	  0.0000
-  3.3879	  3.3983	 -0.0587	 -2.9562	  0.0000
-  3.8852	  3.3983	 -0.1373	 -2.9133	  0.0000
-  4.3825	  3.3983	 -0.1947	 -2.8557	  0.0000
-  4.8798	  3.3983	 -0.3670	 -2.6830	  0.0000
-  0.4041	  2.9010	  0.0665	 -2.8040	  0.0000
-  0.9014	  2.9010	  0.0722	 -2.8245	  0.0000
-  1.3987	  2.9010	  0.4053	 -2.7250	  0.0000
-  1.8960	  2.9010	  0.0578	 -2.8927	  0.0000
-  2.3933	  2.9010	  0.0323	 -2.9326	  0.0000
-  2.8906	  2.9010	 -0.0168	 -2.9186	  0.0000
-  3.3879	  2.9010	 -0.0805	 -2.8935	  0.0000
-  3.8852	  2.9010	 -0.1594	 -2.8354	  0.0000
-  4.3825	  2.9010	 -0.2061	 -2.7844	  0.0000
-  4.8798	  2.9010	 -0.3066	 -2.6590	  0.0000
-  0.4041	  2.4036	 -0.0594	 -2.7840	  0.0000
-  0.9014	  2.4036	  0.0691	 -2.8055	  0.0000
-  1.3987	  2.4036	  0.0673	 -2.8306	  0.0000
-  1.8960	  2.4036	  0.0471	 -2.8555	  0.0000
-  2.3933	  2.4036	 -0.0328	 -3.1216	  0.0000
-  2.8906	  2.4036	 -0.0386	 -2.8746	  0.0000
-  3.3879	  2.4036	 -0.1014	 -2.8450	  0.0000
-  3.8852	  2.4036	 -0.1698	 -2.7944	  0.0000
-  4.3825	  2.4036	 -0.2126	 -2.7545	  0.0000
-  4.8798	  2.4036	 -0.2916	 -2.6564	  0.0000
-  0.4041	  1.9063	  0.0525	 -2.7684	  0.0000
-  0.9014	  1.9063	  0.0386	 -2.7413	  0.0000
-  1.3987	  1.9063	 -0.2324	 -2.9411	  0.0000
-  1.8960	  1.9063	  0.0251	 -2.8002	  0.0000
-  2.3933	  1.9063	  0.1382	 -2.9616	  0.0000
-  2.8906	  1.9063	 -0.0768	 -2.7952	  0.0000
-  3.3879	  1.9063	 -0.1411	 -2.7683	  0.0000
-  3.8852	  1.9063	 -0.1849	 -2.7214	  0.0000
-  4.3825	  1.9063	 -0.2214	 -2.6969	  0.0000
-  4.8798	  1.9063	 -0.2577	 -2.6471	  0.0000
-  0.4041	  1.4090	  0.0971	 -2.7341	  0.0000
-  0.9014	  1.4090	  0.0887	 -2.7155	  0.0000
-  1.3987	  1.4090	  0.0636	 -2.7338	  0.0000
-  1.8960	  1.4090	  0.0181	 -2.7250	  0.0000
-  2.3933	  1.4090	 -0.0418	 -2.7314	  0.0000
-  2.8906	  1.4090	 -0.0996	 -2.7079	  0.0000
-  3.3879	  1.4090	 -0.1617	 -2.7015	  0.0000
-  3.8852	  1.4090	 -0.3670	 -2.6830	  0.0000
-  4.3825	  1.4090	 -0.2229	 -2.6631	  0.0000
-  4.8798	  1.4090	 -0.2474	 -2.6431	  0.0000
-  0.4041	  0.9117	  0.1195	 -2.7126	  0.0000
-  0.9014	  0.9117	  0.1056	 -2.6844	  0.0000
-  1.3987	  0.9117	  0.0769	 -2.6932	  0.0000
-  1.8960	  0.9117	  0.1454	 -2.5757	  0.0000
-  2.3933	  0.9117	 -0.1543	 -2.7084	  0.0000
-  2.8906	  0.9117	 -0.0990	 -2.6575	  0.0000
-  3.3879	  0.9117	 -0.3521	 -2.5478	  0.0000
-  3.8852	  0.9117	 -0.1831	 -2.6454	  0.0000
-  4.3825	  0.9117	 -0.2044	 -2.6432	  0.0000
-  4.8798	  0.9117	 -0.0650	 -2.6367	  0.0000
-  0.4041	  0.4144	  0.1767	 -2.6746	  0.0000
-  0.9014	  0.4144	  0.5106	 -2.6316	  0.0000
-  1.3987	  0.4144	  0.1007	 -2.6398	  0.0000
-  1.8960	  0.4144	  0.0127	 -2.2562	  0.0000
-  2.3933	  0.4144	 -0.0425	 -2.6163	  0.0000
-  2.8906	  0.4144	 -0.1095	 -2.6114	  0.0000
-  3.3879	  0.4144	 -0.0219	 -2.5749	  0.0000
-  3.8852	  0.4144	 -0.1777	 -2.6289	  0.0000
-  4.3825	  0.4144	 -0.1981	 -2.6318	  0.0000
-  4.8798	  0.4144	 -0.2080	 -2.6325	  0.0000
+# x	y	u	v	flags	mask
+4.0406e-01	3.3983e+00	-5.2592e-03	-5.9910e-02	0.0000e+00	0.0000e+00
+9.0137e-01	3.3983e+00	-9.6075e-04	-6.4036e-02	0.0000e+00	0.0000e+00
+1.3987e+00	3.3983e+00	-3.4784e-06	-5.9356e-02	1.0000e+00	0.0000e+00
+1.8960e+00	3.3983e+00	4.9192e-03	-6.1691e-02	0.0000e+00	0.0000e+00
+2.3933e+00	3.3983e+00	-9.2873e-04	-5.6505e-02	1.0000e+00	0.0000e+00
+2.8906e+00	3.3983e+00	-5.9565e-03	-5.0575e-02	0.0000e+00	0.0000e+00
+3.3879e+00	3.3983e+00	2.1094e-04	-5.7925e-02	0.0000e+00	0.0000e+00
+3.8852e+00	3.3983e+00	-2.7240e-03	-6.0472e-02	0.0000e+00	0.0000e+00
+4.3825e+00	3.3983e+00	-3.7283e-03	-5.8267e-02	1.0000e+00	0.0000e+00
+4.8798e+00	3.3983e+00	2.4173e-03	-6.4150e-02	0.0000e+00	0.0000e+00
+4.0406e-01	2.9010e+00	-1.8216e-03	-5.4789e-02	0.0000e+00	0.0000e+00
+9.0137e-01	2.9010e+00	-1.8865e-04	-5.9088e-02	1.0000e+00	0.0000e+00
+1.3987e+00	2.9010e+00	5.2738e-03	-5.5928e-02	0.0000e+00	0.0000e+00
+1.8960e+00	2.9010e+00	8.0944e-03	-5.4726e-02	0.0000e+00	0.0000e+00
+2.3933e+00	2.9010e+00	-2.6124e-03	-5.5983e-02	0.0000e+00	0.0000e+00
+2.8906e+00	2.9010e+00	-4.3661e-03	-5.1347e-02	0.0000e+00	0.0000e+00
+3.3879e+00	2.9010e+00	-3.3565e-03	-5.6682e-02	0.0000e+00	0.0000e+00
+3.8852e+00	2.9010e+00	-3.5475e-03	-6.1713e-02	0.0000e+00	0.0000e+00
+4.3825e+00	2.9010e+00	-3.8556e-03	-5.6242e-02	1.0000e+00	0.0000e+00
+4.8798e+00	2.9010e+00	-6.4612e-03	-6.4347e-02	0.0000e+00	0.0000e+00
+4.0406e-01	2.4036e+00	8.3705e-04	-5.9559e-02	0.0000e+00	0.0000e+00
+9.0137e-01	2.4036e+00	1.4459e-03	-6.0987e-02	0.0000e+00	0.0000e+00
+1.3987e+00	2.4036e+00	-3.0819e-04	-5.8402e-02	1.0000e+00	0.0000e+00
+1.8960e+00	2.4036e+00	-7.8548e-03	-6.5643e-02	0.0000e+00	0.0000e+00
+2.3933e+00	2.4036e+00	-6.7928e-04	-6.3742e-02	0.0000e+00	0.0000e+00
+2.8906e+00	2.4036e+00	1.2726e-04	-4.9550e-02	0.0000e+00	0.0000e+00
+3.3879e+00	2.4036e+00	-6.4997e-03	-4.9535e-02	0.0000e+00	0.0000e+00
+3.8852e+00	2.4036e+00	-5.7793e-03	-5.4359e-02	0.0000e+00	0.0000e+00
+4.3825e+00	2.4036e+00	-7.7358e-03	-5.8984e-02	0.0000e+00	0.0000e+00
+4.8798e+00	2.4036e+00	-3.6829e-03	-5.6436e-02	1.0000e+00	0.0000e+00
+4.0406e-01	1.9063e+00	-8.4074e-03	-5.9327e-02	0.0000e+00	0.0000e+00
+9.0137e-01	1.9063e+00	2.5401e-03	-5.4095e-02	0.0000e+00	0.0000e+00
+1.3987e+00	1.9063e+00	-3.3883e-03	-5.7585e-02	0.0000e+00	0.0000e+00
+1.8960e+00	1.9063e+00	1.9393e-03	-5.9907e-02	0.0000e+00	0.0000e+00
+2.3933e+00	1.9063e+00	1.4774e-03	-6.0280e-02	0.0000e+00	0.0000e+00
+2.8906e+00	1.9063e+00	-1.7161e-03	-5.2136e-02	0.0000e+00	0.0000e+00
+3.3879e+00	1.9063e+00	-9.2400e-03	-4.8946e-02	0.0000e+00	0.0000e+00
+3.8852e+00	1.9063e+00	-7.1067e-03	-4.8031e-02	0.0000e+00	0.0000e+00
+4.3825e+00	1.9063e+00	-1.2505e-03	-5.2882e-02	0.0000e+00	0.0000e+00
+4.8798e+00	1.9063e+00	6.4614e-04	-5.0812e-02	0.0000e+00	0.0000e+00
+4.0406e-01	1.4090e+00	2.2486e-03	-5.0550e-02	0.0000e+00	0.0000e+00
+9.0137e-01	1.4090e+00	-6.7877e-03	-5.4202e-02	0.0000e+00	0.0000e+00
+1.3987e+00	1.4090e+00	-2.5288e-03	-6.3126e-02	0.0000e+00	0.0000e+00
+1.8960e+00	1.4090e+00	-5.9178e-04	-5.8457e-02	0.0000e+00	0.0000e+00
+2.3933e+00	1.4090e+00	5.8459e-03	-5.2184e-02	0.0000e+00	0.0000e+00
+2.8906e+00	1.4090e+00	5.4790e-03	-4.3826e-02	0.0000e+00	0.0000e+00
+3.3879e+00	1.4090e+00	-7.8645e-04	-5.1268e-02	0.0000e+00	0.0000e+00
+3.8852e+00	1.4090e+00	-5.9201e-03	-5.2166e-02	0.0000e+00	0.0000e+00
+4.3825e+00	1.4090e+00	-4.3095e-03	-5.2602e-02	0.0000e+00	0.0000e+00
+4.8798e+00	1.4090e+00	-2.2094e-03	-5.4975e-02	0.0000e+00	0.0000e+00
+4.0406e-01	9.1173e-01	9.7924e-03	-5.5734e-02	0.0000e+00	0.0000e+00
+9.0137e-01	9.1173e-01	7.5636e-03	-5.2847e-02	0.0000e+00	0.0000e+00
+1.3987e+00	9.1173e-01	9.0445e-03	-4.9824e-02	0.0000e+00	0.0000e+00
+1.8960e+00	9.1173e-01	1.4482e-03	-5.3496e-02	0.0000e+00	0.0000e+00
+2.3933e+00	9.1173e-01	-3.3418e-03	-5.3215e-02	0.0000e+00	0.0000e+00
+2.8906e+00	9.1173e-01	-5.2835e-03	-4.9696e-02	0.0000e+00	0.0000e+00
+3.3879e+00	9.1173e-01	-5.0878e-03	-5.0559e-02	0.0000e+00	0.0000e+00
+3.8852e+00	9.1173e-01	-5.8373e-03	-5.1331e-02	0.0000e+00	0.0000e+00
+4.3825e+00	9.1173e-01	-9.5435e-04	-5.1071e-02	0.0000e+00	0.0000e+00
+4.8798e+00	9.1173e-01	-1.7836e-03	-5.0735e-02	0.0000e+00	0.0000e+00
+4.0406e-01	4.1442e-01	7.7151e-03	-5.9321e-02	0.0000e+00	0.0000e+00
+9.0137e-01	4.1442e-01	1.0424e-02	-5.2889e-02	0.0000e+00	0.0000e+00
+1.3987e+00	4.1442e-01	-1.2132e-03	-5.1367e-02	0.0000e+00	0.0000e+00
+1.8960e+00	4.1442e-01	1.8418e-03	-5.2428e-02	1.0000e+00	0.0000e+00
+2.3933e+00	4.1442e-01	3.0095e-03	-4.7837e-02	0.0000e+00	0.0000e+00
+2.8906e+00	4.1442e-01	2.7171e-03	-5.1027e-02	0.0000e+00	0.0000e+00
+3.3879e+00	4.1442e-01	-5.2003e-03	-5.0522e-02	0.0000e+00	0.0000e+00
+3.8852e+00	4.1442e-01	-4.6899e-03	-5.3185e-02	0.0000e+00	0.0000e+00
+4.3825e+00	4.1442e-01	-2.9401e-03	-5.4006e-02	0.0000e+00	0.0000e+00
+4.8798e+00	4.1442e-01	2.9101e-03	-5.1380e-02	0.0000e+00	0.0000e+00