CV Decompose Homography
Recovers the camera motion hidden in a PLANAR homography (cv2.decomposeHomographyMat): given H and the camera matrix K it returns the rotation, translation and plane normal that would produce it. A homography between two views of a plane is mathematically ambiguous, so OpenCV returns up to FOUR candidate solutions - two of them mirror pairs. Feed 'ref_points' (the source-image points the homography was fitted on) to have filterHomographyDecompByVisibleRefpoints drop the ones that would put the plane BEHIND a camera; the 'visible' mask marks the survivors. That normally removes the two mirror solutions and leaves TWO - the remaining two-fold ambiguity is real geometry, not a bug, and needs a third view or a known plane normal to break. Pair with 'CV Index Batch' (widget-convert its index and wire best_index) to pull a candidate out. Failure tolerant: a degenerate or non-finite H gives found=false with empty stacks instead of raising.
- homography
- camera_matrix
- ref_points
- rotations
- translations
- normals
- visible
- count
- best_index
- found
Inputs (3)
| Name | Type | Default | Description |
|---|---|---|---|
| homography | NPARRAY | 3x3 homography mapping the SOURCE view to the DESTINATION view ('CV Find Homography', cv2.getPerspectiveTransform, or a composed matrix). | |
| camera_matrix | NPARRAY | 3x3 intrinsic matrix K of the camera that took BOTH views ('CV Camera Matrix' / 'Calibrate Camera'). | |
| ref_pointsopt | NPARRAY | Optional Nx2 (or Nx1x2) PIXEL points in the SOURCE image that lie on the plane - normally the very correspondences H was fitted on. At least 4 are needed. They are normalized with K and mapped through H internally, then used to reject the candidates that would put the plane behind a camera (filling 'visible' and 'best_index'). |
Outputs (7)
| Name | Type | Description |
|---|---|---|
| rotations | NPARRAY | (N, 3, 3) float64 stack of candidate rotation matrices, N up to 4. Use 'CV Index Batch' to take one. |
| translations | NPARRAY | (N, 3) float64 stack of candidate translations, SCALED BY THE PLANE DISTANCE: each row is t/d, not t. Only its DIRECTION is metric unless you know d - multiply by the real distance to the plane for units. |
| normals | NPARRAY | (N, 3) float64 stack of candidate plane normals, in the SOURCE camera frame (unit length). |
| visible | NPARRAY | (N, 1) uint8 mask, 255 for each candidate that keeps ref_points in front of both cameras. All 255 when no ref_points were given. Expect TWO survivors out of four: the filter removes the mirror pair, not the genuine two-fold planar ambiguity. |
| count | INT | How many candidate solutions were returned (0 when not found, otherwise usually 4). |
| best_index | INT | Index of the FIRST candidate that survives the visibility filter (0 when no ref_points were given, -1 when nothing was found or every candidate was rejected). It is not necessarily the right one - check 'visible' for the other survivor, and pick between them with an outside cue (e.g. the dot product of 'normals' with a known plane normal, then 'CV Pick Value (sorted)'). 'CV Index Batch' clamps a -1 to 0, so branch on 'found' first. |
| found | BOOLEAN | — |