get_rectangle_poseT_get_rectangle_poseGetRectanglePoseGetRectanglePoseget_rectangle_pose (Operator)

Name

get_rectangle_poseT_get_rectangle_poseGetRectanglePoseGetRectanglePoseget_rectangle_pose — Determine the 3D pose of a rectangle from its perspective 2D projection

Signature

get_rectangle_pose(Contour : : CameraParam, Width, Height, WeightingMode, ClippingFactor : Pose, CovPose, Error)

Herror T_get_rectangle_pose(const Hobject Contour, const Htuple CameraParam, const Htuple Width, const Htuple Height, const Htuple WeightingMode, const Htuple ClippingFactor, Htuple* Pose, Htuple* CovPose, Htuple* Error)

void GetRectanglePose(const HObject& Contour, const HTuple& CameraParam, const HTuple& Width, const HTuple& Height, const HTuple& WeightingMode, const HTuple& ClippingFactor, HTuple* Pose, HTuple* CovPose, HTuple* Error)

HPoseArray HXLD::GetRectanglePose(const HCamPar& CameraParam, const HTuple& Width, const HTuple& Height, const HString& WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const

HPose HXLD::GetRectanglePose(const HCamPar& CameraParam, double Width, double Height, const HString& WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const

HPose HXLD::GetRectanglePose(const HCamPar& CameraParam, double Width, double Height, const char* WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const

HPose HXLD::GetRectanglePose(const HCamPar& CameraParam, double Width, double Height, const wchar_t* WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const   (Windows only)

HPoseArray HCamPar::GetRectanglePose(const HXLD& Contour, const HTuple& Width, const HTuple& Height, const HString& WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const

HPose HCamPar::GetRectanglePose(const HXLD& Contour, double Width, double Height, const HString& WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const

HPose HCamPar::GetRectanglePose(const HXLD& Contour, double Width, double Height, const char* WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const

HPose HCamPar::GetRectanglePose(const HXLD& Contour, double Width, double Height, const wchar_t* WeightingMode, double ClippingFactor, HTuple* CovPose, HTuple* Error) const   (Windows only)

static void HOperatorSet.GetRectanglePose(HObject contour, HTuple cameraParam, HTuple width, HTuple height, HTuple weightingMode, HTuple clippingFactor, out HTuple pose, out HTuple covPose, out HTuple error)

HPose[] HXLD.GetRectanglePose(HCamPar cameraParam, HTuple width, HTuple height, string weightingMode, double clippingFactor, out HTuple covPose, out HTuple error)

HPose HXLD.GetRectanglePose(HCamPar cameraParam, double width, double height, string weightingMode, double clippingFactor, out HTuple covPose, out HTuple error)

HPose[] HCamPar.GetRectanglePose(HXLD contour, HTuple width, HTuple height, string weightingMode, double clippingFactor, out HTuple covPose, out HTuple error)

HPose HCamPar.GetRectanglePose(HXLD contour, double width, double height, string weightingMode, double clippingFactor, out HTuple covPose, out HTuple error)

def get_rectangle_pose(contour: HObject, camera_param: Sequence[Union[int, float, str]], width: MaybeSequence[float], height: MaybeSequence[float], weighting_mode: str, clipping_factor: float) -> Tuple[Sequence[Union[int, float]], Sequence[float], Sequence[float]]

Description

A rectangle in space is projected as a general quadrangle into the image. get_rectangle_poseget_rectangle_poseGetRectanglePoseGetRectanglePoseGetRectanglePoseget_rectangle_pose determines the PosePosePosePoseposepose of the rectangle from this projection (ContourContourContourContourcontourcontour).

The algorithm works as follows: First, ContourContourContourContourcontourcontour is segmented into four line segments and their intersections are considered as corners of the contour. The corners together with the internal camera parameters (CameraParamCameraParamCameraParamCameraParamcameraParamcamera_param) and the rectangle size in meters (WidthWidthWidthWidthwidthwidth, HeightHeightHeightHeightheightheight) are used for an initial estimation of the rectangle pose. Then, the final PosePosePosePoseposepose is refined with a non-linear optimization by minimizing the geometrical distance of the contour points from the back projection of the rectangle in the image.

The operator supports only area scan pinhole (projective) cameras. An error is returned if CameraParamCameraParamCameraParamCameraParamcameraParamcamera_param specifies a line scan or a telecentric camera (see also Calibration).

WidthWidthWidthWidthwidthwidth and HeightHeightHeightHeightheightheight specify the size of the rectangle in x and y dimensions, respectively, in its coordinate system. The origin of this coordinate system is in the center of the rectangle. The z axis points away from the camera.

The arguments WeightingModeWeightingModeWeightingModeWeightingModeweightingModeweighting_mode and ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor can be used to damp the impact of outliers on the algorithm. If WeightingModeWeightingModeWeightingModeWeightingModeweightingModeweighting_mode is set to 'tukey'"tukey""tukey""tukey""tukey""tukey" or 'huber'"huber""huber""huber""huber""huber", the contour points are weighted based on the approach of Tukey or Huber respectively. In such a case a robust error statistics is used to estimate the standard deviation of the distances of the contour points from the backprojected rectangle excluding outliers. The parameter ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (a scaling factor for the standard deviation) controls the amount of damping outliers: The smaller the value chosen for ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor the more outliers are detected. See a discussion about the properties of the different weighting modes in fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldFitLineContourXldfit_line_contour_xld. Note that, unlike by fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldFitLineContourXldfit_line_contour_xld, for the rectangle pose estimation the approach of Huber is recommended.

Output

The resulting PosePosePosePoseposepose is of code 0 (see create_posecreate_poseCreatePoseCreatePoseCreatePosecreate_pose) and represents the pose of the center of the rectangle. You can compute the pose of the corners of the rectangle as follows:
set_origin_pose(Pose, Width/2, -Height/2, 0, PoseCorner1)set_origin_pose(Pose, Width/2, -Height/2, 0, PoseCorner1)SetOriginPose(Pose, Width/2, -Height/2, 0, PoseCorner1)SetOriginPose(Pose, Width/2, -Height/2, 0, PoseCorner1)SetOriginPose(Pose, Width/2, -Height/2, 0, PoseCorner1)set_origin_pose(Pose, Width/2, -Height/2, 0, PoseCorner1)
set_origin_pose(Pose, Width/2, Height/2, 0, PoseCorner2)set_origin_pose(Pose, Width/2, Height/2, 0, PoseCorner2)SetOriginPose(Pose, Width/2, Height/2, 0, PoseCorner2)SetOriginPose(Pose, Width/2, Height/2, 0, PoseCorner2)SetOriginPose(Pose, Width/2, Height/2, 0, PoseCorner2)set_origin_pose(Pose, Width/2, Height/2, 0, PoseCorner2)
set_origin_pose(Pose, -Width/2, Height/2, 0, PoseCorner3)set_origin_pose(Pose, -Width/2, Height/2, 0, PoseCorner3)SetOriginPose(Pose, -Width/2, Height/2, 0, PoseCorner3)SetOriginPose(Pose, -Width/2, Height/2, 0, PoseCorner3)SetOriginPose(Pose, -Width/2, Height/2, 0, PoseCorner3)set_origin_pose(Pose, -Width/2, Height/2, 0, PoseCorner3)
set_origin_pose(Pose, -Width/2, -Height/2, 0, PoseCorner4)set_origin_pose(Pose, -Width/2, -Height/2, 0, PoseCorner4)SetOriginPose(Pose, -Width/2, -Height/2, 0, PoseCorner4)SetOriginPose(Pose, -Width/2, -Height/2, 0, PoseCorner4)SetOriginPose(Pose, -Width/2, -Height/2, 0, PoseCorner4)set_origin_pose(Pose, -Width/2, -Height/2, 0, PoseCorner4)
A rectangle is symmetric with respect to its x, y, and z axis and one and the same contour can represent a rectangle in 4 different poses. The angles in PosePosePosePoseposepose are normalized to be in the range [-90; 90] degrees and the rest of the 4 possible poses can be computed by combining flips around the corresponding axis:
* NOTE: the following code works ONLY for pose of code 0
* as it is returned by get_rectangle_pose
*
* flip around z-axis
PoseFlippedZ := Pose
PoseFlippedZ[5] := PoseFlippedZ[5]+180
* flip around y-axis
PoseFlippedY := Pose
PoseFlippedY[4] := PoseFlippedY[4]+180
PoseFlippedY[5] := -PoseFlippedY[5]
* flip around x-axis
PoseFlippedX := Pose
PoseFlippedX[3] := PoseFlippedX[3]+180
PoseFlippedX[4] := -PoseFlippedX[4]
PoseFlippedX[5] := -PoseFlippedX[5]

Note that if the rectangle is a square (WidthWidthWidthWidthwidthwidth == HeightHeightHeightHeightheightheight) the number of alternative poses is 8.

If more than one contour are given in ContourContourContourContourcontourcontour, a corresponding tuple of values for both WidthWidthWidthWidthwidthwidth and HeightHeightHeightHeightheightheight has to be provided as well. Yet, if only one value is provided for each of these arguments, then this value is applied for each processed contour. A pose is estimated for each processed contour and all poses are concatenated in PosePosePosePoseposepose (see the example below).

Accuracy of the pose

The accuracy of the estimated pose depends on the following three factors:

In order to achieve an accurate pose estimation, there are three corresponding criteria that should be considered:

The ratio WidthWidthWidthWidthwidthwidth/HeightHeightHeightHeightheightheight should fulfill For a rectangular object deviating from this criterion, its longer side dominates the determination of its pose. This causes instability in the estimation of the angle around the longer rectangle's axis. In the extreme case when one of the dimensions is 0, the rectangle is in fact a line segment, whose pose cannot be estimated.

Secondly, the lengths of each side of the contour should be at least 20 pixels. An error is returned if a side of the contour is less than 5 pixels long.

Thirdly, the more the contour appears projectively distorted, the more stable the algorithm works. Therefore, the pose of a rectangle tilted with respect to the image plane can be estimated accurately, whereas the pose of an rectangle parallel to the image plane of the camera could be unstable. This is further discussed in the next paragraph. Additionally, there is a rule of thumb that ensures projective distortion: the rectangle should be placed in space such that its size in x and y dimension in the camera coordinate system should not be less than 1/10th of its distance from the camera in z direction.

get_rectangle_poseget_rectangle_poseGetRectanglePoseGetRectanglePoseGetRectanglePoseget_rectangle_pose provides two measures for the accuracy of the estimated PosePosePosePoseposepose. ErrorErrorErrorErrorerrorerror is the average pixel error between the contour points and the modeled rectangle backprojected on the image. If ErrorErrorErrorErrorerrorerror is exceeding 0.5, this is an indication that the algorithm did not converge properly, and the resulting PosePosePosePoseposepose should not be used. CovPoseCovPoseCovPoseCovPosecovPosecov_pose contains 36 entries representing the 6×6 covariance matrix of the first 6 entries of PosePosePosePoseposepose. The above mentioned case of instability of the angle about the longer rectangle's axis be detected by checking that the absolute values of the variances and covariances of the rotations around the x and y axis (CovPoseCovPoseCovPoseCovPosecovPosecov_pose[21],CovPoseCovPoseCovPoseCovPosecovPosecov_pose[28], and CovPoseCovPoseCovPoseCovPosecovPosecov_pose[22] == CovPoseCovPoseCovPoseCovPosecovPosecov_pose[27]) do not exceed 0.05. Further, unusually increased values of any of the covariances and especially of the variances (the 6 values on the diagonal of CovPoseCovPoseCovPoseCovPosecovPosecov_pose with indices 0, 7, 14, 21, 28 and 35, respectively) indicate a poor quality of PosePosePosePoseposepose.

Execution Information

Parameters

ContourContourContourContourcontourcontour (input_object)  xld(-array) objectHXLDHObjectHXLDHobject

Contour(s) to be examined.

CameraParamCameraParamCameraParamCameraParamcameraParamcamera_param (input_control)  campar HCamPar, HTupleSequence[Union[int, float, str]]HTupleHtuple (real / integer / string) (double / int / long / string) (double / Hlong / HString) (double / Hlong / char*)

Internal camera parameters.

WidthWidthWidthWidthwidthwidth (input_control)  number(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Width of the rectangle in meters.

Restriction: Width > 0

HeightHeightHeightHeightheightheight (input_control)  number(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Height of the rectangle in meters.

Restriction: Height > 0

WeightingModeWeightingModeWeightingModeWeightingModeweightingModeweighting_mode (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Weighting mode for the optimization phase.

Default value: 'nonweighted' "nonweighted" "nonweighted" "nonweighted" "nonweighted" "nonweighted"

List of values: 'huber'"huber""huber""huber""huber""huber", 'nonweighted'"nonweighted""nonweighted""nonweighted""nonweighted""nonweighted", 'tukey'"tukey""tukey""tukey""tukey""tukey"

ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (input_control)  number HTuplefloatHTupleHtuple (real) (double) (double) (double)

Clipping factor for the elimination of outliers (typical: 1.0 for 'huber'"huber""huber""huber""huber""huber" and 3.0 for 'tukey'"tukey""tukey""tukey""tukey""tukey").

Default value: 2.0

Suggested values: 1.0, 1.5, 2.0, 2.5, 3.0

Restriction: ClippingFactor > 0

PosePosePosePoseposepose (output_control)  pose(-array) HPose, HTupleSequence[Union[int, float]]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

3D pose of the rectangle.

Number of elements: Pose == 7 * Contour

CovPoseCovPoseCovPoseCovPosecovPosecov_pose (output_control)  number-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Covariances of the pose values.

Number of elements: CovPose == 36 * Contour

ErrorErrorErrorErrorerrorerror (output_control)  number-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Root-mean-square value of the final residual error.

Number of elements: Error == Contour

Example (HDevelop)

* Process an image with several rectangles of the same size appearing
* as light objects.
RectWidth := 0.04
RectHeight := 0.025
gen_cam_par_area_scan_division (0.014, 830, 4.58e-006, 4.65e-006, \
                                509, 488, 800, 800, CameraParam)
read_image (Image, 'barcode/ean13/tea_box_01')
* Find light objects in the image.
mean_image (Image, ImageMean, 201, 201)
dyn_threshold (Image, ImageMean, Region, 5, 'light')
* Fill gaps in the objects.
fill_up (Region, RegionFillUp)
* Extract rectangular contours.
connection (RegionFillUp, ConnectedRegions)
select_shape (ConnectedRegions, SelectedRegions, ['area','rectangularity'], \
              'and', [50000,0.9], [640000,1])
boundary (SelectedRegions, RegionBorder, 'inner')
dilation_circle (RegionBorder, RegionDilation, 3.5)
* NOTE: for a real application, this step might require some additional
*       pre- or postprocessing.
reduce_domain (Image, RegionDilation, ImageReduced)
edges_sub_pix (ImageReduced, Edges, 'canny', 1, 20, 40)
* Get the pose of all contours found.
get_rectangle_pose (Edges, CameraParam, RectWidth, RectHeight, 'huber', 2, \
                    Poses, CovPose, Error)
NumPoses := |Poses|/7
for I := 0 to NumPoses-1 by 1
  Pose := Poses[I*7:I*7+6]
  * Use the Pose here.
  * ...
endfor

Result

get_rectangle_poseget_rectangle_poseGetRectanglePoseGetRectanglePoseGetRectanglePoseget_rectangle_pose returns TRUE if all parameter values are correct and the position of the rectangle has been determined successfully. If the provided contour(s) cannot be segmented as a quadrangle get_rectangle_poseget_rectangle_poseGetRectanglePoseGetRectanglePoseGetRectanglePoseget_rectangle_pose returns H_ERR_FIT_QUADRANGLE. If further necessary, an exception is raised.

Possible Predecessors

edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixEdgesSubPixedges_sub_pix

See also

get_circle_poseget_circle_poseGetCirclePoseGetCirclePoseGetCirclePoseget_circle_pose, set_origin_poseset_origin_poseSetOriginPoseSetOriginPoseSetOriginPoseset_origin_pose, camera_calibrationcamera_calibrationCameraCalibrationCameraCalibrationCameraCalibrationcamera_calibration

References

G.Schweighofer and A.Pinz: “Robust Pose Estimation from a Planar Target”; Transactions on Pattern Analysis and Machine Intelligence (PAMI), 28(12):2024-2030, 2006

Module

3D Metrology