| Operators |
gen_image_to_world_plane_map — Generate a projection map that describes the mapping between the image plane and a the plane z=0 of a world coordinate system.
gen_image_to_world_plane_map( : Map : CameraParam, WorldPose, WidthIn, HeightIn, WidthMapped, HeightMapped, Scale, MapType : )
gen_image_to_world_plane_map generates a projection map Map, which describes the mapping between the image plane and the plane z=0 (plane of measurements) in a world coordinate system. This map can be used to rectify an image with the operator map_image. The rectified image shows neither radial nor perspective distortions; it corresponds to an image acquired by a distortion-free camera that looks perpendicularly onto the plane of measurements. The world coordinate system is chosen by passing its 3D pose relative to the camera coordinate system in WorldPose. In CameraParam you must pass the internal camera parameters (see calibrate_cameras for the sequence of the parameters and the underlying camera model).
In many cases CameraParam and WorldPose are the result of calibrating the camera with the operator calibrate_cameras. See below for an example.
The size of the images to be mapped can be specified by the parameters WidthIn and HeightIn. The pixel position of the upper left corner of the output image is determined by the origin of the world coordinate system. The size of the output image can be chosen by the parameters WidthMapped, HeightMapped, and Scale. WidthMapped and HeightMapped must be given in pixels.
With the parameter Scale you can specify the size of a pixel in the transformed image. There are two typical scenarios: First, you can scale the image such that pixel coordinates in the transformed image directly correspond to metric units, e.g., that one pixel corresponds to one micron. This is useful if you want to perform measurements in the transformed image which will then directly result in metric results. The second scenario is to scale the image such that its content appears in a size similar to the original image. This is useful, e.g., if you want to perform shape-based matching in the transformed image.
Scale must be specified as the ratio desired pixel size/original unit. A pixel size of 1um means that a pixel in the transformed image corresponds to the area 1um x 1um in the plane of measurements. The original unit is determined by the coordinates of the calibration object. If the original unit is meters (which is the case if you use the standard calibration plate), you can use the parameter values 'm', 'cm', 'mm', 'microns', or 'um' to directly set the unit of pixel coordinates in the transformed image.
The mapping function is stored in the output image Map. Map has the same size as the resulting images after the mapping. MapType is used to specify the type of the output Map. If 'nearest_neighbor' is chosen, Map consists of one image containing one channel, in which for each pixel of the resulting image the linearized coordinate of the pixel of the input image is stored that is the nearest neighbor to the transformed coordinates. If 'bilinear' interpolation is chosen, Map consists of one image containing five channels. In the first channel for each pixel in the resulting image the linearized coordinates of the pixel in the input image is stored that is in the upper left position relative to the transformed coordinates. The four other channels contain the weights of the four neighboring pixels of the transformed coordinates which are used for the bilinear interpolation, in the following order:
| 2 | 3 |
| 4 | 5 |
The second channel, for example, contains the weights of the pixels that lie to the upper left relative to the transformed coordinates. If 'coord_map_sub_pix' is chosen, Map consists of one vector field image of the semantic type 'vector_field_absolute', in which for each pixel of the resulting image the subpixel precise coordinates in the input image are stored.
If several images have to be mapped using the same camera parameters, gen_image_to_world_plane_map in combination with map_image is much more efficient than the operator image_to_world_plane because the mapping function needs to be computed only once.
If you want to re-use the created map in another program, you can save it as a multi-channel image with the operator write_image, using the format 'tiff'.
Image containing the mapping data.
Internal camera parameters.
3D pose of the world coordinate system in camera coordinates.
Number of elements: 7
Width of the images to be transformed.
Restriction: WidthIn >= 1
Height of the images to be transformed.
Restriction: HeightIn >= 1
Width of the resulting mapped images in pixels.
Restriction: WidthMapped >= 1
Height of the resulting mapped images in pixels.
Restriction: HeightMapped >= 1
Scale or unit.
Default value: 'm'
Suggested values: 'm', 'cm', 'mm', 'microns', 'um', 1.0, 0.01, 0.001, 1.0e-6, 0.0254, 0.3048, 0.9144
Restriction: Scale > 0
Type of the mapping.
Default value: 'bilinear'
List of values: 'bilinear', 'coord_map_sub_pix', 'nearest_neighbor'
* Calibrate camera.
calibrate_cameras (CalibDataID, Error)
* Obtain camera parameters.
get_calib_data (CalibDataID, 'camera', 0, 'params', CamParam)
* Example values, if no calibration data is available:
CamParam := ['area_scan_division', 0.0087, -1859, 8.65e-006, 8.6e-006, \
362.5, 291.6, 768, 576]
* Get reference pose (pose 4 of calibration object 0).
get_calib_data (CalibDataID, 'calib_obj_pose',\
[0,4], 'pose', Pose)
* Example values, if no calibration data is available:
Pose := [-0.11, -0.21, 2.51, 352.73, 346.73, 336.48, 0]
* Compensate thickness of plate.
set_origin_pose (Pose, -1.125, -1.0, 0, PoseNewOrigin)
* Transform the image into the world plane.
read_image (Image, 'calib/calib-3d-coord-04')
gen_image_to_world_plane_map (MapSingle, CamParam, PoseNewOrigin,\
CamParam[6], CamParam[7], 900, 800, 0.0025, 'bilinear')
map_image (Image, MapSingle, ImageMapped)
gen_image_to_world_plane_map returns 2 (H_MSG_TRUE) if all parameter values are correct. If necessary, an exception is raised.
create_pose, hom_mat3d_to_pose, camera_calibration, hand_eye_calibration, set_origin_pose
map_image, contour_to_world_plane_xld, image_points_to_world_plane
Calibration
| Operators |