write_cam

Herror ::write_cam_par ( const HTuple &CamParam, const HTuple &CamParFile )

Write the internal camera parameters to text file.

::write_cam_par is used to write the internal camera parameters CamParam to a text file with name CamParFile.

The format of the text file is a (Halcon-independent) generic parameter description. Thus, arbitrary sets of parameters can be grouped together in a hierarchical way. The description of a single parameter within a parameter group consists of the following 3 lines:

   Name : Shortname : Actual value ; 
    Type : Lower bound (optional) : Upper bound (optional) ;
    Description (optional) ;

The following parameter types are supported in this generic format: BOOL, XBOOL (exclusive BOOL), INT, FLOAT, DOUBLE, STRING and FILE_SELECTOR. Comments are marked by a '\#' at the beginning of a line.

The operator ::write_cam_par writes the parameter group Camera:Parameter into the text file CamParFile. This parameter group consists of the 8 parameters Focus, Sx, Sy, Cx, Cy, Kappa , ImageWidth and ImageHeight.

The underlying camera model is a \textbf{pinhole camera with radial distortions} if the focal length passed in CamParam is greater than 0. It describes the transform of a 3D point P_C into a (sub-)pixel [r,c] of the video image by the following equations:

  P_C = (x,y,z)

    u = Focus * x / z
    v = Focus * y / z

   u' = (2*u) / (1+sqrt(1-4*Kappa*(u^2+v^2)))
   v' = (2*v) / (1+sqrt(1-4*Kappa*(u^2+v^2)))

    c = u' / Sx + Cx
    r = v' / Sy + Cy

If the focal length is passed as 0 in CamParam, the camera model of a \textbf{telecentric camera with radial distortions} is used, i.e., it is assumed that the optics of the lens of the camera performs a parallel projection. In this case, the corresponding equations are:

  P_C = (x,y,z) = R*P_W + T

    u = x
    v = y

   u' = (2*u) / (1+sqrt(1-4*Kappa*(u^2+v^2)))
   v' = (2*v) / (1+sqrt(1-4*Kappa*(u^2+v^2)))

    c = u' / Sx + Cx
    r = v' / Sy + Cy

These equations consist of a coordinate transform from the world coordinate system into the camera coordinate system, a perspective or parallel projection into the image plane, a radial distortion of the projected point, and finally a sampling and an image center displacement.

The parameter R and T describe the 3D pose of the camera coordinate system in the world coordinate system. They are called external camera parameters, see also ::hom_mat3d_to_pose and ::create_pose.

The internal camera parameters consist of the focal length (Focus), the radial distortion coefficient (Kappa), the scale factor Sx and Sy (horizontal and vertical distance between cells on the CCD chip), the image center (Cx,Cy), and the used image width and height. The internal camera parameters are - in contrast to the external parameters - independent of the actual pose of the CCD camera. They describe the projection process of the used combination of camera, lens, and framegrabber. The determination of these parameters is done by the camera calibration, see ::camera_calibration.

Parameters

`CamParam` (input_control)	number-array `->` HTuple.double / long
Internal camera parameters.
Number of elements: 8

`CamParFile` (input_control)	string `->` HTuple.char *
File name of internal camera parameters.
Default value: 'campar.dat'
List of values: 'campar.dat', 'campar.initial', 'campar.final'

Example

HTuple StartCamPar,NX,NY,NZ;
HTuple RCoord1,CCoord1,StartPose1;
HTuple RCoord2,CCoord2,StartPose2;
HTuple RCoord3,CCoord3,StartPose3;
HTuple StartPoses,RCoords,CCoords;
HTuple CamParam,NFinalPose,Errors;
// read calibration images
HImage Image1("calib-01.tiff");
HImage Image2("calib-02.tiff");
HImage Image3("calib-03.tiff");
// find calibration pattern
HRegion Caltab1 = Image1.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab2 = Image2.FindCaltab("caltab.descr",3,112,5);
HRegion Caltab3 = Image3.FindCaltab("caltab.descr",3,112,5);
// find calibration marks and start poses
StartCamPar[7] = 576;          // ImageHeight
StartCamPar[6] = 768;          // ImageWidth
StartCamPar[5] = 288;          // Cy
StartCamPar[4] = 384;          // Cx
StartCamPar[3] = 0.000011;     // Sy
StartCamPar[2] = 0.000011;     // Sx
StartCamPar[1] = 0.0;          // Kappa
StartCamPar[0] = 0.008;        // Focus
RCoord1 = Image1.FindMarksAndPose(Caltab1,"caltab.descr",StartCamPar,
                                  128,10,&CCoord1,&StartPose1);
RCoord2 = Image2.FindMarksAndPose(Caltab2,"caltab.descr",StartCamPar,
                                  128,10,&CCoord2,&StartPose2);
RCoord3 = Image3.FindMarksAndPose(Caltab3,"caltab.descr",StartCamPar,
                                  128,10,&CCoord3,&StartPose3);
// read 3D positions of calibration marks
::caltab_points("caltab.descr",&NX,&NY,&NZ);
// camera calibration 
StartPoses = (StartPose1.Append(StartPose2)).Append(StartPose3);
RCoords = (RCoord1.Append(RCoord2)).Append(RCoord3);
CCoords = (CCoord1.Append(CCoord2)).Append(CCoord3);
::camera_calibration(NX,NY,NZ,RCoords,CCoords,StartCamPar,StartPoses,
                     11,&CamParam,&NFinalPose,&Errors);
// write internal camera parameters to file
::write_cam_par(CamParam,"campar.dat");

Result

::write_cam_par returns H_MSG_TRUE if all parameter values are correct and the file has been written successfully. If necessary an exception handling is raised.

Possible Predecessors

::camera_calibration

Module

Camera calibration