aboutsummaryrefslogtreecommitdiff
path: root/docs/user_guide
diff options
context:
space:
mode:
Diffstat (limited to 'docs/user_guide')
-rw-r--r--docs/user_guide/aruco_markers/camera_calibration.md91
-rw-r--r--docs/user_guide/augmented_reality_pipeline/optic_parameters_calibration.md133
2 files changed, 133 insertions, 91 deletions
diff --git a/docs/user_guide/aruco_markers/camera_calibration.md b/docs/user_guide/aruco_markers/camera_calibration.md
deleted file mode 100644
index ad28200..0000000
--- a/docs/user_guide/aruco_markers/camera_calibration.md
+++ /dev/null
@@ -1,91 +0,0 @@
-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 [ArUcoBoard](../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) 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 [ArUcoBoard](../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) through the camera and then, pass them to an [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector.ArUcoDetector) instance to detect board corners and store them as calibration data to an [ArUcoOpticCalibrator](../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator) for final calibration process.
-
-![Calibration step](../../img/camera_calibration_step.png)
-
-The sample of code below shows how to detect board corners into camera images, store detected corners then process them to build calibration data and, finally, save it into a JSON file:
-
-``` python
-from argaze.ArUcoMarkers import ArUcoMarkersDictionary, ArUcoOpticCalibrator, ArUcoBoard, ArUcoDetector
-
-# Create ArUco dictionary
-aruco_dictionary = ArUcoMarkersDictionary.ArUcoMarkersDictionary('DICT_APRILTAG_16h5')
-
-# Create ArUco optic calibrator
-aruco_optic_calibrator = ArUcoOpticCalibrator.ArUcoOpticCalibrator()
-
-# 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 images from a live Full HD video stream (1920x1080)
-while video_stream.is_alive():
-
- image = video_stream.read()
-
- # Detect all board corners in image
- aruco_detector.detect_board(image, 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(image)
-
- # Append tracked board data for further calibration processing
- aruco_optic_calibrator.store_calibration_data(aruco_detector.board_corners, aruco_detector.board_corners_identifier)
-
-# Start camera calibration processing for Full HD image resolution
-print('Calibrating camera...')
-optic_parameters = aruco_optic_calibrator.calibrate(aruco_board, dimensions=(1920, 1080))
-
-if optic_parameters:
-
- print('\nCalibration succeeded!')
-
- print(f'\nRMS:\n{optic_parameters.rms}')
- print(f'\nDimensions:\n{optic_parameters.dimensions[0]}x{optic_parameters.dimensions[1]}')
- print(f'\nCamera matrix:\n{optic_parameters.K}')
- print(f'\nDistortion coefficients:\n{optic_parameters.D}')
-
- optic_parameters.to_json(f'{args.output}/calibration.json')
-
- print(f'\ncalibration.json file exported into {args.output} folder')
-
-else:
-
- print('\nCalibration error.')
-```
-
-Then, the camera calibration data are loaded to compensate optical distorsion during [ArUcoMarkers](../../argaze.md/#argaze.ArUcoMarkers.ArUcoMarker) detection:
-
-``` python
-from argaze.ArUcoMarkers import ArUcoOpticCalibrator
-
-# Load camera optic parameters
-optic_parameters = ArUcoOpticCalibrator.OpticParameters.from_json('./calibration.json')
-```
diff --git a/docs/user_guide/augmented_reality_pipeline/optic_parameters_calibration.md b/docs/user_guide/augmented_reality_pipeline/optic_parameters_calibration.md
new file mode 100644
index 0000000..0561112
--- /dev/null
+++ b/docs/user_guide/augmented_reality_pipeline/optic_parameters_calibration.md
@@ -0,0 +1,133 @@
+Calibrate optic parameters
+==========================
+
+A camera device have to be calibrated to compensate its optical distorsion.
+
+![Optic parameters calibration](../../img/optic_calibration.png)
+
+## Print calibration board
+
+The first step to calibrate a camera is to create an [ArUcoBoard](../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) 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)
+```
+
+!!! note
+ There is **A3_DICT_APRILTAG_16h5_3cm_35cmx25cm.pdf** file located in *./src/argaze/ArUcoMarkers/utils/* folder ready to be printed on A3 paper sheet.
+
+Let's print the calibration board before to go further.
+
+## Capture board pictures
+
+Then, the calibration process needs to make many different captures of an [ArUcoBoard](../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) through the camera and then, pass them to an [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector.ArUcoDetector) instance to detect board corners and store them as calibration data into an [ArUcoOpticCalibrator](../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator) for final calibration process.
+
+![Calibration step](../../img/optic_calibration_step.png)
+
+The sample of code below illustrates how to:
+
+* load all required ArGaze objects,
+* detect board corners into a Full HD camera video stream,
+* store detected corners as calibration data then,
+* once enough captures are made, process them to find optic parameters and,
+* finally, save optic parameters into a JSON file.
+
+``` python
+from argaze.ArUcoMarkers import ArUcoMarkersDictionary, ArUcoOpticCalibrator, ArUcoBoard, ArUcoDetector
+
+# Create ArUco dictionary
+aruco_dictionary = ArUcoMarkersDictionary.ArUcoMarkersDictionary('DICT_APRILTAG_16h5')
+
+# Create ArUco optic calibrator
+aruco_optic_calibrator = ArUcoOpticCalibrator.ArUcoOpticCalibrator()
+
+# 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)
+
+# Assuming that live Full HD (1920x1080) video stream is enabled
+...
+
+# Assuming there is a way to escape the while loop
+...
+
+ # Capture images from video stream
+ while video_stream.is_alive():
+
+ image = video_stream.read()
+
+ # Detect all board corners in image
+ aruco_detector.detect_board(image, expected_aruco_board, expected_aruco_board.markers_number)
+
+ # If all board corners are detected
+ if aruco_detector.board_corners_number == expected_aruco_board.corners_number:
+
+ # Draw board corners to show that board tracking succeeded
+ aruco_detector.draw_board(image)
+
+ # Append tracked board data for further calibration processing
+ aruco_optic_calibrator.store_calibration_data(aruco_detector.board_corners, aruco_detector.board_corners_identifier)
+
+# Start optic calibration processing for Full HD image resolution
+print('Calibrating optic...')
+optic_parameters = aruco_optic_calibrator.calibrate(aruco_board, dimensions=(1920, 1080))
+
+if optic_parameters:
+
+ # Export optic parameters
+ optic_parameters.to_json('./optic_parameters.json')
+
+ print('Calibration succeeded: optic_parameters.json file exported.')
+
+else:
+
+ print('Calibration failed.')
+```
+
+Below, an optic_parameters JSON file example:
+
+```json
+{
+ "rms": 0.6688921504088245,
+ "dimensions": [
+ 1920,
+ 1080
+ ],
+ "K": [
+ [
+ 1135.6524381415752,
+ 0.0,
+ 956.0685325355497
+ ],
+ [
+ 0.0,
+ 1135.9272506869524,
+ 560.059099810324
+ ],
+ [
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ ],
+ "D": [
+ 0.01655492265003404,
+ 0.1985524264972037,
+ 0.002129965902489484,
+ -0.0019528582922179365,
+ -0.5792910353639452
+ ]
+}
+```