find_caltabfind_caltabFindCaltabFindCaltabfind_caltab (Operator)

Name

find_caltabfind_caltabFindCaltabFindCaltabfind_caltab — Segment the region of a standard calibration plate with rectangularly arranged marks in the image.

Signature

find_caltab(Image : CalPlate : CalPlateDescr, SizeGauss, MarkThresh, MinDiamMarks : )

Herror find_caltab(const Hobject Image, Hobject* CalPlate, const char* CalPlateDescr, const Hlong SizeGauss, const Hlong MarkThresh, const Hlong MinDiamMarks)

Herror T_find_caltab(const Hobject Image, Hobject* CalPlate, const Htuple CalPlateDescr, const Htuple SizeGauss, const Htuple MarkThresh, const Htuple MinDiamMarks)

void FindCaltab(const HObject& Image, HObject* CalPlate, const HTuple& CalPlateDescr, const HTuple& SizeGauss, const HTuple& MarkThresh, const HTuple& MinDiamMarks)

HRegion HImage::FindCaltab(const HString& CalPlateDescr, const HTuple& SizeGauss, const HTuple& MarkThresh, Hlong MinDiamMarks) const

HRegion HImage::FindCaltab(const HString& CalPlateDescr, Hlong SizeGauss, Hlong MarkThresh, Hlong MinDiamMarks) const

HRegion HImage::FindCaltab(const char* CalPlateDescr, Hlong SizeGauss, Hlong MarkThresh, Hlong MinDiamMarks) const

HRegion HImage::FindCaltab(const wchar_t* CalPlateDescr, Hlong SizeGauss, Hlong MarkThresh, Hlong MinDiamMarks) const   (Windows only)

static void HOperatorSet.FindCaltab(HObject image, out HObject calPlate, HTuple calPlateDescr, HTuple sizeGauss, HTuple markThresh, HTuple minDiamMarks)

HRegion HImage.FindCaltab(string calPlateDescr, HTuple sizeGauss, HTuple markThresh, int minDiamMarks)

HRegion HImage.FindCaltab(string calPlateDescr, int sizeGauss, int markThresh, int minDiamMarks)

def find_caltab(image: HObject, cal_plate_descr: str, size_gauss: MaybeSequence[Union[int, str]], mark_thresh: MaybeSequence[Union[int, float]], min_diam_marks: int) -> HObject

Description

find_caltabfind_caltabFindCaltabFindCaltabFindCaltabfind_caltab is used to determine the region of a plane calibration plate with circular marks in the input image ImageImageImageImageimageimage. The region must correspond to a standard calibration plate with rectangularly arranged marks described in the file CalPlateDescrCalPlateDescrCalPlateDescrCalPlateDescrcalPlateDescrcal_plate_descr. The successfully segmented region is returned in CalPlateCalPlateCalPlateCalPlatecalPlatecal_plate. The operator provides two algorithms. By setting appropriate integer values in SizeGaussSizeGaussSizeGaussSizeGausssizeGausssize_gauss, MarkThreshMarkThreshMarkThreshMarkThreshmarkThreshmark_thresh, and MinDiamMarksMinDiamMarksMinDiamMarksMinDiamMarksminDiamMarksmin_diam_marks, respectively, you invoke the standard algorithm. If you pass a tuple of parameter names in SizeGaussSizeGaussSizeGaussSizeGausssizeGausssize_gauss and a corresponding tuple of parameter values in MarkThreshMarkThreshMarkThreshMarkThreshmarkThreshmark_thresh, or just two empty tuples, respectively, you invoke the advanced algorithm instead. In this case the value passed in MinDiamMarksMinDiamMarksMinDiamMarksMinDiamMarksminDiamMarksmin_diam_marks is ignored.

Standard algorithm

First, the input image is smoothed (see gauss_imagegauss_imageGaussImageGaussImageGaussImagegauss_image); the size of the used filter mask is given by SizeGaussSizeGaussSizeGaussSizeGausssizeGausssize_gauss. Afterwards, a threshold operator (see thresholdthresholdThresholdThresholdThresholdthreshold) with a minimum gray value MarkThreshMarkThreshMarkThreshMarkThreshmarkThreshmark_thresh is applied. Among the extracted connected regions the most convex region with an almost correct number of holes (corresponding to the dark marks of the calibration plate) is selected. Holes with a diameter smaller than the expected size of the marks MinDiamMarksMinDiamMarksMinDiamMarksMinDiamMarksminDiamMarksmin_diam_marks are eliminated to reduce the impact of noise. The number of marks is read from the calibration plate description file CalPlateDescrCalPlateDescrCalPlateDescrCalPlateDescrcalPlateDescrcal_plate_descr. The complete explanation of this file can be found within the description of gen_caltabgen_caltabGenCaltabGenCaltabGenCaltabgen_caltab.

Advanced algorithm

First, an image pyramid based on ImageImageImageImageimageimage is built. Starting from the highest pyramid level, round regions are segmented with a dynamic threshold. Then, they are associated in groups based on their mutual proximity and it is evaluated whether they can represent marks of a potential calibration plate. The search is terminated once the expected number of marks has been identified in one group. The surrounding lighter area is returned in CalPlateCalPlateCalPlateCalPlatecalPlatecal_plate.

The image pyramid makes the search independent from the size of the image and the marks. The dynamic threshold makes the algorithm immune to bad or irregular illumination. Therefore, in general, no parameter is required. Yet, you can adjust some auxiliary parameters of the advanced algorithm by passing a list of parameter names (strings) to SizeGaussSizeGaussSizeGaussSizeGausssizeGausssize_gauss and a list of corresponding parameter values to MarkThreshMarkThreshMarkThreshMarkThreshmarkThreshmark_thresh. Currently the following parameter is supported:

'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance":

Tolerance factor for gaps between the marks. If the marks appear closer to each other than expected, you might set 'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance" < 1.0 to avoid disturbing patterns outside the calibration plate to be associated with the calibration plate. This can typically happen if the plate is strongly tilted and positioned in front of a background that exposes mark-like patterns. If the distances between single marks deviate significantly, e.g., if the calibration plate appears with strong perspective distortion in the image, you might set 'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance" > 1.0 to enforce the grouping for the more distant marks.

Suggested values: 0.75, 0.9, 1.0 (default), 1.1, 1.2, 1.5

Execution Information

Parameters

ImageImageImageImageimageimage (input_object)  singlechannelimage(-array) objectHImageHObjectHImageHobject (byte / uint2)

Input image.

CalPlateCalPlateCalPlateCalPlatecalPlatecal_plate (output_object)  region objectHRegionHObjectHRegionHobject *

Output region.

CalPlateDescrCalPlateDescrCalPlateDescrCalPlateDescrcalPlateDescrcal_plate_descr (input_control)  filename.read HTuplestrHTupleHtuple (string) (string) (HString) (char*)

File name of the calibration plate description.

Default value: 'caltab_100.descr' "caltab_100.descr" "caltab_100.descr" "caltab_100.descr" "caltab_100.descr" "caltab_100.descr"

List of values: 'caltab_100mm.descr'"caltab_100mm.descr""caltab_100mm.descr""caltab_100mm.descr""caltab_100mm.descr""caltab_100mm.descr", 'caltab_10mm.descr'"caltab_10mm.descr""caltab_10mm.descr""caltab_10mm.descr""caltab_10mm.descr""caltab_10mm.descr", 'caltab_200mm.descr'"caltab_200mm.descr""caltab_200mm.descr""caltab_200mm.descr""caltab_200mm.descr""caltab_200mm.descr", 'caltab_2500um.descr'"caltab_2500um.descr""caltab_2500um.descr""caltab_2500um.descr""caltab_2500um.descr""caltab_2500um.descr", 'caltab_30mm.descr'"caltab_30mm.descr""caltab_30mm.descr""caltab_30mm.descr""caltab_30mm.descr""caltab_30mm.descr", 'caltab_650um.descr'"caltab_650um.descr""caltab_650um.descr""caltab_650um.descr""caltab_650um.descr""caltab_650um.descr", 'caltab_6mm.descr'"caltab_6mm.descr""caltab_6mm.descr""caltab_6mm.descr""caltab_6mm.descr""caltab_6mm.descr", 'caltab_800mm.descr'"caltab_800mm.descr""caltab_800mm.descr""caltab_800mm.descr""caltab_800mm.descr""caltab_800mm.descr", 'caltab_big.descr'"caltab_big.descr""caltab_big.descr""caltab_big.descr""caltab_big.descr""caltab_big.descr", 'caltab_small.descr'"caltab_small.descr""caltab_small.descr""caltab_small.descr""caltab_small.descr""caltab_small.descr"

File extension: .descr

SizeGaussSizeGaussSizeGaussSizeGausssizeGausssize_gauss (input_control)  integer(-array) HTupleMaybeSequence[Union[int, str]]HTupleHtuple (integer / string) (int / long / string) (Hlong / HString) (Hlong / char*)

Filter size of the Gaussian.

Default value: 3

List of values: 0, 3, 5, 7, 9, 11, 'gap_tolerance'"gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance""gap_tolerance"

MarkThreshMarkThreshMarkThreshMarkThreshmarkThreshmark_thresh (input_control)  integer(-array) HTupleMaybeSequence[Union[int, float]]HTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

Threshold value for mark extraction.

Default value: 112

Suggested values: 48, 64, 80, 96, 112, 128, 144, 160, 0.5, 0.9, 1.0, 1.1, 1.5

MinDiamMarksMinDiamMarksMinDiamMarksMinDiamMarksminDiamMarksmin_diam_marks (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Expected minimal diameter of the marks on the calibration plate.

Default value: 5

Suggested values: 3, 5, 9, 15, 30, 50, 70

Example (HDevelop)

* Read calibration image.
read_image(Image, 'calib/calib_distorted_01')
* Find calibration pattern.
find_caltab(Image, CalPlate, 'caltab_100mm.descr', 3, 112, 5)

Example (HDevelop)

* Read calibration image.
read_image(Image, 'calib/calib_distorted_01')
* Find calibration pattern.
find_caltab(Image, CalPlate, 'caltab_100mm.descr', 3, 112, 5)

Example (C++)

// read calibration image
HImage Image("calib/calib_distorted_01");
// find calibration pattern
HRegion CalPlate = Image.FindCaltab("caltab_100mm.descr", 3,112, 5);

Example (HDevelop)

* Read calibration image.
read_image(Image, 'calib/calib_distorted_01')
* Find calibration pattern.
find_caltab(Image, CalPlate, 'caltab_100mm.descr', 3, 112, 5)

Example (HDevelop)

* Read calibration image.
read_image(Image, 'calib/calib_distorted_01')
* Find calibration pattern.
find_caltab(Image, CalPlate, 'caltab_100mm.descr', 3, 112, 5)

Result

find_caltabfind_caltabFindCaltabFindCaltabFindCaltabfind_caltab returns TRUE if all parameter values are correct and an image region is found. The behavior in case of empty input (no image given) can be set via set_system(::'no_object_result',<Result>:)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>) and the behavior in case of an empty result region via set_system(::'store_empty_region',<'2 (H_MSG_TRUE)'/'3 (H_MSG_FALSE)'>:)set_system("store_empty_region",<"2 (H_MSG_TRUE)"/"3 (H_MSG_FALSE)">)SetSystem("store_empty_region",<"2 (H_MSG_TRUE)"/"3 (H_MSG_FALSE)">)SetSystem("store_empty_region",<"2 (H_MSG_TRUE)"/"3 (H_MSG_FALSE)">)SetSystem("store_empty_region",<"2 (H_MSG_TRUE)"/"3 (H_MSG_FALSE)">)set_system("store_empty_region",<"2 (H_MSG_TRUE)"/"3 (H_MSG_FALSE)">). If necessary, an exception is raised.

Possible Predecessors

read_imageread_imageReadImageReadImageReadImageread_image

Possible Successors

find_marks_and_posefind_marks_and_poseFindMarksAndPoseFindMarksAndPoseFindMarksAndPosefind_marks_and_pose

See also

find_marks_and_posefind_marks_and_poseFindMarksAndPoseFindMarksAndPoseFindMarksAndPosefind_marks_and_pose, camera_calibrationcamera_calibrationCameraCalibrationCameraCalibrationCameraCalibrationcamera_calibration, disp_caltabdisp_caltabDispCaltabDispCaltabDispCaltabdisp_caltab, sim_caltabsim_caltabSimCaltabSimCaltabSimCaltabsim_caltab, caltab_pointscaltab_pointsCaltabPointsCaltabPointsCaltabPointscaltab_points, gen_caltabgen_caltabGenCaltabGenCaltabGenCaltabgen_caltab

Module

Foundation