Skip to content

Commit a252fb7

Browse files
alexlibalexlib
authored
Merge pull request #347 from OpenPIV/copilot/fix-346
Add comprehensive GitHub Copilot instructions for OpenPIV development workflow
2 parents ea5a47e + 4885e49 commit a252fb7

File tree

3 files changed

+191
-71
lines changed

3 files changed

+191
-71
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# OpenPIV Python
2+
3+
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.
4+
5+
**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.**
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Install Dependencies
10+
- **Primary method (recommended)**: Use Poetry for development:
11+
- Install Poetry: `pip install poetry`
12+
- Install dependencies: `poetry install` -- takes ~10 seconds. NEVER CANCEL.
13+
- All development commands should use `poetry run <command>`
14+
15+
### Alternative Installation Methods
16+
- **From PyPI**: `pip install openpiv` -- takes ~33 seconds. NEVER CANCEL.
17+
- **From conda-forge**: `conda install -c conda-forge openpiv` -- takes ~46 seconds. NEVER CANCEL.
18+
- **Build from source**: `python setup.py build_ext --inplace` -- takes <1 second (no Cython extensions in current setup)
19+
20+
### Build and Test the Repository
21+
- **Run tests**: `poetry run pytest openpiv -v` -- takes ~12 seconds, 198 tests pass, 12 skipped. NEVER CANCEL. Set timeout to 30+ minutes for safety.
22+
- **Test import**: `poetry run python -c "import openpiv; print('OpenPIV imported successfully')"`
23+
- **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')"`
24+
25+
### Run Example Workflows
26+
- **Tutorial 1**: `poetry run python openpiv/tutorials/tutorial1.py` -- demonstrates complete PIV analysis workflow
27+
- **Test data location**: `openpiv/data/test1/` contains sample image pairs (`exp1_001_a.bmp`, `exp1_001_b.bmp`)
28+
29+
## Validation
30+
31+
### ALWAYS run these validation steps after making changes:
32+
1. **Import test**: Verify basic import works: `poetry run python -c "import openpiv"`
33+
2. **Core functionality test**: Run simple PIV analysis to ensure algorithms work
34+
3. **Full test suite**: `poetry run pytest openpiv -v` -- NEVER CANCEL, takes ~12 seconds but allow 30+ minutes timeout
35+
4. **Tutorial execution**: Run `poetry run python openpiv/tutorials/tutorial1.py` to test complete workflow
36+
37+
### Critical User Scenarios to Test
38+
After making changes, ALWAYS test these scenarios:
39+
- **Basic PIV Analysis**: Load two images, run PIV analysis, get velocity fields
40+
- **Data Loading**: Import test images from `openpiv/data/test1/`
41+
- **Validation and Filtering**: Apply signal-to-noise filtering and outlier detection
42+
- **File I/O**: Save and load PIV results in vector field format
43+
44+
### CI/CD Validation
45+
- The repository has GitHub Actions workflows in `.github/workflows/`:
46+
- `testing.yml`: Runs tests on Python 3.10, 3.11, 3.12 with Poetry
47+
- `build.yml`: Builds and publishes to PyPI on releases
48+
- No linting tools are configured (no black, flake8, etc.)
49+
50+
## Common Tasks
51+
52+
### Repository Structure
53+
```
54+
openpiv/
55+
├── __init__.py # Main package initialization
56+
├── piv.py # High-level PIV analysis functions
57+
├── pyprocess.py # Core PIV processing algorithms
58+
├── pyprocess3D.py # 3D PIV algorithms
59+
├── tools.py # Utility functions for I/O and visualization
60+
├── validation.py # Signal validation and filtering
61+
├── filters.py # Outlier detection and replacement
62+
├── windef.py # Window deformation PIV
63+
├── scaling.py # Coordinate scaling and transformation
64+
├── preprocess.py # Image preprocessing
65+
├── smoothn.py # Smoothing algorithms
66+
├── data/ # Sample test data
67+
├── test/ # Comprehensive test suite (210 tests)
68+
├── tutorials/ # Example scripts
69+
└── docs/ # Documentation source
70+
```
71+
72+
### Key APIs and Usage Patterns
73+
- **Simple PIV**: `piv.simple_piv(frame_a, frame_b)` returns `(x, y, u, v, s2n)`
74+
- **Extended search area**: `pyprocess.extended_search_area_piv()` for higher accuracy
75+
- **Window deformation**: `windef` module for advanced PIV with iterative refinement
76+
- **File I/O**: `tools.imread()`, `tools.save()`, `tools.display_vector_field()`
77+
- **Validation**: `validation.sig2noise_val()`, `validation.global_val()`
78+
- **Filtering**: `filters.replace_outliers()` for cleaning velocity fields
79+
80+
### Project Management
81+
- **Dependencies**: Managed via Poetry (`pyproject.toml`) and fallback setuptools (`setup.py`)
82+
- **Package name**: "OpenPIV" (capital letters)
83+
- **Version**: 0.25.3 (defined in both `pyproject.toml` and `setup.py`)
84+
- **Python support**: 3.10, 3.11, 3.12
85+
- **Key dependencies**: numpy, scipy, scikit-image, matplotlib, imageio
86+
87+
### Development Notes
88+
- Uses `importlib_resources` for accessing package data files
89+
- Test configurations in `openpiv/test/conftest.py` disable plotting for CI
90+
- Sample data includes real PIV image pairs for testing workflows
91+
- Documentation built with Sphinx (source in `openpiv/docs/`)
92+
- External examples repository: [OpenPIV-Python-Examples](https://github.com/OpenPIV/openpiv-python-examples)
93+
94+
### Common Command Reference
95+
```bash
96+
# Development setup
97+
poetry install # ~10 seconds
98+
poetry run pytest openpiv -v # ~12 seconds, 198 tests pass
99+
100+
# Testing functionality
101+
poetry run python openpiv/tutorials/tutorial1.py # Complete PIV workflow
102+
poetry run python -c "import openpiv.piv as piv; ..." # API test
103+
104+
# Alternative installs
105+
pip install openpiv # ~33 seconds
106+
conda install -c conda-forge openpiv # ~46 seconds
107+
108+
# Build from source (minimal - no Cython compilation needed)
109+
python setup.py build_ext --inplace # <1 second
110+
```
111+
112+
### Timing Expectations and Timeouts
113+
- **Poetry install**: ~10 seconds (set 5+ minute timeout)
114+
- **Test suite**: ~12 seconds (set 30+ minute timeout for safety)
115+
- **Tutorial execution**: ~1-2 seconds
116+
- **Pip install**: ~33 seconds (set 10+ minute timeout)
117+
- **Conda install**: ~46 seconds (set 15+ minute timeout)
118+
- **Build from source**: <1 second (no Cython compilation currently)
119+
120+
**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‎

Lines changed: 71 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,71 @@
1-
# x y u v mask
2-
0.4041 3.3983 0.1059 -2.7964 0.0000
3-
0.9014 3.3983 0.1055 -2.8239 0.0000
4-
1.3987 3.3983 0.0993 -2.8579 0.0000
5-
1.8960 3.3983 0.0847 -2.9079 0.0000
6-
2.3933 3.3983 0.0636 -2.9569 0.0000
7-
2.8906 3.3983 0.0027 -2.9658 0.0000
8-
3.3879 3.3983 -0.0587 -2.9562 0.0000
9-
3.8852 3.3983 -0.1373 -2.9133 0.0000
10-
4.3825 3.3983 -0.1947 -2.8557 0.0000
11-
4.8798 3.3983 -0.3670 -2.6830 0.0000
12-
0.4041 2.9010 0.0665 -2.8040 0.0000
13-
0.9014 2.9010 0.0722 -2.8245 0.0000
14-
1.3987 2.9010 0.4053 -2.7250 0.0000
15-
1.8960 2.9010 0.0578 -2.8927 0.0000
16-
2.3933 2.9010 0.0323 -2.9326 0.0000
17-
2.8906 2.9010 -0.0168 -2.9186 0.0000
18-
3.3879 2.9010 -0.0805 -2.8935 0.0000
19-
3.8852 2.9010 -0.1594 -2.8354 0.0000
20-
4.3825 2.9010 -0.2061 -2.7844 0.0000
21-
4.8798 2.9010 -0.3066 -2.6590 0.0000
22-
0.4041 2.4036 -0.0594 -2.7840 0.0000
23-
0.9014 2.4036 0.0691 -2.8055 0.0000
24-
1.3987 2.4036 0.0673 -2.8306 0.0000
25-
1.8960 2.4036 0.0471 -2.8555 0.0000
26-
2.3933 2.4036 -0.0328 -3.1216 0.0000
27-
2.8906 2.4036 -0.0386 -2.8746 0.0000
28-
3.3879 2.4036 -0.1014 -2.8450 0.0000
29-
3.8852 2.4036 -0.1698 -2.7944 0.0000
30-
4.3825 2.4036 -0.2126 -2.7545 0.0000
31-
4.8798 2.4036 -0.2916 -2.6564 0.0000
32-
0.4041 1.9063 0.0525 -2.7684 0.0000
33-
0.9014 1.9063 0.0386 -2.7413 0.0000
34-
1.3987 1.9063 -0.2324 -2.9411 0.0000
35-
1.8960 1.9063 0.0251 -2.8002 0.0000
36-
2.3933 1.9063 0.1382 -2.9616 0.0000
37-
2.8906 1.9063 -0.0768 -2.7952 0.0000
38-
3.3879 1.9063 -0.1411 -2.7683 0.0000
39-
3.8852 1.9063 -0.1849 -2.7214 0.0000
40-
4.3825 1.9063 -0.2214 -2.6969 0.0000
41-
4.8798 1.9063 -0.2577 -2.6471 0.0000
42-
0.4041 1.4090 0.0971 -2.7341 0.0000
43-
0.9014 1.4090 0.0887 -2.7155 0.0000
44-
1.3987 1.4090 0.0636 -2.7338 0.0000
45-
1.8960 1.4090 0.0181 -2.7250 0.0000
46-
2.3933 1.4090 -0.0418 -2.7314 0.0000
47-
2.8906 1.4090 -0.0996 -2.7079 0.0000
48-
3.3879 1.4090 -0.1617 -2.7015 0.0000
49-
3.8852 1.4090 -0.3670 -2.6830 0.0000
50-
4.3825 1.4090 -0.2229 -2.6631 0.0000
51-
4.8798 1.4090 -0.2474 -2.6431 0.0000
52-
0.4041 0.9117 0.1195 -2.7126 0.0000
53-
0.9014 0.9117 0.1056 -2.6844 0.0000
54-
1.3987 0.9117 0.0769 -2.6932 0.0000
55-
1.8960 0.9117 0.1454 -2.5757 0.0000
56-
2.3933 0.9117 -0.1543 -2.7084 0.0000
57-
2.8906 0.9117 -0.0990 -2.6575 0.0000
58-
3.3879 0.9117 -0.3521 -2.5478 0.0000
59-
3.8852 0.9117 -0.1831 -2.6454 0.0000
60-
4.3825 0.9117 -0.2044 -2.6432 0.0000
61-
4.8798 0.9117 -0.0650 -2.6367 0.0000
62-
0.4041 0.4144 0.1767 -2.6746 0.0000
63-
0.9014 0.4144 0.5106 -2.6316 0.0000
64-
1.3987 0.4144 0.1007 -2.6398 0.0000
65-
1.8960 0.4144 0.0127 -2.2562 0.0000
66-
2.3933 0.4144 -0.0425 -2.6163 0.0000
67-
2.8906 0.4144 -0.1095 -2.6114 0.0000
68-
3.3879 0.4144 -0.0219 -2.5749 0.0000
69-
3.8852 0.4144 -0.1777 -2.6289 0.0000
70-
4.3825 0.4144 -0.1981 -2.6318 0.0000
71-
4.8798 0.4144 -0.2080 -2.6325 0.0000
1+
# x y u v flags mask
2+
4.0406e-01 3.3983e+00 -5.2592e-03 -5.9910e-02 0.0000e+00 0.0000e+00
3+
9.0137e-01 3.3983e+00 -9.6075e-04 -6.4036e-02 0.0000e+00 0.0000e+00
4+
1.3987e+00 3.3983e+00 -3.4784e-06 -5.9356e-02 1.0000e+00 0.0000e+00
5+
1.8960e+00 3.3983e+00 4.9192e-03 -6.1691e-02 0.0000e+00 0.0000e+00
6+
2.3933e+00 3.3983e+00 -9.2873e-04 -5.6505e-02 1.0000e+00 0.0000e+00
7+
2.8906e+00 3.3983e+00 -5.9565e-03 -5.0575e-02 0.0000e+00 0.0000e+00
8+
3.3879e+00 3.3983e+00 2.1094e-04 -5.7925e-02 0.0000e+00 0.0000e+00
9+
3.8852e+00 3.3983e+00 -2.7240e-03 -6.0472e-02 0.0000e+00 0.0000e+00
10+
4.3825e+00 3.3983e+00 -3.7283e-03 -5.8267e-02 1.0000e+00 0.0000e+00
11+
4.8798e+00 3.3983e+00 2.4173e-03 -6.4150e-02 0.0000e+00 0.0000e+00
12+
4.0406e-01 2.9010e+00 -1.8216e-03 -5.4789e-02 0.0000e+00 0.0000e+00
13+
9.0137e-01 2.9010e+00 -1.8865e-04 -5.9088e-02 1.0000e+00 0.0000e+00
14+
1.3987e+00 2.9010e+00 5.2738e-03 -5.5928e-02 0.0000e+00 0.0000e+00
15+
1.8960e+00 2.9010e+00 8.0944e-03 -5.4726e-02 0.0000e+00 0.0000e+00
16+
2.3933e+00 2.9010e+00 -2.6124e-03 -5.5983e-02 0.0000e+00 0.0000e+00
17+
2.8906e+00 2.9010e+00 -4.3661e-03 -5.1347e-02 0.0000e+00 0.0000e+00
18+
3.3879e+00 2.9010e+00 -3.3565e-03 -5.6682e-02 0.0000e+00 0.0000e+00
19+
3.8852e+00 2.9010e+00 -3.5475e-03 -6.1713e-02 0.0000e+00 0.0000e+00
20+
4.3825e+00 2.9010e+00 -3.8556e-03 -5.6242e-02 1.0000e+00 0.0000e+00
21+
4.8798e+00 2.9010e+00 -6.4612e-03 -6.4347e-02 0.0000e+00 0.0000e+00
22+
4.0406e-01 2.4036e+00 8.3705e-04 -5.9559e-02 0.0000e+00 0.0000e+00
23+
9.0137e-01 2.4036e+00 1.4459e-03 -6.0987e-02 0.0000e+00 0.0000e+00
24+
1.3987e+00 2.4036e+00 -3.0819e-04 -5.8402e-02 1.0000e+00 0.0000e+00
25+
1.8960e+00 2.4036e+00 -7.8548e-03 -6.5643e-02 0.0000e+00 0.0000e+00
26+
2.3933e+00 2.4036e+00 -6.7928e-04 -6.3742e-02 0.0000e+00 0.0000e+00
27+
2.8906e+00 2.4036e+00 1.2726e-04 -4.9550e-02 0.0000e+00 0.0000e+00
28+
3.3879e+00 2.4036e+00 -6.4997e-03 -4.9535e-02 0.0000e+00 0.0000e+00
29+
3.8852e+00 2.4036e+00 -5.7793e-03 -5.4359e-02 0.0000e+00 0.0000e+00
30+
4.3825e+00 2.4036e+00 -7.7358e-03 -5.8984e-02 0.0000e+00 0.0000e+00
31+
4.8798e+00 2.4036e+00 -3.6829e-03 -5.6436e-02 1.0000e+00 0.0000e+00
32+
4.0406e-01 1.9063e+00 -8.4074e-03 -5.9327e-02 0.0000e+00 0.0000e+00
33+
9.0137e-01 1.9063e+00 2.5401e-03 -5.4095e-02 0.0000e+00 0.0000e+00
34+
1.3987e+00 1.9063e+00 -3.3883e-03 -5.7585e-02 0.0000e+00 0.0000e+00
35+
1.8960e+00 1.9063e+00 1.9393e-03 -5.9907e-02 0.0000e+00 0.0000e+00
36+
2.3933e+00 1.9063e+00 1.4774e-03 -6.0280e-02 0.0000e+00 0.0000e+00
37+
2.8906e+00 1.9063e+00 -1.7161e-03 -5.2136e-02 0.0000e+00 0.0000e+00
38+
3.3879e+00 1.9063e+00 -9.2400e-03 -4.8946e-02 0.0000e+00 0.0000e+00
39+
3.8852e+00 1.9063e+00 -7.1067e-03 -4.8031e-02 0.0000e+00 0.0000e+00
40+
4.3825e+00 1.9063e+00 -1.2505e-03 -5.2882e-02 0.0000e+00 0.0000e+00
41+
4.8798e+00 1.9063e+00 6.4614e-04 -5.0812e-02 0.0000e+00 0.0000e+00
42+
4.0406e-01 1.4090e+00 2.2486e-03 -5.0550e-02 0.0000e+00 0.0000e+00
43+
9.0137e-01 1.4090e+00 -6.7877e-03 -5.4202e-02 0.0000e+00 0.0000e+00
44+
1.3987e+00 1.4090e+00 -2.5288e-03 -6.3126e-02 0.0000e+00 0.0000e+00
45+
1.8960e+00 1.4090e+00 -5.9178e-04 -5.8457e-02 0.0000e+00 0.0000e+00
46+
2.3933e+00 1.4090e+00 5.8459e-03 -5.2184e-02 0.0000e+00 0.0000e+00
47+
2.8906e+00 1.4090e+00 5.4790e-03 -4.3826e-02 0.0000e+00 0.0000e+00
48+
3.3879e+00 1.4090e+00 -7.8645e-04 -5.1268e-02 0.0000e+00 0.0000e+00
49+
3.8852e+00 1.4090e+00 -5.9201e-03 -5.2166e-02 0.0000e+00 0.0000e+00
50+
4.3825e+00 1.4090e+00 -4.3095e-03 -5.2602e-02 0.0000e+00 0.0000e+00
51+
4.8798e+00 1.4090e+00 -2.2094e-03 -5.4975e-02 0.0000e+00 0.0000e+00
52+
4.0406e-01 9.1173e-01 9.7924e-03 -5.5734e-02 0.0000e+00 0.0000e+00
53+
9.0137e-01 9.1173e-01 7.5636e-03 -5.2847e-02 0.0000e+00 0.0000e+00
54+
1.3987e+00 9.1173e-01 9.0445e-03 -4.9824e-02 0.0000e+00 0.0000e+00
55+
1.8960e+00 9.1173e-01 1.4482e-03 -5.3496e-02 0.0000e+00 0.0000e+00
56+
2.3933e+00 9.1173e-01 -3.3418e-03 -5.3215e-02 0.0000e+00 0.0000e+00
57+
2.8906e+00 9.1173e-01 -5.2835e-03 -4.9696e-02 0.0000e+00 0.0000e+00
58+
3.3879e+00 9.1173e-01 -5.0878e-03 -5.0559e-02 0.0000e+00 0.0000e+00
59+
3.8852e+00 9.1173e-01 -5.8373e-03 -5.1331e-02 0.0000e+00 0.0000e+00
60+
4.3825e+00 9.1173e-01 -9.5435e-04 -5.1071e-02 0.0000e+00 0.0000e+00
61+
4.8798e+00 9.1173e-01 -1.7836e-03 -5.0735e-02 0.0000e+00 0.0000e+00
62+
4.0406e-01 4.1442e-01 7.7151e-03 -5.9321e-02 0.0000e+00 0.0000e+00
63+
9.0137e-01 4.1442e-01 1.0424e-02 -5.2889e-02 0.0000e+00 0.0000e+00
64+
1.3987e+00 4.1442e-01 -1.2132e-03 -5.1367e-02 0.0000e+00 0.0000e+00
65+
1.8960e+00 4.1442e-01 1.8418e-03 -5.2428e-02 1.0000e+00 0.0000e+00
66+
2.3933e+00 4.1442e-01 3.0095e-03 -4.7837e-02 0.0000e+00 0.0000e+00
67+
2.8906e+00 4.1442e-01 2.7171e-03 -5.1027e-02 0.0000e+00 0.0000e+00
68+
3.3879e+00 4.1442e-01 -5.2003e-03 -5.0522e-02 0.0000e+00 0.0000e+00
69+
3.8852e+00 4.1442e-01 -4.6899e-03 -5.3185e-02 0.0000e+00 0.0000e+00
70+
4.3825e+00 4.1442e-01 -2.9401e-03 -5.4006e-02 0.0000e+00 0.0000e+00
71+
4.8798e+00 4.1442e-01 2.9101e-03 -5.1380e-02 0.0000e+00 0.0000e+00

‎openpiv/test/OpenPIV_results_16_test1/field_A0000.png‎

-1 Bytes
Loading

0 commit comments

Comments
 (0)