projective_trans_regionProjectiveTransRegionProjectiveTransRegionprojective_trans_regionT_projective_trans_region🔗

Short description🔗

projective_trans_regionProjectiveTransRegionProjectiveTransRegionprojective_trans_regionT_projective_trans_region — Apply a projective transformation to a region.

Signature🔗

projective_trans_region( region Regions, out region TransRegions, hom_mat2d HomMat2D, string Interpolation )

Description🔗

projective_trans_regionProjectiveTransRegion applies the projective transformation specified by the homogeneous matrix HomMat2DhomMat2Dhom_mat_2d on the regions in Regionsregionsregions and returns the transformed regions in TransRegionstransRegionstrans_regions.

For creation and interpretation details of this matrix see also projective_trans_imageProjectiveTransImage.

If 'clip_region'"clip_region" is set to its default value 'true'"true" by set_system('clip_region', 'true') or if the transformation is degenerated and thus produces infinite regions, the output region is clipped by the rectangle with upper left corner (0, 0) and lower right corner ('width'"width", 'height'"height"), where 'width'"width" and 'height'"height" are system variables (see also get_systemGetSystem). If 'clip_region'"clip_region" is 'false'"false", the output region is not clipped except by the maximum supported coordinate size. See the “Installation Guide” for further information about coordinate range limitations. This may result in extremely memory and time intensive computations, so use with care.

Attention🔗

The used coordinate system is the same as in affine_trans_pixelAffineTransPixel. This means that in fact not HomMat2DhomMat2Dhom_mat_2d is applied but a modified version. Therefore, applying projective_trans_regionProjectiveTransRegion corresponds to the following chain of transformations, which is applied to each point \((Row_{i}, Col_{i})\) of the region (input and output pixels as homogeneous vectors):

\[\begin{eqnarray*} \mvHomVectorTwoD{RowTrans_{i}}{ColTrans_{i}} = \mvHomMatrixTwoDElements{1 & 0 & - 0.5 \\ 0 & 1 & - 0.5} \cdot \textrm{HomMat2D} \cdot \mvHomMatrixTwoDElements{1 & 0 & + 0.5 \\ 0 & 1 & + 0.5} \cdot \mvHomVectorTwoD{Row_{i}}{Col_{i}} \end{eqnarray*}\]

As an effect, you might get unexpected results when creating projective transformations based on coordinates that are derived from the region, e.g., by operators like area_centerAreaCenter. For example, if you use this operator to calculate the center of gravity of a rotationally symmetric region and then rotate the region around this point using hom_mat2d_rotateHomMat2dRotate, the resulting region will not lie on the original one. In such a case, you can compensate this effect by applying the following translations to HomMat2DhomMat2Dhom_mat_2d before using it in projective_trans_regionProjectiveTransRegion:


`hom_mat2d_translate(HomMat2D, 0.5, 0.5, HomMat2DTmp)`
`hom_mat2d_translate_local(HomMat2DTmp, -0.5, -0.5, HomMat2DAdapted)`
`projective_trans_region(Region, TransRegion, HomMat2DAdapted, 'bilinear')`

For an explanation of the different 2D coordinate systems used in HALCON, see the introduction of chapter Transformations / 2D Transformations.

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Automatically parallelized on tuple level.

Parameters🔗

Regionsregionsregions (input_object) region(-array) → objectHObjectHRegionHObjectHobject

Input regions.

TransRegionstransRegionstrans_regions (output_object) region(-array) → objectHObjectHRegionHObjectHobject *

Output regions.

HomMat2DhomMat2Dhom_mat_2d (input_control) hom_mat2d → (real)HTuple (double)HHomMat2D, HTuple (double)Sequence[float]Htuple (double)

Homogeneous projective transformation matrix.

Interpolationinterpolationinterpolation (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Interpolation method for the transformation.

Default: 'bilinear'"bilinear"
List of values: 'bilinear', 'nearest_neighbor'"bilinear", "nearest_neighbor"

Combinations with other operators🔗

Combinations

Possible predecessors

vector_to_proj_hom_mat2dVectorToProjHomMat2d, hom_vector_to_proj_hom_mat2dHomVectorToProjHomMat2d, proj_match_points_ransacProjMatchPointsRansac, proj_match_points_ransac_guidedProjMatchPointsRansacGuided, hom_mat3d_projectHomMat3dProject

Module🔗

Foundation