From 9958a965725764aee7150a67d9f63e241b4c345e Mon Sep 17 00:00:00 2001 From: Théo de la Hogue Date: Wed, 17 Apr 2024 14:16:40 +0200 Subject: Improving aruco marker pipeline documentation. --- .../aruco_marker_pipeline/aoi_3d_description.md | 2 +- .../aruco_marker_pipeline/aoi_3d_frame.md | 2 +- .../aruco_marker_pipeline/aoi_3d_projection.md | 4 +- .../aruco_marker_description.md | 120 +++++++++++ .../aruco_markers_description.md | 120 ----------- .../configuration_and_execution.md | 28 +-- .../aruco_marker_pipeline/introduction.md | 10 +- .../aruco_marker_pipeline/pose_estimation.md | 12 +- .../gaze_analysis_pipeline/aoi_analysis.md | 2 +- .../configuration_and_execution.md | 2 +- mkdocs.yml | 2 +- src/argaze/utils/aruco_marker_group_export.py | 234 +++++++++++++++++++++ 12 files changed, 386 insertions(+), 152 deletions(-) create mode 100644 docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md delete mode 100644 docs/user_guide/aruco_marker_pipeline/aruco_markers_description.md create mode 100644 src/argaze/utils/aruco_marker_group_export.py diff --git a/docs/user_guide/aruco_marker_pipeline/aoi_3d_description.md b/docs/user_guide/aruco_marker_pipeline/aoi_3d_description.md index 23ea550..e8342c7 100644 --- a/docs/user_guide/aruco_marker_pipeline/aoi_3d_description.md +++ b/docs/user_guide/aruco_marker_pipeline/aoi_3d_description.md @@ -1,7 +1,7 @@ Describe 3D AOI =============== -Now [scene pose is estimated](aruco_markers_description.md) thanks to ArUco markers description, [areas of interest (AOI)](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) need to be described into the same 3D referential. +Now [scene pose is estimated](aruco_marker_description.md) thanks to ArUco markers description, [areas of interest (AOI)](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) need to be described into the same 3D referential. In the example scene, the two screens, the control panel and the window are considered as areas of interest. diff --git a/docs/user_guide/aruco_marker_pipeline/aoi_3d_frame.md b/docs/user_guide/aruco_marker_pipeline/aoi_3d_frame.md index e1614d3..358c412 100644 --- a/docs/user_guide/aruco_marker_pipeline/aoi_3d_frame.md +++ b/docs/user_guide/aruco_marker_pipeline/aoi_3d_frame.md @@ -82,7 +82,7 @@ An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) instance can con ### Left_Screen & Right_Screen -The names of 3D AOI **and** their related [ArFrames](../../argaze.md/#argaze.ArFeatures.ArFrame). Basically useful for visualization purpose. +The names of 3D AOI **and** their related [ArFrames](../../argaze.md/#argaze.ArFeatures.ArFrame). Basically, it is useful for visualization purposes. !!! warning "AOI / Frame names policy" diff --git a/docs/user_guide/aruco_marker_pipeline/aoi_3d_projection.md b/docs/user_guide/aruco_marker_pipeline/aoi_3d_projection.md index e0f7f4c..ae31075 100644 --- a/docs/user_guide/aruco_marker_pipeline/aoi_3d_projection.md +++ b/docs/user_guide/aruco_marker_pipeline/aoi_3d_projection.md @@ -47,7 +47,7 @@ An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) instance can con ### MyLayer -The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualization purpose. +The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically, it is useful for visualization purposes. ### *aoi_scene* @@ -106,7 +106,7 @@ An [ArUcoCamera](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contai ### MyLayer -The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualization purpose. +The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically, it is useful for visualization purposes. !!! warning "Layer name policy" diff --git a/docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md b/docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md new file mode 100644 index 0000000..1d703d4 --- /dev/null +++ b/docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md @@ -0,0 +1,120 @@ +Set up ArUco markers +==================== + +First of all, ArUco markers needs to be printed and placed into the scene. + +Here is an example scene where markers are surrounding a workspace with two screens, a control panel and a window. + +![Scene](../../img/scene.png) + +## Print ArUco markers from an ArUco dictionary + +ArUco markers always belong to a set of markers called the ArUco marker dictionary. + +![ArUco dictionaries](../../img/aruco_dictionaries.png) + +Many ArUco marker dictionaries exist with properties concerning the format, the number of markers, or the difference between each marker to avoid errors in tracking. + +Here is the documention [about ArUco markers dictionaries](https://docs.opencv.org/3.4/d9/d6a/group__aruco.html#gac84398a9ed9dd01306592dd616c2c975). + +The creation of [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.ArUcoMarker) pictures from a dictionary is illustrated in the code below: + +```python +from argaze.ArUcoMarker import ArUcoMarkerDictionary + +# Create a dictionary of specific April tags +aruco_dictionary = ArUcoMarkerDictionary.ArUcoMarkerDictionary('DICT_APRILTAG_16h5') + +# Export marker n°5 as 3.5 cm picture with 300 dpi resolution +aruco_dictionary.create_marker(5, 3.5).save('./markers/', 300) + +# Export all dictionary markers as 3.5 cm pictures with 300 dpi resolution +aruco_dictionary.save('./markers/', 3.5, 300) +``` + +!!! note + There is an **A4_DICT_APRILTAG_16h5_5cm_0-7.pdf** file located in *./src/argaze/ArUcoMarker/utils/* folder ready to be printed on an A4 paper sheet. + +Let's print some of them before going further. + +!!! warning + Print markers with a blank zone around them to help in their detection. + +## Describe ArUco markers place + +Once [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.ArUcoMarker) pictures are placed into a scene, it is possible to describe their 3D places into a file. + +![ArUco markers description](../../img/aruco_markers_description.png) + +Wherever the origin point is, all markers places need to be described on a [right-handed 3D axis](https://robotacademy.net.au/lesson/right-handed-3d-coordinate-frame/) where: + +* +X is pointing to the right, +* +Y is pointing to the top, +* +Z is pointing to the backward. + +!!! warning + All ArUco markers spatial values must be given in **centimeters**. + +### Edit OBJ file description + +OBJ file format could be exported from most 3D editors. + +``` obj +o DICT_APRILTAG_16h5#0_Marker +v 15.000000 0.378741 0.330527 +v 20.000000 0.378741 0.330527 +v 15.000000 5.120359 -1.255996 +v 20.000000 5.120359 -1.255996 +f 1 2 4 3 +o DICT_APRILTAG_16h5#1_Marker +v 43.500000 31.428055 18.333317 +v 48.500000 31.428055 18.333317 +v 43.500000 36.428055 18.333317 +v 48.500000 36.428055 18.333317 +f 5 6 8 7 +o DICT_APRILTAG_16h5#2_Marker +v 38.500000 2.678055 5.498381 +v 43.500000 2.678055 5.498381 +v 38.500000 5.178055 1.168253 +v 43.500000 5.178055 1.168253 +f 9 10 12 11 +``` + +Here are some common OBJ file features needed to describe ArUco markers places: + +* Object line (starting with *o* key) indicate marker dictionary and id by following this format: **DICTIONARY**#**ID**\_Marker. +* Vertice line (starting with *v* key) indicate marker corners. The marker size will be automatically deducted from the geometry. +* Face line (starting with *f* key) link vertice and normal indexes together. + +!!! warning + Markers have to belong to the same dictionary. + +!!! note + Markers can have different sizes. + +### Edit JSON file description + +JSON file format allows to describe markers places using translation and euler angle rotation vectors. + +``` json +{ + "dictionary": "DICT_APRILTAG_16h5", + "places": { + "0": { + "translation": [17.5, 2.75, -0.5], + "rotation": [-18.5, 0, 0], + "size": 5 + }, + "1": { + "translation": [46, 34, 18.333], + "rotation": [0, 70, 0], + "size": 5 + }, + "2": { + "translation": [41, 4, 3.333], + "rotation": [-60, 0, 0], + "size": 5 + } + } +} +``` diff --git a/docs/user_guide/aruco_marker_pipeline/aruco_markers_description.md b/docs/user_guide/aruco_marker_pipeline/aruco_markers_description.md deleted file mode 100644 index 6da600c..0000000 --- a/docs/user_guide/aruco_marker_pipeline/aruco_markers_description.md +++ /dev/null @@ -1,120 +0,0 @@ -Set up ArUco markers -==================== - -First of all, ArUco markers needs to be printed and placed into the scene. - -Here is an example scene where markers are surrounding a workspace with two screens, a control panel and a window. - -![Scene](../../img/scene.png) - -## Print ArUco markers from an ArUco dictionary - -ArUco markers always belongs to a set of markers called ArUco markers dictionary. - -![ArUco dictionaries](../../img/aruco_dictionaries.png) - -Many ArUco dictionaries exist with properties concerning the format, the number of markers or the difference between each markers to avoid error in tracking. - -Here is the documention [about ArUco markers dictionaries](https://docs.opencv.org/3.4/d9/d6a/group__aruco.html#gac84398a9ed9dd01306592dd616c2c975). - -The creation of [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.ArUcoMarker) pictures from a dictionary is illustrated in the code below: - -```python -from argaze.ArUcoMarker import ArUcoMarkerDictionary - -# Create a dictionary of specific April tags -aruco_dictionary = ArUcoMarkerDictionary.ArUcoMarkerDictionary('DICT_APRILTAG_16h5') - -# Export marker n°5 as 3.5 cm picture with 300 dpi resolution -aruco_dictionary.create_marker(5, 3.5).save('./markers/', 300) - -# Export all dictionary markers as 3.5 cm pictures with 300 dpi resolution -aruco_dictionary.save('./markers/', 3.5, 300) -``` - -!!! note - There is **A4_DICT_APRILTAG_16h5_5cm_0-7.pdf** file located in *./src/argaze/ArUcoMarker/utils/* folder ready to be printed on A4 paper sheet. - -Let's print some of them before to go further. - -!!! warning - Print markers with a blank zone around them to help in their detection. - -## Describe ArUco markers place - -Once [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.ArUcoMarker) pictures are placed into a scene it is possible to describe their 3D places into a file. - -![ArUco markers description](../../img/aruco_markers_description.png) - -Where ever the origin point is, all markers places need to be described in a [right-handed 3D axis](https://robotacademy.net.au/lesson/right-handed-3d-coordinate-frame/) where: - -* +X is pointing to the right, -* +Y is pointing to the top, -* +Z is pointing to the backward. - -!!! warning - All ArUco markers spatial values must be given in **centimeters**. - -### Edit OBJ file description - -OBJ file format could be exported from most 3D editors. - -``` obj -o DICT_APRILTAG_16h5#0_Marker -v 15.000000 0.378741 0.330527 -v 20.000000 0.378741 0.330527 -v 15.000000 5.120359 -1.255996 -v 20.000000 5.120359 -1.255996 -f 1 2 4 3 -o DICT_APRILTAG_16h5#1_Marker -v 43.500000 31.428055 18.333317 -v 48.500000 31.428055 18.333317 -v 43.500000 36.428055 18.333317 -v 48.500000 36.428055 18.333317 -f 5 6 8 7 -o DICT_APRILTAG_16h5#2_Marker -v 38.500000 2.678055 5.498381 -v 43.500000 2.678055 5.498381 -v 38.500000 5.178055 1.168253 -v 43.500000 5.178055 1.168253 -f 9 10 12 11 -``` - -Here are common OBJ file features needed to describe ArUco markers places: - -* Object lines (starting with *o* key) indicate markers dictionary and id by following this format: **DICTIONARY**#**ID**\_Marker. -* Vertice lines (starting with *v* key) indicate markers corners. The marker size will be automatically deducted from the geometry. -* Face (starting with *f* key) link vertices and normals indexes together. - -!!! warning - Markers have to belong to the same dictionary. - -!!! note - Markers can have different size. - -### Edit JSON file description - -JSON file format allows to describe markers places using translation and euler angle rotation vectors. - -``` json -{ - "dictionary": "DICT_APRILTAG_16h5", - "places": { - "0": { - "translation": [17.5, 2.75, -0.5], - "rotation": [-18.5, 0, 0], - "size": 5 - }, - "1": { - "translation": [46, 34, 18.333], - "rotation": [0, 70, 0], - "size": 5 - }, - "2": { - "translation": [41, 4, 3.333], - "rotation": [-60, 0, 0], - "size": 5 - } - } -} -``` diff --git a/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md b/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md index f2bddf8..cadaf61 100644 --- a/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md +++ b/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md @@ -1,9 +1,9 @@ Load and execute pipeline ========================= -Once [ArUco markers are placed into a scene](aruco_markers_description.md), they can be detected thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) class. +Once [ArUco markers are placed into a scene](aruco_marker_description.md), they can be detected thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) class. -As [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame), the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) class also benefits from all the services described in [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md). +As [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame), the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) class also benefits from all the services described in the [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md). ![ArUco camera frame](../../img/aruco_camera_frame.png) @@ -68,30 +68,30 @@ Now, let's understand the meaning of each JSON entry. ### argaze.ArUcoMarker.ArUcoCamera.ArUcoCamera -The loaded object class name. +The class name of the object being loaded. ### *name - inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)* -The name of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) frame. Basically useful for visualization purpose. +The name of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) frame. Basically, it is useful for visualization purposes. ### *size - inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)* -The size of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) frame in pixels. Be aware that gaze positions have to be in the same range of value to be projected in. +The size of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) frame in pixels. Be aware that gaze positions have to be in the same range of value to be projected. ### *aruco_detector* -The first [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) pipeline step is to detect ArUco markers inside input image. +The first [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) pipeline step is to detect ArUco markers inside the input image. ![ArUco markers detection](../../img/aruco_camera_markers_detection.png) -The [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarker.ArUcoDetector) is in charge to detect all markers from a specific dictionary. +The [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarker.ArUcoDetector) is in charge of detecting all markers from a specific dictionary. !!! warning "Mandatory" JSON *aruco_detector* entry is mandatory. ### *gaze_movement_identifier - inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)* -The first [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) pipeline step dedicated to identify fixations or saccades from consecutive timestamped gaze positions. +The first [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) pipeline step is dedicated to identify fixations or saccades from consecutive timestamped gaze positions. ![Gaze movement identification](../../img/aruco_camera_gaze_movement_identification.png) @@ -103,7 +103,7 @@ The usual [ArFrame visualization parameters](../gaze_analysis_pipeline/visualiza ### Detect ArUco markers, estimate scene pose and project 3D AOI -Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole pipeline dedicated to ArUco markers detection, scene pose estimation and 3D AOI projection. +Pass each camera image to the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole pipeline dedicated to ArUco marker detection, scene pose estimation and 3D AOI projection. !!! warning "Mandatory" @@ -127,11 +127,11 @@ Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures ... aruco_camera.image() ``` -### Analyse timestamped gaze positions into camera frame +### Analyse time-stamped gaze positions into the camera frame -As mentioned above, [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and so, benefits from all the services described in [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md). +As mentioned above, [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and, so benefits from all the services described in the [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md). -Particularly, timestamped gaze positions can be passed one by one to [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole pipeline dedicated to gaze analysis. +Particularly, timestamped gaze positions can be passed one by one to the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole pipeline dedicated to gaze analysis. !!! warning "Mandatory" @@ -154,6 +154,6 @@ Particularly, timestamped gaze positions can be passed one by one to [ArUcoCamer !!! note "" - At this point, the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method only detects ArUco markers and the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArCamera.look) method only processes gaze movement identification without any AOI support as no scene description is provided into the JSON configuration file. + At this point, the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method only detects ArUco marker and the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArCamera.look) method only processes gaze movement identification without any AOI support as no scene description is provided into the JSON configuration file. - Read the next chapters to learn [how to estimate scene pose](pose_estimation.md), [how to describe 3D scene's AOI](aoi_3d_description.md) and [how to project them into camera frame](aoi_3d_projection.md). \ No newline at end of file + Read the next chapters to learn [how to estimate scene pose](pose_estimation.md), [how to describe a 3D scene's AOI](aoi_3d_description.md) and [how to project them into the camera frame](aoi_3d_projection.md). \ No newline at end of file diff --git a/docs/user_guide/aruco_marker_pipeline/introduction.md b/docs/user_guide/aruco_marker_pipeline/introduction.md index 273de16..ef2e4da 100644 --- a/docs/user_guide/aruco_marker_pipeline/introduction.md +++ b/docs/user_guide/aruco_marker_pipeline/introduction.md @@ -1,7 +1,7 @@ Overview ======== -This section explains how to build augmented reality pipelines based on [ArUco Markers technology](https://www.sciencedirect.com/science/article/abs/pii/S0031320314000235) for various use cases. +This section explains how to build augmented reality pipelines based on [ArUco Marker technology](https://www.sciencedirect.com/science/article/abs/pii/S0031320314000235) for various use cases. The OpenCV library provides a module to detect fiducial markers in a picture and estimate their poses. @@ -15,11 +15,11 @@ First, let's look at the schema below. It gives an overview of the main notions To build your own ArUco marker pipeline, you need to know: -* [How to setup ArUco markers into a scene](aruco_markers_description.md), +* [How to setup ArUco markers into a scene](aruco_marker_description.md), * [How to load and execute ArUco marker pipeline](configuration_and_execution.md), -* [How to estimate scene pose](pose_estimation.md), -* [How to describe a scene's AOI](aoi_3d_description.md), -* [How to project 3D AOI into camera frame](aoi_3d_projection.md), +* [How to estimate the scene pose](pose_estimation.md), +* [How to describe the scene's AOI](aoi_3d_description.md), +* [How to project 3D AOI into the camera frame](aoi_3d_projection.md), * [How to define a 3D AOI as a frame](aoi_3d_frame.md). More advanced features are also explained like: diff --git a/docs/user_guide/aruco_marker_pipeline/pose_estimation.md b/docs/user_guide/aruco_marker_pipeline/pose_estimation.md index 5ebe783..02a4979 100644 --- a/docs/user_guide/aruco_marker_pipeline/pose_estimation.md +++ b/docs/user_guide/aruco_marker_pipeline/pose_estimation.md @@ -1,13 +1,13 @@ Estimate scene pose =================== -Once [ArUco markers are placed into a scene](aruco_markers_description.md) and [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) is [configured](configuration_and_execution.md), scene pose can be estimated. +Once [ArUco markers are placed into a scene](aruco_marker_description.md) and the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) is [configured](configuration_and_execution.md), the scene pose can be estimated. ![Scene pose estimation](../../img/aruco_camera_pose_estimation.png) ## Add ArUcoScene to ArUcoCamera JSON configuration file -An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) class defines a space with [ArUco markers inside](aruco_markers_description.md) helping to estimate scene pose when they are watched by [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera). +An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) class defines a space with [ArUco markers inside](aruco_marker_description.md), helping to estimate scene pose when they are watched by [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera). Here is an extract from the JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) configuration file with a sample where one scene is added and displayed: @@ -67,15 +67,15 @@ Now, let's understand the meaning of each JSON entry. ### *scenes* -An [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) instance can contains multiples [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) stored by name. +An [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) instance can contain multiples [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) stored by name. ### MyScene -The name of an [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene). Basically useful for visualization purpose. +The name of an [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene). Basically, it is useful for visualization purposes. ### *aruco_markers_group* -The 3D places of ArUco markers into the scene as defined at [ArUco markers description chapter](aruco_markers_description.md). Thanks to this description, it is possible to estimate the pose of [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) in [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) frame. +The 3D placement of ArUco markers into the scene, as defined in the [ArUco marker description chapter](aruco_marker_description.md). Thanks to this description, it is possible to estimate the pose of [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) in an [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) frame. !!! note @@ -83,4 +83,4 @@ The 3D places of ArUco markers into the scene as defined at [ArUco markers descr ### *draw_scenes* -The drawing parameters of each loaded [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) in [ArUcoCamera.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image). +The drawing parameters of each loaded [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) in an [ArUcoCamera.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image). diff --git a/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md b/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md index fa7a71e..be27c69 100644 --- a/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md +++ b/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md @@ -71,7 +71,7 @@ An [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contains m ### MyLayer -The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualization purpose. +The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically, it is useful for visualization purposes. ### *aoi_scene* diff --git a/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md b/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md index 7eba8a7..57a9d71 100644 --- a/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md +++ b/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md @@ -51,7 +51,7 @@ Now, let's understand the meaning of each JSON entry. ### argaze.ArFeatures.ArFrame -The loaded object class name. +The class name of the object being loaded. ### *name* diff --git a/mkdocs.yml b/mkdocs.yml index 35bff5a..5b25529 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,7 +26,7 @@ nav: - user_guide/gaze_analysis_pipeline/advanced_topics/gaze_position_calibration.md - ArUco marker pipeline: - user_guide/aruco_marker_pipeline/introduction.md - - user_guide/aruco_marker_pipeline/aruco_markers_description.md + - user_guide/aruco_marker_pipeline/aruco_marker_description.md - user_guide/aruco_marker_pipeline/configuration_and_execution.md - user_guide/aruco_marker_pipeline/pose_estimation.md - user_guide/aruco_marker_pipeline/aoi_3d_description.md diff --git a/src/argaze/utils/aruco_marker_group_export.py b/src/argaze/utils/aruco_marker_group_export.py new file mode 100644 index 0000000..961d12b --- /dev/null +++ b/src/argaze/utils/aruco_marker_group_export.py @@ -0,0 +1,234 @@ +#!/usr/bin/env python + +""" + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. +You should have received a copy of the GNU General Public License along with +this program. If not, see . +""" + +__author__ = "Théo de la Hogue" +__credits__ = [] +__copyright__ = "Copyright 2023, Ecole Nationale de l'Aviation Civile (ENAC)" +__license__ = "GPLv3" + +import argparse +import contextlib + +import cv2 + +from argaze import DataFeatures +from argaze.ArUcoMarker import ArUcoDetector, ArUcoOpticCalibrator, ArUcoMarkerGroup +from argaze.utils import UtilsFeatures + + +def main(): + """ + Detect DICTIONARY and SIZE ArUco markers inside a MOVIE frame then, export detected ArUco markers group as .obj file into an OUTPUT folder. + """ + + # Manage arguments + parser = argparse.ArgumentParser(description=main.__doc__.split('-')[0]) + parser.add_argument('movie', metavar='MOVIE', type=str, default=None, help='movie path') + parser.add_argument('dictionary', metavar='DICTIONARY', type=str, default=None, + help='expected ArUco markers dictionary') + parser.add_argument('size', metavar='SIZE', type=float, default=None, help='expected ArUco markers size (in cm)') + + parser.add_argument('-p', '--parameters', metavar='PARAMETERS', type=str, default=None, + help='ArUco detector parameters file') + parser.add_argument('-op', '--optic_parameters', metavar='OPTIC_PARAMETERS', type=str, default=None, + help='ArUco detector optic parameters file') + + parser.add_argument('-s', '--start', metavar='START', type=float, default=0., help='start time in second') + parser.add_argument('-o', '--output', metavar='OUTPUT', type=str, default='.', help='export folder path') + parser.add_argument('-v', '--verbose', action='store_true', default=False, + help='enable verbose mode to print information in console') + + args = parser.parse_args() + + # Load movie + video_capture = cv2.VideoCapture(args.movie) + + video_fps = video_capture.get(cv2.CAP_PROP_FPS) + image_width = int(video_capture.get(cv2.CAP_PROP_FRAME_WIDTH)) + image_height = int(video_capture.get(cv2.CAP_PROP_FRAME_HEIGHT)) + + # Edit ArUco detector configuration + configuration = { + "dictionary": args.dictionary + } + + if args.parameters: + configuration["parameters"] = args.parameters + + if args.optic_parameters: + configuration["optic_parameters"] = args.optic_parameters + + # Load ArUco detector configuration + aruco_detector = DataFeatures.from_dict(ArUcoDetector.ArUcoDetector, configuration) + + if args.verbose: + print(aruco_detector) + + # Create empty ArUco scene + aruco_markers_group = None + + # Edit draw parameters + draw_parameters = { + "color": [255, 255, 255], + "draw_axes": { + "thickness": 4 + } + } + + # Create a window + cv2.namedWindow("Export detected ArUco markers", cv2.WINDOW_AUTOSIZE) + + # Init image selection + current_image_index = -1 + _, current_image = video_capture.read() + next_image_index = int(args.start * video_fps) + refresh = False + + # Waiting for 'ctrl+C' interruption + with contextlib.suppress(KeyboardInterrupt): + + while True: + + # Select a new image and detect markers once + if next_image_index != current_image_index or refresh: + + video_capture.set(cv2.CAP_PROP_POS_FRAMES, next_image_index) + + success, video_image = video_capture.read() + + video_height, video_width, _ = video_image.shape + + # Create default optic parameters adapted to frame size + if aruco_detector.optic_parameters is None: + # Note: The choice of 1000 for default focal length should be discussed... + aruco_detector.optic_parameters = ArUcoOpticCalibrator.OpticParameters(rms=-1, dimensions=( + video_width, video_height), K=ArUcoOpticCalibrator.K0(focal_length=(1000., 1000.), + width=video_width, height=video_height)) + + if success: + + # Refresh once + refresh = False + + current_image_index = video_capture.get(cv2.CAP_PROP_POS_FRAMES) - 1 + current_image_time = video_capture.get(cv2.CAP_PROP_POS_MSEC) + + try: + + # Detect and project AR features + aruco_detector.detect_markers(video_image) + + # Estimate all detected markers pose + aruco_detector.estimate_markers_pose(args.size) + + # Build aruco scene from detected markers + aruco_markers_group = ArUcoMarkerGroup.ArUcoMarkerGroup(aruco_detector.dictionary, + aruco_detector.detected_markers()) + + # Detection succeeded + exception = None + + # Write errors + except Exception as e: + + aruco_markers_group = None + + exception = e + + # Draw detected markers + aruco_detector.draw_detected_markers(video_image, draw_parameters) + + # Write detected markers + cv2.putText(video_image, f'Detecting markers {list(aruco_detector.detected_markers().keys())}', + (20, video_height - 40), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 1, cv2.LINE_AA) + + # Write timing + cv2.putText(video_image, f'Frame at {int(current_image_time)}ms', (20, 40), + cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 1, cv2.LINE_AA) + + # Write exception + if exception is not None: + cv2.putText(video_image, f'error: {exception}', (20, 80), cv2.FONT_HERSHEY_SIMPLEX, 1, + (0, 255, 255), 1, cv2.LINE_AA) + + # Write documentation + cv2.putText(video_image, f'<- previous image', (video_width - 500, video_height - 160), + cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 255), 1, cv2.LINE_AA) + cv2.putText(video_image, f'-> next image', (video_width - 500, video_height - 120), + cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 255), 1, cv2.LINE_AA) + cv2.putText(video_image, f'r: reload config', (video_width - 500, video_height - 80), + cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 255), 1, cv2.LINE_AA) + cv2.putText(video_image, f'Ctrl+s: export ArUco markers', (video_width - 500, video_height - 40), + cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 255), 1, cv2.LINE_AA) + + # Copy image + current_image = video_image.copy() + + # Keep last image + else: + + video_image = current_image.copy() + + key_pressed = cv2.waitKey(10) + + #if key_pressed != -1: + # print(key_pressed) + + # Select previous image with left arrow + if key_pressed == 2: + next_image_index -= 1 + + # Select next image with right arrow + if key_pressed == 3: + next_image_index += 1 + + # Clip image index + if next_image_index < 0: + next_image_index = 0 + + # r: reload configuration + if key_pressed == 114: + aruco_detector = DataFeatures.from_dict(ArUcoDetector.ArUcoDetector, configuration) + refresh = True + print('Configuration reloaded') + + # Save selected marker edition using 'Ctrl + s' + if key_pressed == 19: + + if aruco_markers_group: + + aruco_markers_group.to_obj(f'{args.output}/{int(current_image_time)}-aruco_markers_group.obj') + print(f'ArUco markers saved into {args.output}') + + else: + + print(f'No ArUco markers to export') + + # Close window using 'Esc' key + if key_pressed == 27: + break + + # Display video + cv2.imshow(aruco_detector.name, video_image) + + # Close movie capture + video_capture.release() + + # Stop image display + cv2.destroyAllWindows() + + +if __name__ == '__main__': + main() -- cgit v1.1