Transform 2D points using homography and lens distortion correction

Use This When

• Mapping camera pixel coordinates to ground plane for spatial measurements
• Correcting perspective distortion from angled camera views
• Transforming detection coordinates across multi-camera overlapping fields of view
• Converting image-space tracking to real-world floor plan coordinates

What It Does

• Applies lens undistortion using radial distortion coefficients (k1, k2)
• Transforms 2D points via 3x3 homography matrix to target plane
• Preserves vector orientation through transformation for flow consistency
• Returns projected points with corrected positions and orientations

Works Best With

• Tracking results → this component → zone containment in world coordinates
• calculate-object-movement → this component → real-world velocity estimation
• Integration with check-object-distance for metric distance calculations
• Multi-camera fusion where cameras share overlapping ground plane view

Caveats

• Homography matrix and distortion coefficients require careful camera calibration
• Single transformation assumes planar scene; fails on 3D or multi-level environments
• Distortion model limited to radial k1/k2; tangential distortion not supported
• Near-degenerate homography (e.g., camera parallel to plane) causes numerical instability