[ErichZimmer]

Preface

This quite large pull request entails the addition of a geometric camera calibration module that can be used for de-warping planar PIV images, stereo-PIV experiments, and tomo-PIV experiments. With over 25 new functions and three of the most common camera models, nearly any PIV experiment can be calibrated before further processing and reconstructions. This pull request contains the following new additions:

• calibration (namespace module)
  • DLT camera model
    • forward projection
    • backward projection
    • analytical two-camera 3D point triangulation
    • least squared multi-camera 3D point triangulation
  • Pinhole camera model (with brown and polynomial distortion models)
    • forward projection
    • backward projection
    • analytical two-camera 3D point triangulation
    • least squared multi-camera 3D point triangulation
  • Soloff polynomial camera model
    • forward projection
    • backward projection
    • analytical two-camera 3D point triangulation
    • least squared multi-camera 3D point triangulation with polynomial refinement
  • marker detection
    • correlated template detection
    • checkerboard detection
  • marker grid generation and matching
    • create rectangular symmetric and asymmettric grids
    • match image points to world points using marching points algorithm
    • match image points to world points using camera projection estimates
  • epipolar utilities
    • plot epipolar lines
  • reprojection error utilities
    • get rms error of residuals
    • get reprojection error of camera models
    • get line-of-sight (LOS) error of camera models
  • mapping functions for de-warping planar PIV images
    • get de-warping mapping and pixel-to-world scale ratio

Along with all these new function, a large quantity of tests have been added too (more than 50 for the camera models alone). However, this module is still a work-in-progress and will be so for many weeks to months until the final product is considered production worthy.

Note

I added tomographic PIV test data in the openpiv/data/test7 directory. It is around 40 MB for this section of the dataset.

Important

Documentation will have to be rebuilt once pull request is merged and a new version is released.

How to test this

• Clone fork
• Run tests
• Play around with calibration utilities

What issue does this PR address?

Closes #220

Additional Context

This module is primarily for 3D imaging systems such as

• Stereo-PIV
• Tomo-PIV
• 3D PTV (mainly used for volume self calibration)

However, it can also be used for

• De-warping image distortions
• Aligning camera projection with planar light sheet (mainly for off-axis cameras)

Checklist

Additionally, here is a checklist of future tasks to be completed:

• Debug image mapping and de-warping functions (something funny is going on)
• Add changes to documentation generation to add new module
• Fix relative import on test files (should be openpiv.calibration, not .calibration)
• Fix examples on docstrings (they were originally from the draft phase)
• Add an object-orientated wrapper over the procedural-based module
• Minimize user parameters per function (in theory, minimizes user error and confusion)
• Add more testing to calibration utilities
• Optimize correlated template-based marker detection
• Proof-read docstrings (I know there are a lot of mistakes)
• Add de-warping capabilities to windef
• Add an automated grid and image marker detection system
• Add checkerboard detection
• Add asymmetric grid detection capabilities to matching function
• Automate most of the calibration routines
• Add volume self calibration (may be pushed towards the tomo-PIV pull request)
• Test the calibration module on a synthetically generated 3D volume with 2 to 6 cameras (needed for tomo-PIV, also will test all projection functions for the camera models)
• Move pull request out of draft

[ErichZimmer]

Calibration module is nearly complete. I tested Tomo-PIV on a three camera system with checkerboard free-hand calibration with the first image setting origin. The errors from a A4 printed checkerboard pattern approaching 0.3 pixels and ~0.08 mm RMS error. Some more utilities are needed for mainstreaming the calibration process when manual origins are to be specified, stereo-piv may be moved out of the calibration module since it is it's own thing for the most part (and also needs an implementation fix on self-calibration). Refractive interface support is in planning phase, but actual implementation may not be done depending if there is a real need for it. The calibration module may go through a few more revisions before it is pulled from draft.

[ErichZimmer]

Note one issue occurred during the merging of upstream to local which resulted in all files in the repo being marked as modified even though they retain original state. This issue is being investigated to see if it can be removed and if so, what are the side-effects. Contrarily, the side-effects of keeping all these changes are also being investigated since it may cause merge conflicts.