From e7344955a1368c24c55fc12b2cb9ff2582278785 Mon Sep 17 00:00:00 2001 From: Théo de la Hogue Date: Mon, 22 Apr 2024 14:31:24 +0200 Subject: First work around ArContext documentation. --- docs/img/aruco_marker_pipeline.png | Bin 102120 -> 104416 bytes docs/img/pipeline_input_context.png | Bin 0 -> 49064 bytes .../configuration_and_connection.md | 35 +++++++++++++ .../pipeline_input_context/context_definition.md | 58 +++++++++++++++++++++ .../pipeline_input_context/introduction.md | 15 ++++++ docs/user_guide/utils/demonstrations_scripts.md | 12 ++--- mkdocs.yml | 4 ++ 7 files changed, 118 insertions(+), 6 deletions(-) create mode 100644 docs/img/pipeline_input_context.png create mode 100644 docs/user_guide/pipeline_input_context/configuration_and_connection.md create mode 100644 docs/user_guide/pipeline_input_context/context_definition.md create mode 100644 docs/user_guide/pipeline_input_context/introduction.md diff --git a/docs/img/aruco_marker_pipeline.png b/docs/img/aruco_marker_pipeline.png index 178da7f..c7c7b87 100644 Binary files a/docs/img/aruco_marker_pipeline.png and b/docs/img/aruco_marker_pipeline.png differ diff --git a/docs/img/pipeline_input_context.png b/docs/img/pipeline_input_context.png new file mode 100644 index 0000000..8c195ea Binary files /dev/null and b/docs/img/pipeline_input_context.png differ diff --git a/docs/user_guide/pipeline_input_context/configuration_and_connection.md b/docs/user_guide/pipeline_input_context/configuration_and_connection.md new file mode 100644 index 0000000..392860f --- /dev/null +++ b/docs/user_guide/pipeline_input_context/configuration_and_connection.md @@ -0,0 +1,35 @@ +Load and connect a context +========================== + +Once an [ArContext is defined](context_definition.md), it have to be connected to a pipeline. + +# Load JSON configuration file + +An [ArContext](../../argaze.md/#argaze.ArFeatures.ArContext) can be loaded from a JSON configuration file thanks to the argaze.load package method. + +Here is a JSON configuration file related to the [previously defined Example context](context_definition.md): + +```json +{ + "my_context.Example": { + "name": "My example context", + "parameter": ..., + "pipeline": "pipeline.json" + } +} +``` + +Then, here is how to load the JSON file: + +```python +import argaze + +# Load ArContext +with argaze.load('./configuration.json') as ar_context: + + # Do something with ArContext + ... +``` + +!!! note + There is nothing to do to execute a loaded context as it is handled inside its own **__enter__** method. diff --git a/docs/user_guide/pipeline_input_context/context_definition.md b/docs/user_guide/pipeline_input_context/context_definition.md new file mode 100644 index 0000000..9f4981c --- /dev/null +++ b/docs/user_guide/pipeline_input_context/context_definition.md @@ -0,0 +1,58 @@ +Define a context class +====================== + +The [ArContext](../../argaze.md/#argaze.ArFeatures.ArContext) class defines a generic class interface to handle pipeline inputs according to [Python context manager feature](https://docs.python.org/3/reference/datamodel.html#context-managers). + +# Write Python context file + +A specific [ArContext](../../argaze.md/#argaze.ArFeatures.ArContext) can be defined into a Python file. + +Here is an example context defined into *my_context.py* file: + +```python +from argaze import ArFeatures, DataFeatures + +class Example(ArFeatures.ArContext): + + @DataFeatures.PipelineStepInit + def __init__(self, **kwargs): + + # Init ArContext class + super().__init__() + + # Init private attribute + self.__parameter = ... + + @property + def parameter(self): + """Any required parameter.""" + return self.__parameter + + @parameter.setter + def parameter(self, parameter): + self.__parameter = parameter + + @DataFeatures.PipelineStepEnter + def __enter__(self): + + # Start context according any required parameter + ... self.parameter + + # Assuming that timestamp, x and y values are available + ... + + # Process timestamped gaze position + self._process_gaze_position(timestamp = timestamp, x = x, y = y) + + return self + + @DataFeatures.PipelineStepExit + def __exit__(self, exception_type, exception_value, exception_traceback): + + # End context + ... +``` + +!!! note "" + + The next chapter explains how to [load a context to connect it with a pipeline](configuration_and_connection.md). \ No newline at end of file diff --git a/docs/user_guide/pipeline_input_context/introduction.md b/docs/user_guide/pipeline_input_context/introduction.md new file mode 100644 index 0000000..002f1e2 --- /dev/null +++ b/docs/user_guide/pipeline_input_context/introduction.md @@ -0,0 +1,15 @@ +Overview +======== + +This section explains how to wrap any pipeline detailled in previous sections into various context. + +First, let's look at the schema below: it gives an overview of the main notions involved in the following chapters. + +![Pipeline input context](../../img/pipeline_input_context.png) + +To build your own input context, you need to know: + +* [How to define a context class](context_definition.md), +* [How to load and connect a context](configuration_and_connection.md), +* [How to visualize a context](visualization.md), +* [How to pause and resume a context](pause_and_resume.md) diff --git a/docs/user_guide/utils/demonstrations_scripts.md b/docs/user_guide/utils/demonstrations_scripts.md index 82018e3..ed2f8d9 100644 --- a/docs/user_guide/utils/demonstrations_scripts.md +++ b/docs/user_guide/utils/demonstrations_scripts.md @@ -9,20 +9,20 @@ Collection of command-line scripts for demonstration purpose. !!! note *Use -h option to get command arguments documentation.* -## OpenCV window context +## Random context -Load **opencv_window_context.json** file to analyze mouse pointer positions over OpenCV window. +Load **random_context.json** file to analyze random gaze positions. ```shell -python -m argaze ./src/argaze/utils/demo/opencv_window_context.json +python -m argaze ./src/argaze/utils/demo/random_context.json ``` -## Random context +## OpenCV window context -Load **random_context.json** file to analyze random gaze positions. +Load **opencv_window_context.json** file to analyze mouse pointer positions over OpenCV window. ```shell -python -m argaze ./src/argaze/utils/demo/random_context.json +python -m argaze ./src/argaze/utils/demo/opencv_window_context.json ``` ## Tobii Pro Glasses 2 diff --git a/mkdocs.yml b/mkdocs.yml index 50417b1..bdb8603 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,10 @@ nav: - user_guide/aruco_marker_pipeline/advanced_topics/scripting.md - user_guide/aruco_marker_pipeline/advanced_topics/optic_parameters_calibration.md - user_guide/aruco_marker_pipeline/advanced_topics/aruco_detector_configuration.md + - Pipeline Input Context: + - user_guide/pipeline_input_context/introduction.md + - user_guide/pipeline_input_context/context_definition.md + - user_guide/pipeline_input_context/configuration_and_connection.md - utils: - user_guide/utils/ready-made_scripts.md - user_guide/utils/demonstrations_scripts.md -- cgit v1.1