Apply an arbitrary affine transformation to XLD polygons.

affine_trans_polygon_xld applies an arbitrary affine transformation, i.e., scaling, rotation, translation, and slant (skewing), to the XLD polygons given in Polygons and returns the transformed polygons in PolygonsAffinTrans. The affine transformation is described by the homogeneous transformation matrix given in HomMat2D. This matrix can be created using the operators hom_mat2d_identity, hom_mat2d_scale, hom_mat2d_rotate, hom_mat2d_translate, etc., or be the result of operators like vector_angle_to_rigid.

The components of the homogeneous transformation matrix are interpreted as follows: The row coordinate of the image corresponds to x and the col coordinate corresponds to y of the coordinate system in which the transformation matrix was defined. This is necessary to obtain a right-handed coordinate system for the image. In particular, this assures that rotations are performed in the correct direction. Note that the (x,y) order of the matrices quite naturally corresponds to the usual (row,column) order for coordinates in the image.

The XLD contours that are possibly referenced by Polygons are neither transformed nor stored with the output polygons, since this is generally impossible without creating inconsistencies for the attributes of the XLD contours. Hence, operators that access the contours associated with a polygon, e.g., split_contours_xld will not work correctly.

The used coordinate system is the same as in affine_trans_pixel. This means that in fact not HomMat2D is applied but a modified version. Therefore, applying affine_trans_polygon_xld corresponds to the following chain of transformations, which is applied to each point (Row_i, Col_i) of the polygon (input and output pixels as homogeneous vectors):

  / RowTrans_i \   / 1 0 -0.5 \              / 1 0 +0.5 \   / Row_i \
  | ColTrans_i | = | 0 1 -0.5 | * HomMat2D * | 0 1 +0.5 | * | Col_i |
  \    1       /   \ 0 0   1  /              \ 0 0   1  /   \  1    /

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

  hom_mat2d_translate(HomMat2D, 0.5, 0.5, HomMat2DTmp)
  hom_mat2d_translate_local(HomMat2DTmp, -0.5, -0.5, HomMat2DAdapted)
  affine_trans_polygon_xld(Polygons, PolygonsAffinTrans, HomMat2DAdapted)

If the matrix HomMat2D represents an affine transformation (i.e., not a projective transformation), affine_trans_polygon_xld returns 2 (H_MSG_TRUE). If the input is empty the behavior can be set via set_system(::'no_object_result',<Result>:). If necessary, an exception handling is raised.

affine_trans_polygon_xld is reentrant and automatically parallelized (on tuple level).

hom_mat2d_identity, hom_mat2d_translate, hom_mat2d_rotate, hom_mat2d_scale

affine_trans_image, affine_trans_region, affine_trans_contour_xld

Foundation