From 9ee4f593beb3df640a6b1befe453b2e5d1f97df2 Mon Sep 17 00:00:00 2001 From: Théo de la Hogue Date: Mon, 5 Jun 2023 20:25:35 +0200 Subject: Moving documentation to Mkdocs. --- .gitignore | 2 +- README.md | 103 +------------------------ docs/api_reference.md | 4 + docs/css/mkdocstrings.css | 11 +++ docs/getting_started.md | 89 +++++++++++++++++++++ docs/index.md | 1 + docs/requirements.in | 3 + mkdocs.yml | 25 ++++++ pyproject.toml | 2 +- src/argaze/ArFeatures.py | 14 ++-- src/argaze/ArUcoMarkers/ArUcoDetector.py | 6 +- src/argaze/ArUcoMarkers/ArUcoScene.py | 28 +++---- src/argaze/ArUcoMarkers/README.md | 11 --- src/argaze/ArUcoMarkers/__init__.py | 5 +- src/argaze/ArUcoMarkers/utils/__init__.py | 5 ++ src/argaze/AreaOfInterest/AOI2DScene.py | 20 ++--- src/argaze/AreaOfInterest/AOI3DScene.py | 35 +++++---- src/argaze/AreaOfInterest/AOIFeatures.py | 56 +++++++------- src/argaze/AreaOfInterest/README.md | 5 -- src/argaze/AreaOfInterest/__init__.py | 3 +- src/argaze/DataStructures.py | 2 +- src/argaze/GazeAnalysis/Entropy.py | 6 +- src/argaze/GazeAnalysis/LempelZivComplexity.py | 2 - src/argaze/GazeAnalysis/README.md | 5 -- src/argaze/GazeAnalysis/TransitionMatrix.py | 6 +- src/argaze/GazeAnalysis/__init__.py | 3 +- src/argaze/GazeFeatures.py | 10 +-- src/argaze/PupilAnalysis/README.md | 5 -- src/argaze/PupilAnalysis/__init__.py | 2 +- src/argaze/__init__.py | 3 +- src/argaze/utils/MiscFeatures.py | 4 +- src/argaze/utils/README.md | 22 +++--- src/argaze/utils/__init__.py | 2 +- 33 files changed, 256 insertions(+), 244 deletions(-) create mode 100644 docs/api_reference.md create mode 100644 docs/css/mkdocstrings.css create mode 100644 docs/getting_started.md create mode 100644 docs/index.md create mode 100644 docs/requirements.in create mode 100644 mkdocs.yml delete mode 100644 src/argaze/ArUcoMarkers/README.md create mode 100644 src/argaze/ArUcoMarkers/utils/__init__.py delete mode 100644 src/argaze/AreaOfInterest/README.md delete mode 100644 src/argaze/GazeAnalysis/README.md delete mode 100644 src/argaze/PupilAnalysis/README.md diff --git a/.gitignore b/.gitignore index 28a4d01..cb867e1 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ _export _projects _workaround dist -doc +site calibration.json *.egg-info *.blend1 \ No newline at end of file diff --git a/README.md b/README.md index 749c6cf..6387d15 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Welcome to ArGaze's documentation + **ArGaze** is a python toolkit to deal with gaze tracking in **Augmented Reality (AR) environment**. The ArGaze toolkit provides solutions to build 3D modeled AR environment defining **Areas Of Interest (AOI)** mapped on **OpenCV ArUco markers** and so ease experimentation design with wearable eye tracker device. @@ -6,103 +8,6 @@ Further, tracked gaze can be projected onto AR environment for live or post **ga ArGaze can be combined with any wearable eye tracking device python library like Tobii or Pupil glasses. -# Architecture - -ArGaze is divided in submodules dedicated to various specifics features: - -* `argaze.ArUcoMarkers`: ArUco markers generator, detector, camera calibration, scene description, ... -* `argaze.AreaOfInterest`: Area Of Interest (AOI) scene management for 2D and 3D environment. -* `argaze.ArFeatures`: Load and manage AR environement assets. -* `argaze.GazeFeatures`: Generic gaze data and class definitions. -* `argaze.GazeAnalysis`: Various gaze analysis algorithms. -* `argaze.DataStructures`: Timestamped data features. -* `argaze.utils`: Collection of command-line high level features scripts. - -# Installation - -Consider that all inline commands below have to be executed into ArGaze root folder. - -- Install build tool package: - -``` -pip install build -``` - -- Then, build ArGaze package: - -``` -python -m build -``` - -- Then, install ArGaze package (replace VERSION by what has been built into dist folder): - -``` -pip install ./dist/argaze-VERSION.whl -``` - -.. note:: As Argaze library developper - *You should prefer to install the package in developer mode to test live code changes:* - - ``` - pip install -e . - ``` - -# Documentation - -## Wiki - -The [wiki](https://git.recherche.enac.fr/projects/argaze/wiki) provides many explanations about how works ArGaze, what is possible to do and code samples. - -## Cookbook - -The `argaze.utils` submodule is a good place to get ready made code examples. - -## Code - -ArGaze code documentation is based on [pdoc](https://pdoc.dev/). -To generate html documentation: - -- Install 'pdoc' package: - -``` -pip install pdoc -``` - -- Then, build documentation into doc folder: - -``` -pdoc -o ./doc ./src/argaze/ -``` - -.. note:: As Argaze library developper - *You should prefer to create a local html server to watch live documentation changes:* - - ``` - pdoc ./src/argaze/ - ``` - -# Test - -ArGaze package unitary tests are based on [unittest](https://docs.python.org/fr/3.10/library/unittest.html) module. -Test files tree structure is mirroring the file tree structure of src/argaze folder. - -To run all unitary tests: - -``` -python -m unittest discover ./src/argaze.test "*.py" -``` - -To run only submodule unitary tests: - -``` -python -m unittest discover ./src/argaze.test/SUBMODULE "*.py" -``` - -To run only a single unitary test file from a submodule: - -``` -python -m unittest discover ./src/argaze.test/SUBMODULE/ TEST_FILE.py -``` +Check out the [installation](getting_started#installation) section to start. -.. note:: Verbose mode - *Use -v option to get more details.* +Check out the [API reference](api_reference) section to get deeper into library architecture. diff --git a/docs/api_reference.md b/docs/api_reference.md new file mode 100644 index 0000000..5b69d1c --- /dev/null +++ b/docs/api_reference.md @@ -0,0 +1,4 @@ +API Reference +=============== + +::: argaze \ No newline at end of file diff --git a/docs/css/mkdocstrings.css b/docs/css/mkdocstrings.css new file mode 100644 index 0000000..c213aed --- /dev/null +++ b/docs/css/mkdocstrings.css @@ -0,0 +1,11 @@ +[data-md-color-scheme="slate"] { + --doc-symbol-attribute-fg-color: #963fb8; + --doc-symbol-function-fg-color: #6d67e4; + --doc-symbol-class-fg-color: #46c2cb; + --doc-symbol-module-fg-color: #f2f7a1; + + --doc-symbol-attribute-bg-color: #963fb81a; + --doc-symbol-function-bg-color: #6d67e41a; + --doc-symbol-class-bg-color: #46c2cb1a; + --doc-symbol-module-bg-color: #f2f7a11a; +} \ No newline at end of file diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..4951a25 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,89 @@ +Getting started +===== +Here are all you need to deal with ArGaze library. + +!!! note + + *Consider that all inline commands below have to be executed into ArGaze root folder.* + +Installation +------------ + +Install build tool package: + +```console +pip install build +``` + +Then, build ArGaze package: +```console +python -m build +``` + +Then, install ArGaze package (replace VERSION by what has been built into dist folder): +```console +pip install ./dist/argaze-VERSION.whl +``` + +!!! note + + **As Argaze library developper** + *You should prefer to install the package in developer mode to test live code changes:* + + ``` + pip install -e . + ``` + +Documentation +------------ + +ArGaze has a standard MkDocs layout which is built by Read the Docs. You can build and view this documentation project locally. + +Install required Python dependencies (MkDocs etc.): +```console +pip install -r docs/requirements.in +``` + +Run the mkdocs development server: +```console +mkdocs serve +``` + +Export the mkdocs site: +```console +mkdocs build +``` + +## Cookbook + +The `argaze.utils` submodule is a good place to get ready made code examples. + + +Test +------------ + +ArGaze package unitary tests are based on [unittest](https://docs.python.org/fr/3.10/library/unittest.html) module. +Test files tree structure is mirroring the file tree structure of src/argaze folder. + +To run all unitary tests: + +```shell +python -m unittest discover ./src/argaze.test "*.py" +``` + +To run only submodule unitary tests: + +```shell +python -m unittest discover ./src/argaze.test/SUBMODULE "*.py" +``` + +To run only a single unitary test file from a submodule: + +```shell +python -m unittest discover ./src/argaze.test/SUBMODULE/ TEST_FILE.py +``` + +!!! note + + **Verbose mode** + *Use -v option to get more details.* diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..563ed56 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +{!README.md!} diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000..bec300c --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,3 @@ +mkdocs +mkdocstrings[python] +markdown-include diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..c954ec8 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,25 @@ +site_name: ArGaze documentation +theme: + name: readthedocs + highlightjs: true +plugins: + - search + - mkdocstrings: + handlers: + # See: https://mkdocstrings.github.io/python/usage/ + python: + options: + docstring_style: google + allow_inspection: false + show_source: false + members_order: 'alphabetical' + heading_level: 2 + annotations_path: brief + show_submodules: true + show_root_toc_entry: false + watch: + - src/argaze +markdown_extensions: + - markdown_include.include: + base_path: . + - admonition diff --git a/pyproject.toml b/pyproject.toml index fa7093a..b0f0765 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,3 @@ [build-system] requires = ["setuptools>=42"] -build-backend = "setuptools.build_meta" \ No newline at end of file +build-backend = "setuptools.build_meta" diff --git a/src/argaze/ArFeatures.py b/src/argaze/ArFeatures.py index 2f12690..e60f792 100644 --- a/src/argaze/ArFeatures.py +++ b/src/argaze/ArFeatures.py @@ -1,6 +1,6 @@ #!/usr/bin/env python -""" """ +"""Manage AR environement assets.""" __author__ = "Théo de la Hogue" __credits__ = [] @@ -205,14 +205,14 @@ class ArScene(): return self.aoi_scene.project(tvec, rvec, K) - def estimate_pose(self, detected_markers) -> Tuple[numpy.array, numpy.array, dict]: + def estimate_pose(self, detected_markers) -> Tuple[numpy.array, numpy.array, str, dict]: """Estimate scene pose from detected ArUco markers. - * **Returns:** - - scene translation vector - - scene rotation matrix - - pose estimation strategy - - dict of markers used to estimate the pose + Returns: + scene translation vector + scene rotation matrix + pose estimation strategy + dict of markers used to estimate the pose """ # Pose estimation fails when no marker is detected diff --git a/src/argaze/ArUcoMarkers/ArUcoDetector.py b/src/argaze/ArUcoMarkers/ArUcoDetector.py index 90d1327..2f424f6 100644 --- a/src/argaze/ArUcoMarkers/ArUcoDetector.py +++ b/src/argaze/ArUcoMarkers/ArUcoDetector.py @@ -309,9 +309,9 @@ class ArUcoDetector(): @property def detection_metrics(self) -> Tuple[int, dict]: """Get marker detection metrics. - * **Returns:** - - number of detect function call - - dict with number of detection for each marker identifier""" + Returns: + number of detect function call + dict with number of detection for each marker identifier""" return self.__detection_count, Counter(self.__detected_ids) diff --git a/src/argaze/ArUcoMarkers/ArUcoScene.py b/src/argaze/ArUcoMarkers/ArUcoScene.py index fc2625d..d069df0 100644 --- a/src/argaze/ArUcoMarkers/ArUcoScene.py +++ b/src/argaze/ArUcoMarkers/ArUcoScene.py @@ -160,14 +160,14 @@ class ArUcoScene(): def from_obj(self, obj_filepath: str) -> ArUcoSceneType: """Load ArUco scene from .obj file. - .. note:: - Expected object (o) name format: #_Marker + !!! note + Expected object (o) name format: #_Marker - .. note:: - All markers have to belong to the same dictionary. + !!! note + All markers have to belong to the same dictionary. - .. note:: - Marker normal vectors (vn) expected. + !!! note + Marker normal vectors (vn) expected. """ @@ -354,9 +354,9 @@ class ArUcoScene(): def filter_markers(self, detected_markers: dict) -> Tuple[dict, dict]: """Sort markers belonging to the scene from given detected markers dict (cf ArUcoDetector.detect_markers()). - * **Returns:** - - dict of markers belonging to this scene - - dict of remaining markers not belonging to this scene + Returns: + dict of markers belonging to this scene + dict of remaining markers not belonging to this scene """ scene_markers = {} @@ -425,13 +425,13 @@ class ArUcoScene(): except: self.__translation_cache[B_identifier] = {A_identifier: AB_tvec} - def check_markers_consistency(self, scene_markers: dict, angle_tolerance: float, distance_tolerance: float) -> Tuple[dict, dict]: + def check_markers_consistency(self, scene_markers: dict, angle_tolerance: float, distance_tolerance: float) -> Tuple[dict, dict, dict]: """Evaluate if given markers configuration match related places configuration. - * **Returns:** - - dict of consistent markers - - dict of unconsistent markers - - dict of identified distance or angle unconsistencies and out-of-bounds values + Returns: + dict of consistent markers + dict of unconsistent markers + dict of identified distance or angle unconsistencies and out-of-bounds values """ consistent_markers = {} diff --git a/src/argaze/ArUcoMarkers/README.md b/src/argaze/ArUcoMarkers/README.md deleted file mode 100644 index 29ab36b..0000000 --- a/src/argaze/ArUcoMarkers/README.md +++ /dev/null @@ -1,11 +0,0 @@ -Class interface to work with [OpenCV ArUco markers](https://docs.opencv.org/4.x/d5/dae/tutorial_aruco_detection.html). - -## Wiki - -Read [ArGaze wiki page dedicated to ArUco markers](https://git.recherche.enac.fr/projects/argaze/wiki/ArUco_markers) submodule. - -## Utils - -Print **A3_DICT_ARUCO_ORIGINAL_3cm_35cmx25cm.pdf** onto A3 paper sheet to get board at expected dimensions. - -Print **A4_DICT_ARUCO_ORIGINAL_3cm_0-9.pdf** onto A4 paper sheet to get markers at expected dimensions. diff --git a/src/argaze/ArUcoMarkers/__init__.py b/src/argaze/ArUcoMarkers/__init__.py index fa769f7..ac1bee4 100644 --- a/src/argaze/ArUcoMarkers/__init__.py +++ b/src/argaze/ArUcoMarkers/__init__.py @@ -1,5 +1,4 @@ """ -.. include:: README.md +Handle [OpenCV ArUco markers](https://docs.opencv.org/4.x/d5/dae/tutorial_aruco_detection.html): generate and detect markers, calibrate camera, describe scene, ... """ -__docformat__ = "restructuredtext" -__all__ = ['ArUcoMarkersDictionary', 'ArUcoMarker', 'ArUcoBoard', 'ArUcoCamera', 'ArUcoDetector', 'ArUcoScene'] \ No newline at end of file +__all__ = ['ArUcoMarkersDictionary', 'ArUcoMarker', 'ArUcoBoard', 'ArUcoCamera', 'ArUcoDetector', 'ArUcoScene', 'utils'] \ No newline at end of file diff --git a/src/argaze/ArUcoMarkers/utils/__init__.py b/src/argaze/ArUcoMarkers/utils/__init__.py new file mode 100644 index 0000000..923f5ec --- /dev/null +++ b/src/argaze/ArUcoMarkers/utils/__init__.py @@ -0,0 +1,5 @@ +""" +Print **A3_DICT_ARUCO_ORIGINAL_3cm_35cmx25cm.pdf** onto A3 paper sheet to get board at expected dimensions. + +Print **A4_DICT_ARUCO_ORIGINAL_3cm_0-9.pdf** onto A4 paper sheet to get markers at expected dimensions. +""" \ No newline at end of file diff --git a/src/argaze/AreaOfInterest/AOI2DScene.py b/src/argaze/AreaOfInterest/AOI2DScene.py index bcf9cfa..73988b7 100644 --- a/src/argaze/AreaOfInterest/AOI2DScene.py +++ b/src/argaze/AreaOfInterest/AOI2DScene.py @@ -35,10 +35,10 @@ class AOI2DScene(AOIFeatures.AOIScene): def raycast(self, pointer:tuple) -> Tuple[str, "AOIFeatures.AreaOfInterest", bool]: """Iterate over aoi to know which aoi is matching the given pointer position. - * **Returns:** - - aoi name - - aoi object - - matching status + Returns: + aoi name + aoi object + matching status """ for name, aoi in self.items(): @@ -67,12 +67,12 @@ class AOI2DScene(AOIFeatures.AOIScene): def circlecast(self, center:tuple, radius:float) -> Tuple[str, "AOIFeatures.AreaOfInterest", numpy.array, float, float]: """Iterate over areas to know which aoi is matching circle. - * **Returns:** - - aoi name - - aoi object - - matching region points - - ratio of matching region area relatively to aoi area - - ratio of matching region area relatively to circle area + Returns: + aoi name + aoi object + matching region points + ratio of matching region area relatively to aoi area + ratio of matching region area relatively to circle area """ for name, aoi in self.items(): diff --git a/src/argaze/AreaOfInterest/AOI3DScene.py b/src/argaze/AreaOfInterest/AOI3DScene.py index ea6c04d..dbb0424 100644 --- a/src/argaze/AreaOfInterest/AOI3DScene.py +++ b/src/argaze/AreaOfInterest/AOI3DScene.py @@ -152,12 +152,13 @@ class AOI3DScene(AOIFeatures.AOIScene): def vision_cone(self, cone_radius, cone_height, cone_tip=[0., 0., 0.], cone_direction=[0., 0., 1.]) -> Tuple[AOI3DSceneType, AOI3DSceneType]: """Get AOI which are inside and out a given cone field. - .. note:: By default - The cone have its tip at origin and its base oriented to positive Z axis. + !!! note + **By default** + The cone have its tip at origin and its base oriented to positive Z axis. - * **Returns:** - - scene inside of the cone - - scene outside of the cone + Returns: + scene inside of the cone + scene outside of the cone """ # define cone tip and direction as numpy array @@ -192,17 +193,17 @@ class AOI3DScene(AOIFeatures.AOIScene): def project(self, T: numpy.array = T0, R: numpy.array = R0, K: numpy.array = K0, D: numpy.array = D0) -> AOI2DSceneType: """Project 3D scene onto 2D scene according translation, rotation and optical parameters. - * **Arguments:** - - translation vector - - rotation vector - - camera intrinsic parameters matrix - - camera distorsion coefficients vector + Parameters: + T: translation vector + R: rotation vector + K: camera intrinsic parameters matrix + D: camera distorsion coefficients vector - .. danger:: - Camera distorsion coefficients could projects points which are far from the frame into it. + !!! danger + Camera distorsion coefficients could projects points which are far from the frame into it. - .. note:: - As gaze is mainly focusing on the frame center, where the distorsion is low, it could be acceptable to not use camera distorsion. + !!! note + As gaze is mainly focusing on the frame center, where the distorsion is low, it could be acceptable to not use camera distorsion. """ aoi2D_scene = AOI2DScene.AOI2DScene() @@ -220,9 +221,9 @@ class AOI3DScene(AOIFeatures.AOIScene): def transform(self, T: numpy.array = T0, R: numpy.array = R0) -> AOI3DSceneType: """Translate and/or rotate 3D scene. - * **Arguments:** - - translation vector - - rotation matrix + Parameters: + T: translation vector + R: rotation matrix """ aoi3D_scene = AOI3DScene() diff --git a/src/argaze/AreaOfInterest/AOIFeatures.py b/src/argaze/AreaOfInterest/AOIFeatures.py index a40eaca..438e15f 100644 --- a/src/argaze/AreaOfInterest/AOIFeatures.py +++ b/src/argaze/AreaOfInterest/AOIFeatures.py @@ -72,8 +72,8 @@ class AreaOfInterest(numpy.ndarray): @property def bounding_box(self) -> numpy.array: """Get area's bounding box. - .. warning:: - Available for 2D AOI only.""" + !!! warning + Available for 2D AOI only.""" assert(self.size > 1) assert(self.dimension == 2) @@ -85,8 +85,8 @@ class AreaOfInterest(numpy.ndarray): def clockwise(self) -> AreaOfInterestType: """Get area points in clockwise order. - .. warning:: - Available for 2D AOI only.""" + !!! warning + Available for 2D AOI only.""" assert(self.dimension == 2) @@ -98,10 +98,10 @@ class AreaOfInterest(numpy.ndarray): def contains_point(self, point: tuple) -> bool: """Is a point inside area? - .. warning:: - Available for 2D AOI only. - .. danger:: - The AOI points must be sorted in clockwise order.""" + !!! warning + Available for 2D AOI only. + !!! danger + The AOI points must be sorted in clockwise order.""" assert(self.dimension == 2) assert(len(point) == self.dimension) @@ -110,10 +110,10 @@ class AreaOfInterest(numpy.ndarray): def inner_axis(self, point: tuple) -> tuple: """Transform the coordinates from the global axis to the AOI's axis. - .. warning:: - Available for 2D AOI only. - .. danger:: - The AOI points must be sorted in clockwise order.""" + !!! warning + Available for 2D AOI only. + !!! danger + The AOI points must be sorted in clockwise order.""" assert(self.dimension == 2) @@ -133,10 +133,10 @@ class AreaOfInterest(numpy.ndarray): def outter_axis(self, point: tuple) -> tuple: """Transform the coordinates from the AOI's axis to the global axis. - .. warning:: - Available for 2D AOI only. - .. danger:: - The AOI points must be sorted in clockwise order.""" + !!! warning + Available for 2D AOI only. + !!! danger + The AOI points must be sorted in clockwise order.""" assert(self.dimension == 2) @@ -156,13 +156,13 @@ class AreaOfInterest(numpy.ndarray): def circle_intersection(self, center: tuple, radius: float) -> Tuple[numpy.array, float, float]: """Get intersection shape with a circle, intersection area / AOI area ratio and intersection area / circle area ratio. - .. warning:: - Available for 2D AOI only. + !!! warning + Available for 2D AOI only. - * **Returns:** - - intersection shape, - - intersection aoi ratio, - - intersection circle ratio + Returns: + intersection shape + intersection aoi ratio + intersection circle ratio """ assert(self.dimension == 2) @@ -186,8 +186,8 @@ class AreaOfInterest(numpy.ndarray): def draw(self, frame, color, border_size=1): """Draw 2D AOI into frame. - .. warning:: - Available for 2D AOI only.""" + !!! warning + Available for 2D AOI only.""" assert(self.dimension == 2) @@ -211,8 +211,8 @@ class AOIFrame(): def __init__(self, aoi: AreaOfInterestType, size: tuple): """ - .. warning:: - Available for 2D AOI only.""" + !!! warning + Available for 2D AOI only.""" assert(aoi.dimension == 2) @@ -250,8 +250,8 @@ class AOIFrame(): def heatmap_update(self, point: tuple, sigma: float): """Update heatmap matrix. - .. danger:: - Call heatmap_init() method before any update.""" + !!! danger + Call heatmap_init() method before any update.""" point_spread = self.point_spread(point, sigma) diff --git a/src/argaze/AreaOfInterest/README.md b/src/argaze/AreaOfInterest/README.md deleted file mode 100644 index d53c189..0000000 --- a/src/argaze/AreaOfInterest/README.md +++ /dev/null @@ -1,5 +0,0 @@ -Class interface to manage Areas of Interest (AOI). - -## Wiki - -Read [ArGaze wiki page dedicated to Areas Of Interest](https://git.recherche.enac.fr/projects/argaze/wiki/Areas_Of_Interest) submodule. \ No newline at end of file diff --git a/src/argaze/AreaOfInterest/__init__.py b/src/argaze/AreaOfInterest/__init__.py index a1e9f47..a9bb2b2 100644 --- a/src/argaze/AreaOfInterest/__init__.py +++ b/src/argaze/AreaOfInterest/__init__.py @@ -1,5 +1,4 @@ """ -.. include:: README.md +Manage Areas of Interest (AOI) and scenes for 2D and 3D environment. """ -__docformat__ = "restructuredtext" __all__ = ['AOIFeatures', 'AOI2DScene', 'AOI3DScene'] \ No newline at end of file diff --git a/src/argaze/DataStructures.py b/src/argaze/DataStructures.py index 1168191..681ec72 100644 --- a/src/argaze/DataStructures.py +++ b/src/argaze/DataStructures.py @@ -1,6 +1,6 @@ #!/usr/bin/env python -""" """ +"""Timestamped data features.""" __author__ = "Théo de la Hogue" __credits__ = [] diff --git a/src/argaze/GazeAnalysis/Entropy.py b/src/argaze/GazeAnalysis/Entropy.py index 05ac5ea..861c73a 100644 --- a/src/argaze/GazeAnalysis/Entropy.py +++ b/src/argaze/GazeAnalysis/Entropy.py @@ -31,9 +31,9 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer): def analyze(self, aoi_scan_path: GazeFeatures.AOIScanPathType, transition_matrix_probabilities: pandas.DataFrame) -> Tuple[float, float]: """Analyze aoi scan path. - * **Returns:** - - stationary entropy - - transition entropy""" + Returns: + stationary entropy + transition entropy""" assert(len(aoi_scan_path) > 1) diff --git a/src/argaze/GazeAnalysis/LempelZivComplexity.py b/src/argaze/GazeAnalysis/LempelZivComplexity.py index ee73820..c449414 100644 --- a/src/argaze/GazeAnalysis/LempelZivComplexity.py +++ b/src/argaze/GazeAnalysis/LempelZivComplexity.py @@ -21,8 +21,6 @@ from lempel_ziv_complexity import lempel_ziv_complexity @dataclass class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer): - """Implementation of Lempel ziv complexity algorithm as described in Lounis paper. - """ def __post_init__(self): diff --git a/src/argaze/GazeAnalysis/README.md b/src/argaze/GazeAnalysis/README.md deleted file mode 100644 index b2582cb..0000000 --- a/src/argaze/GazeAnalysis/README.md +++ /dev/null @@ -1,5 +0,0 @@ -Various gaze movement identification and scan path analysis algorithms. - -## Wiki - -Read [ArGaze wiki page dedicated to gaze analysis](https://git.recherche.enac.fr/projects/argaze/wiki/Gaze_analysis) submodule. \ No newline at end of file diff --git a/src/argaze/GazeAnalysis/TransitionMatrix.py b/src/argaze/GazeAnalysis/TransitionMatrix.py index e92baf3..52bfa3a 100644 --- a/src/argaze/GazeAnalysis/TransitionMatrix.py +++ b/src/argaze/GazeAnalysis/TransitionMatrix.py @@ -31,9 +31,9 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer): def analyze(self, aoi_scan_path: GazeFeatures.AOIScanPathType) -> Tuple[pandas.DataFrame, float]: """Analyze aoi scan path. - * **Returns:** - - transition matrix probabilities - - transition matrix density""" + Returns: + transition matrix probabilities + transition matrix density""" assert(len(aoi_scan_path) > 1) diff --git a/src/argaze/GazeAnalysis/__init__.py b/src/argaze/GazeAnalysis/__init__.py index 5f8b102..2bdb820 100644 --- a/src/argaze/GazeAnalysis/__init__.py +++ b/src/argaze/GazeAnalysis/__init__.py @@ -1,5 +1,4 @@ """ -.. include:: README.md +Various gaze movement identification and scan path analysis algorithms. """ -__docformat__ = "restructuredtext" __all__ = ['DispersionThresholdIdentification', 'VelocityThresholdIdentification', 'TransitionMatrix', 'KCoefficient', 'LempelZivComplexity', 'NGram', 'Entropy', 'NearestNeighborIndex', 'ExploitExploreRatio'] \ No newline at end of file diff --git a/src/argaze/GazeFeatures.py b/src/argaze/GazeFeatures.py index 33b9ef8..6209dc9 100644 --- a/src/argaze/GazeFeatures.py +++ b/src/argaze/GazeFeatures.py @@ -1,6 +1,6 @@ #!/usr/bin/env python -""" """ +"""Generic gaze data and class definitions.""" __author__ = "Théo de la Hogue" __credits__ = [] @@ -437,8 +437,8 @@ class ScanPath(list): def append_fixation(self, ts, fixation): """Append new fixation to scan path. - .. warning:: - Consecutives fixations are ignored keeping the last fixation""" + !!! warning + Consecutives fixations are ignored keeping the last fixation""" self.__last_fixation = fixation @@ -610,8 +610,8 @@ class AOIScanPath(list): def append_fixation(self, ts, fixation, looked_aoi: str) -> bool: """Append new fixation to aoi scan path and return last new aoi scan step if one have been created. - .. warning:: - It could raise AOIScanStepError""" + !!! warning + It could raise AOIScanStepError""" if looked_aoi not in self.__expected_aois: diff --git a/src/argaze/PupilAnalysis/README.md b/src/argaze/PupilAnalysis/README.md deleted file mode 100644 index 3084c15..0000000 --- a/src/argaze/PupilAnalysis/README.md +++ /dev/null @@ -1,5 +0,0 @@ -Class interface to work with various gaze analysis algorithms. - -## Wiki - -Read [ArGaze wiki page dedicated to gaze analysis](https://git.recherche.enac.fr/projects/argaze/wiki/Gaze_analysis) submodule. \ No newline at end of file diff --git a/src/argaze/PupilAnalysis/__init__.py b/src/argaze/PupilAnalysis/__init__.py index ef86b05..41698b5 100644 --- a/src/argaze/PupilAnalysis/__init__.py +++ b/src/argaze/PupilAnalysis/__init__.py @@ -1,5 +1,5 @@ """ -.. include:: README.md +Class interface to work with various pupil analysis algorithms. """ __docformat__ = "restructuredtext" __all__ = ['WorkloadIndex'] \ No newline at end of file diff --git a/src/argaze/__init__.py b/src/argaze/__init__.py index 0099bfc..5b2685b 100644 --- a/src/argaze/__init__.py +++ b/src/argaze/__init__.py @@ -1,5 +1,4 @@ """ -.. include:: ../../README.md +ArGaze is divided in submodules dedicated to various specifics features. """ -__docformat__ = "restructuredtext" __all__ = ['ArUcoMarkers','AreaOfInterest','ArFeatures','GazeFeatures','GazeAnalysis','PupilFeatures','PupilAnalysis','DataStructures','utils'] \ No newline at end of file diff --git a/src/argaze/utils/MiscFeatures.py b/src/argaze/utils/MiscFeatures.py index 09c289d..a06d82f 100644 --- a/src/argaze/utils/MiscFeatures.py +++ b/src/argaze/utils/MiscFeatures.py @@ -32,8 +32,8 @@ def printProgressBar (iteration:int, total:int, prefix:str = '', suffix:str = '' def importFromTestPackage(module: str): """Import module from ArGaze test package. - * **Returns:** - - a module named Test""" + Returns: + a module named Test""" import argaze import importlib.util diff --git a/src/argaze/utils/README.md b/src/argaze/utils/README.md index 0bd5012..d5af45a 100644 --- a/src/argaze/utils/README.md +++ b/src/argaze/utils/README.md @@ -1,10 +1,10 @@ -Collection of ready-to-use commands based on ArGaze toolkit. +Collection of command-line high level features scripts. -.. note:: - *Consider that all inline commands below needs to be executed into ArGaze root folder.* +!!! note + *Consider that all inline commands below needs to be executed into ArGaze root folder.* -.. note:: - *Use -h option to get command arguments documentation.* +!!! note + *Use -h option to get command arguments documentation.* # ArUco Markers factory @@ -28,8 +28,8 @@ Calibrate a camera device (-d DEVICE) using a 7 columns and 5 rows calibration b python ./src/argaze/utils/camera_calibrate.py 7 5 5 3 DICT_APRILTAG_16h5 -d DEVICE -o ./src/argaze/utils/demo_environment ``` -.. note:: - Use **A3_DICT_APRILTAG_16h5_3cm_35cmx25cm.pdf** file located in *./src/argaze/ArUcoMarkers/utils/* folder ready to be printed on A3 paper sheet. +!!! note + Use **A3_DICT_APRILTAG_16h5_3cm_35cmx25cm.pdf** file located in *./src/argaze/ArUcoMarkers/utils/* folder ready to be printed on A3 paper sheet. # AR environment demonstration @@ -39,11 +39,11 @@ Load AR environment from **setup.json** file, detect ArUco markers into camera d python ./src/argaze/utils/demo_ar_features_run.py -d DEVICE ``` -.. note:: - This demonstration assumes that camera calibration step is done and a **calibration.json** has been exported into *./src/argaze/utils/demo_environment/* folder. +!!! note + This demonstration assumes that camera calibration step is done and a **calibration.json** has been exported into *./src/argaze/utils/demo_environment/* folder. -.. note:: - Use **A3_demo.pdf** file located in *./src/argaze/utils/demo_environment/* folder ready to be printed on A3 paper sheet. +!!! note + Use **A3_demo.pdf** file located in *./src/argaze/utils/demo_environment/* folder ready to be printed on A3 paper sheet. # Gaze features demonstration diff --git a/src/argaze/utils/__init__.py b/src/argaze/utils/__init__.py index 262a0e2..8134e6f 100644 --- a/src/argaze/utils/__init__.py +++ b/src/argaze/utils/__init__.py @@ -1,5 +1,5 @@ """ -.. include:: README.md +{!./src/argaze/utils/README.md!} """ __docformat__ = "restructuredtext" __all__ = ['MiscFeatures'] \ No newline at end of file -- cgit v1.1