Integrate synimage module into openpiv.tools for easy synthetic image generation

[Copilot]

Overview

This PR integrates the existing synimage module into the openpiv.tools package, making it easily accessible for users who need to generate synthetic PIV images for testing and validation purposes.

Changes

Module Integration

• Moved the synimage directory into openpiv/synimage/ to make it part of the main package structure
• Created openpiv/synimage/__init__.py to expose the module's functionality
• Added import statement in openpiv/tools.py to make synimage accessible via from openpiv.tools import synimage

New Convenience Function

Added a synimagegen() wrapper function that provides an easy-to-use interface for generating synthetic PIV images with sensible defaults:

from openpiv.tools import synimage

# Generate a pair of 128x128 synthetic PIV images
image_a, image_b = synimage.synimagegen(128)

# Or customize parameters
image_a, image_b = synimage.synimagegen(
    image_size=256,
    dt=0.2,
    den=0.01,
    bit_depth=16
)

Testing

• Added comprehensive test suite in openpiv/test/test_synimage.py with 7 test cases covering:
  • Module import functionality
  • Basic synthetic image generation
  • Different image sizes
  • Custom parameters
  • Direct access to underlying functions
  • Integration with PIV analysis workflow

Benefits

1. Easier Testing: Users can quickly generate synthetic PIV images for testing algorithms without external image files
2. Validation: Provides known ground truth flow fields for validating PIV analysis accuracy
3. Consistent API: Follows OpenPIV's module structure and naming conventions
4. Backward Compatible: All existing functionality remains unchanged

Testing Results

• All 205 existing tests continue to pass
• 7 new tests added specifically for synimage integration
• No security vulnerabilities detected (CodeQL)
• Successfully tested end-to-end workflow with PIV analysis

Usage Example

from openpiv.tools import synimage
from openpiv import piv

# Generate synthetic images
image_a, image_b = synimage.synimagegen(128)

# Run PIV analysis on them
x, y, u, v, s2n = piv.simple_piv(image_a, image_b)

This makes the workflow more streamlined for users who want to test or validate their PIV configurations before processing real experimental data.

Original prompt

open a new branch synimage and help to incorporate synimage into openpiv.tools so we could do >> from openpiv.tools import synimage and then synimage.synimagegen(128) to create a synthetic image with some default parameters

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.