From c4552e04e1271a9210a934233beae5be1943d034 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Wed, 7 Jun 2023 14:34:14 +0200
Subject: Writing User guide and use cases section.

---
 .../user_guide/aruco_markers/camera_calibration.md | 83 ++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 docs/user_guide/aruco_markers/camera_calibration.md

(limited to 'docs/user_guide/aruco_markers/camera_calibration.md')

diff --git a/docs/user_guide/aruco_markers/camera_calibration.md b/docs/user_guide/aruco_markers/camera_calibration.md
new file mode 100644
index 0000000..2a1ba84
--- /dev/null
+++ b/docs/user_guide/aruco_markers/camera_calibration.md
@@ -0,0 +1,83 @@
+Camera calibration
+==================
+
+Any camera device have to be calibrated to compensate its optical distorsion.
+
+![Camera calibration](../../img/camera_calibration.png)
+
+The first step to calibrate a camera is to create an ArUco calibration board like in the code below:
+
+``` python
+from argaze.ArUcoMarkers import ArUcoMarkersDictionary, ArUcoBoard
+
+# Create ArUco dictionary
+aruco_dictionary = ArUcoMarkersDictionary.ArUcoMarkersDictionary('DICT_APRILTAG_16h5')
+
+# Create an ArUco board of 7 columns and 5 rows with 5 cm squares with 3cm ArUco markers inside
+aruco_board = ArUcoBoard.ArUcoBoard(7, 5, 5, 3, aruco_dictionary)
+
+# Export ArUco board with 300 dpi resolution
+aruco_board.save('./calibration_board.png', 300)
+```
+
+Then, the calibration process needs to make many different captures of an ArUco board through the camera and then, pass them to an ArUco detector instance.
+
+![Calibration step](../../img/camera_calibration_step.png)
+
+The sample of code below shows how to detect board corners into camera frames, store detected corners then process them to build calibration data and, finally, save it into a JSON file:
+
+``` python
+from argaze.ArUcoMarkers import ArUcoMarkersDictionary, ArUcoCamera, ArUcoBoard, ArUcoDetector
+
+# Create ArUco dictionary
+aruco_dictionary = ArUcoMarkersDictionary.ArUcoMarkersDictionary('DICT_APRILTAG_16h5')
+
+# Create ArUco camera
+aruco_camera = ArUcoCamera.ArUcoCamera(dimensions=(1920, 1080))
+
+# Create ArUco board of 7 columns and 5 rows with 5 cm squares with 3cm aruco markers inside
+# Note: This board is the one expected during further board tracking
+expected_aruco_board = ArUcoBoard.ArUcoBoard(7, 5, 5, 3, aruco_dictionary)
+
+# Create ArUco detector
+aruco_detector = ArUcoDetector.ArUcoDetector(dictionary=aruco_dictionary, marker_size=3)
+
+# Capture frames from a live Full HD video stream (1920x1080)
+while video_stream.is_alive():
+
+    frame = video_stream.read()
+
+    # Detect all board corners in frame
+    aruco_detector.detect_board(frame, expected_aruco_board, expected_aruco_board.markers_number)
+
+    # If board corners are detected
+    if aruco_detector.board_corners_number > 0:
+
+        # Draw board corners to show that board tracking succeeded
+        aruco_detector.draw_board(frame)
+
+        # Append tracked board data for further calibration processing 
+        aruco_camera.store_calibration_data(aruco_detector.board_corners, aruco_detector.board_corners_identifier)
+
+# Start camera calibration processing for Full HD image resolution
+print('Calibrating camera...')
+aruco_camera.calibrate(expected_aruco_board)
+
+# Print camera calibration data
+print('Calibration succeeded!')
+print(f'RMS:{aruco_camera.rms}')
+print(f'Camera matrix:{aruco_camera.K}')
+print(f'Distortion coefficients:{aruco_camera.D}')
+
+# Save camera calibration data
+aruco_camera.to_json('calibration.json')
+```
+
+Then, the camera calibration data are loaded to compensate optical distorsion during ArUco marker detection:
+
+``` python
+from argaze.ArUcoMarkers import ArUcoCamera
+
+# Load camera calibration data
+aruco_camera = ArUcoCamera.ArUcoCamera.from_json('./calibration.json')
+```
-- 
cgit v1.1