* This example shows how to perform the basic calibration of a single
* camera with multiple images of a calibration object.
dev_update_off ()
* 
* Initialize visualization
*第一個引數：在給定的資料夾'calib'，halcon預設的目錄，第二個引數：影象格式Default Value: 'default'，第三個引數：Default Value: []，第四個引數：AllCalibImageFiles為所有影象的元組
list_image_files ('calib'
 
, 'default', [], AllCalibImageFiles)
*從AllCalibImageFiles挑選指定calib_single_camera名稱的影象，並儲存變數為ImageFiles
tuple_regexp_select (AllCalibImageFiles, 'calib_single_camera', ImageFiles) 
*從儲存區讀取指定的ImageFiles[0]影象並生成Image物件，如果讀取多張生成對應的元組
read_image (Image, ImageFiles[0])
*獲得影象的寬和高
get_image_size (Image, Width, Height)
* 
*關閉之前的圖形視窗
dev_close_window ()
*開啟一個適應影象Width和Height的圖形視窗，左上角行列座標，右下角行列座標，寬度值限制Default Value: -1
 
，Default Value: -1，新圖形視窗的視窗控制代碼。
dev_open_window_fit_size (0, 0, Width, Height, 600, -1, WindowHandle)
*設定當前視窗的文字字型，帶有指定的屬性大小粗體和傾斜，控制代碼；字型大小；字型是否加粗；字型是否傾斜
set_display_font (WindowHandle, 14, 'mono', 'true', 'false')
*返回左上角的位置，並輸出視窗的寬和高
get_window_extents (WindowHandle, Row, Column, WindowWidth, WindowHeight)
*打開了一個新的圖形視窗，它可以用來顯示像影象、區域和行這樣的標誌性物件，以及執行文字輸出。此視窗將自動變為活動狀態，這意味著所有輸出(顯示操作符和自動顯示結果)將被重定向到此視窗。
dev_open_window (0
 
, WindowWidth + 12, 1000 - WindowWidth, WindowHeight, 'white', WindowHandleConfig)
set_display_font (WindowHandleConfig, 14, 'mono', 'true', 'false')
* 
* Create the 3d object models that visualize the current configuration
* of camera and calibration plate. This may take a moment.
*字串賦值
Message := 'Creating 3D object models for visualization...'
*在指定控制代碼視窗中顯示文字，指定的位置，字型顏色，是否帶框
disp_message (WindowHandle, Message, 'window', 12, 12, 'gray', 'false')
create_models (MarksModel, PlateModel, CamModel, BaseModel)
disp_message (WindowHandle, 'Ready.\nNow starting example...', 'window', 32, 12, 'gray', 'false')
wait_seconds (.5)
* -----------------------------------------------------------------------------------------------
* Part I  建立和設定標定模型，
* -------------------------------------------------------------------------------------
* Create and setup the calibration model
* 
* First, create the calibration data structure
*標定設定的型別（5種類型），標定設定中攝像機的數量Default value: 1；標定物件的數量Default value: 1，建立標定資料模型的控制代碼
create_calib_data ('calibration_object', 1, 1, CalibDataID)

* Specify the used calibration plane using the name of the
* description file   標定板的描述檔案，之後可以直接利用生成標定板
CalPlateDescr := 'calplate_80mm.cpd'
*標定資料模型的控制代碼；標定物件的索引；標定板的描述檔案
set_calib_data_calib_object (CalibDataID, 0, CalPlateDescr)
* Set the initial camera parameters--------------相機內參數的含義
* focus: 0.008 (use the nominal focal length of the used lens)
* kappa: 0 (parameter for the division model for the lens distortion)
* sx, sy: 3.7 μm (nominal pixel size of the used sensor)
* cx, cy: 646,482 (use center of the image as initial values
*                   for the principal point)
* ImageWidth, ImageHeight (width and height of the used images)
*相機的初始引數
StartParam := [0.008,0,3.7e-006,3.7e-006,646,482,1292,964]
*標定資料模型的控制代碼；相機索引，相機的型別'area_scan_division'；初始相機內參；
set_calib_data_cam_param (CalibDataID, 0, 'area_scan_division', StartParam)
* -------------------------------------------------------------------------------------------
* Part II從多輻標定影象中提取標記點
* ---------------------------------------------------------------------------------------------
* Extract calibration marks from the calibration images
* 從ImageFiles中開始遍歷
for Index := 0 to |ImageFiles| - 1 by 1
    read_image (Image, ImageFiles[Index])
    * Extract the calibration marks.
    *找出標定版，並提取其中心和輪廓，並估計改標定板相對於相機的姿態，對於每一個標定板的姿態，把所有提取帶的資訊儲存在標定資料模型中。
    *從輸入影象Image，CalibDataID標定資料模型的控制代碼，標定板的索引，標定板的姿態索引
    find_calib_object (Image, CalibDataID, 0, 0, Index, [], [])
    * 
    * Visualize the extracted marks
    * 從標定資料模型CalibDataID中讀取相機座標系下的標定板的位姿；相機索引；被觀測到的標定板的索引；被觀測到的標定板的姿態的索引；儲存相機座標系下標定板的姿態
    get_calib_data_observ_pose (CalibDataID, 0, 0, Index, StartPose)
    if (Index == 0)
        * Just for visualization:
        * Create a 3D model of the viewing volume based on the
        * extracted pose in the first image.
        * (Assume that in image 0 the calibration plate is placed on the base plate.)
        create_pose (0.0, 0.0, StartPose[2] + 0.01, 0, 0, 0, 'Rp+T', 'gba', 'point', BasePoseWorld)
        create_viewing_volume (StartParam, StartPose[2] + 0.001, VolumeModel)
        CamWidth := 1000 - WindowWidth
        CamHeight := WindowHeight
        CamPar := [0.016,0,2.2e-6,2.2e-6,CamHeight / 2,CamWidth / 2,CamHeight,CamWidth]
        * setup the visualization scene
        create_scene_3d (Scene)
        add_scene_3d_camera (Scene, CamPar, CameraIndex)
        create_pose (0.0, 0.0, 0.0, 0, 0, 0, 'Rp+T', 'gba', 'point', Origin)
        * 
        add_scene_3d_instance (Scene, CamModel, Origin, InstanceCamera)
        set_scene_3d_instance_param (Scene, InstanceCamera, 'color', 'blue')
        set_scene_3d_instance_param (Scene, InstanceCamera, 'disp_pose', 'true')
        * 
        add_scene_3d_instance (Scene, BaseModel, BasePoseWorld, InstanceBase)
        set_scene_3d_instance_param (Scene, InstanceBase, 'color', 'gray')
        * 
        add_scene_3d_instance (Scene, PlateModel, StartPose, InstancePlate)
        set_scene_3d_instance_param (Scene, InstancePlate, 'color', 'black')
        * 
        add_scene_3d_instance (Scene, MarksModel, StartPose, InstanceMarks)
        set_scene_3d_instance_param (Scene, InstanceMarks, 'color', 'white')
        * 
        add_scene_3d_instance (Scene, VolumeModel, Origin, InstanceVolume)
        set_scene_3d_instance_param (Scene, InstanceVolume, 'color', 'yellow')
        set_scene_3d_instance_param (Scene, InstanceVolume, 'alpha', 0.4)
        * 
        set_scene_3d_to_world_pose (Scene, [-0.01,-0.07,4.0,306,2.2,330,0])
    endif
    * Display the image and the centers of the calibration marks
    *輸出的輪廓影象；輸入的標定資料模型；Default value: 'marks'；相機索引，標定物件索引，標定物件姿態索引
    get_calib_data_observ_contours (MarkContours, CalibDataID, 'marks', 0, 0, Index)
    dev_set_window (WindowHandle)
    dev_display (Image)
    dev_set_colored (12)
    dev_set_line_width (1)
    dev_display (MarkContours)
    * Visualize the configuration of camera and calibration target
    set_scene_3d_instance_pose (Scene, InstancePlate, StartPose)
    set_scene_3d_instance_pose (Scene, InstanceMarks, StartPose)
    display_scene_3d (WindowHandleConfig, Scene, CameraIndex)
    disp_message (WindowHandle, 'Extracted marks in image ' + Index, 'window', 12, 12, 'black', 'true')
    disp_message (WindowHandleConfig, 'Simulated view of pose ' + Index, 'window', 12, 12, 'black', 'true')
    disp_continue_message (WindowHandle, 'black', 'true')
    stop ()
endfor
* 
* Part III
* 
* Finally calibrate the camera
* 
calibrate_cameras (CalibDataID, Error)
get_calib_data (CalibDataID, 'camera', 0, 'params', CameraParametersCalibrated)
get_calib_data (CalibDataID, 'camera', 0, 'params_labels', ParLabels)
* 
* Display results
dev_set_window (WindowHandle)
dev_clear_window ()
if (|ParLabels| == 12)
    Units := ['m','','','','','','m','m','px','px','px','px']
else
    Units := ['m','','m','m','px','px','px','px']
endif
FormatStringLabels := max(strlen(ParLabels))$'0' + 's'
FormatStringParams := ''
CamParTable := ParLabels$FormatStringLabels + ' = ' + CameraParametersCalibrated + ' ' + Units
Text := 'The camera is now calibrated and ready for'
Text[1] := 'high-accuracy metric measurements.'
Text[2] := 'The final camera parameters are:'
Text[3] := ' '
Message := [Text,CamParTable,' ','Back projection error = ' + Error$'.3f' + ' px']
disp_message (WindowHandle, Message, 'window', 12, 12, 'black', 'true')
stop ()
* 
* Part IV
* 
* Cleanup
clear_calib_data (CalibDataID)
clear_object_model_3d ([MarksModel,PlateModel,CamModel,BaseModel,VolumeModel])
clear_scene_3d (Scene)