From 8ef66affb995c5ef23f29ad567acff33a77b0d0e Mon Sep 17 00:00:00 2001 From: Théo de la Hogue Date: Wed, 9 Aug 2023 18:42:58 +0200 Subject: Improving documentation. Managing scan path analyzer from other modules than GazeAnalysis module. Filling ArFrame background in gray by default. --- src/argaze/ArFeatures.py | 96 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 65 insertions(+), 31 deletions(-) diff --git a/src/argaze/ArFeatures.py b/src/argaze/ArFeatures.py index b4b1e39..476e413 100644 --- a/src/argaze/ArFeatures.py +++ b/src/argaze/ArFeatures.py @@ -65,14 +65,21 @@ class SceneProjectionFailed(Exception): @dataclass class ArFrame(): """ - Define Augmented Reality frame as an AOI2DScene made from a projected then reframed parent AOI3DScene. + Defines rectangular area where to project in timestamped gaze positions and inside which they need to be analyzed. Parameters: name: name of the frame - size: frame dimension in pixel. + size: defines the dimension of the rectangular area where gaze positions are projected. + aoi_2d_scene: AOI 2D scene description background: image to draw behind - aoi_2d_scene: AOI 2D scene description ... : see [orthogonal_projection][argaze.ArFeatures.ArScene.orthogonal_projection] and [reframe][argaze.AreaOfInterest.AOI2DScene.reframe] functions. - ... + gaze_movement_identifier: gaze movement identification algorithm + current_fixation_matching: enable AOI fixation matching even for in progress fixation + looked_aoi_covering_threshold: + scan_path: scan path object + scan_path_analyzers: dictionary of scan path analysis to apply on scan path + aoi_scan_path: AOI scan path object + aoi_scan_path_analyzers: dictionary of scan path analysis to apply on AOI scan path + heatmap: heatmap object """ name: str @@ -104,6 +111,12 @@ class ArFrame(): @classmethod def from_dict(self, frame_data, working_directory: str = None) -> ArFrameType: + """Load attributes from dictionary. + + Parameters: + frame_data: dictionary with attributes to load + working_directory: folder path where to load files when a dictionary value is a relative filepath. + """ # Load name try: @@ -152,16 +165,20 @@ class ArFrame(): except KeyError: - new_frame_background = numpy.zeros((new_frame_size[1], new_frame_size[0], 3)).astype(numpy.uint8) + new_frame_background = numpy.full((new_frame_size[1], new_frame_size[0], 3), 127).astype(numpy.uint8) # Load gaze movement identifier try: gaze_movement_identifier_value = frame_data.pop('gaze_movement_identifier') - gaze_movement_identifier_type, gaze_movement_identifier_parameters = gaze_movement_identifier_value.popitem() + gaze_movement_identifier_module_path, gaze_movement_identifier_parameters = gaze_movement_identifier_value.popitem() + + # Prepend argaze.GazeAnalysis path when a single name is provided + if len(gaze_movement_identifier_module_path.split('.')) == 1: + gaze_movement_identifier_module_path = f'argaze.GazeAnalysis.{gaze_movement_identifier_module_path}' - gaze_movement_identifier_module = importlib.import_module(f'argaze.GazeAnalysis.{gaze_movement_identifier_type}') + gaze_movement_identifier_module = importlib.import_module(gaze_movement_identifier_module_path) new_gaze_movement_identifier = gaze_movement_identifier_module.GazeMovementIdentifier(**gaze_movement_identifier_parameters) except KeyError: @@ -204,9 +221,15 @@ class ArFrame(): new_scan_path_analyzers_value = frame_data.pop('scan_path_analyzers') - for scan_path_analyzer_type, scan_path_analyzer_parameters in new_scan_path_analyzers_value.items(): + for scan_path_analyzer_module_path, scan_path_analyzer_parameters in new_scan_path_analyzers_value.items(): - scan_path_analyzer_module = importlib.import_module(f'argaze.GazeAnalysis.{scan_path_analyzer_type}') + print(scan_path_analyzer_module_path) + + # Prepend argaze.GazeAnalysis path when a single name is provided + if len(scan_path_analyzer_module_path.split('.')) == 1: + scan_path_analyzer_module_path = f'argaze.GazeAnalysis.{scan_path_analyzer_module_path}' + + scan_path_analyzer_module = importlib.import_module(scan_path_analyzer_module_path) # Check scan path analyzer parameters type members = getmembers(scan_path_analyzer_module.ScanPathAnalyzer) @@ -231,11 +254,11 @@ class ArFrame(): except KeyError: - raise EnvironmentJSONLoadingFailed(f'{scan_path_analyzer_type} scan path analyzer loading fails because {parameter_module_path[2]} scan path analyzer is missing.') + raise EnvironmentJSONLoadingFailed(f'{scan_path_analyzer_module_path} scan path analyzer loading fails because {parameter_module_path[2]} scan path analyzer is missing.') scan_path_analyzer = scan_path_analyzer_module.ScanPathAnalyzer(**scan_path_analyzer_parameters) - new_scan_path_analyzers[scan_path_analyzer_type] = scan_path_analyzer + new_scan_path_analyzers[scan_path_analyzer_module_path] = scan_path_analyzer # Force scan path creation if len(new_scan_path_analyzers) > 0 and new_scan_path == None: @@ -266,9 +289,13 @@ class ArFrame(): new_aoi_scan_path_analyzers_value = frame_data.pop('aoi_scan_path_analyzers') - for aoi_scan_path_analyzer_type, aoi_scan_path_analyzer_parameters in new_aoi_scan_path_analyzers_value.items(): + for aoi_scan_path_analyzer_module_path, aoi_scan_path_analyzer_parameters in new_aoi_scan_path_analyzers_value.items(): + + # Prepend argaze.GazeAnalysis path when a single name is provided + if len(aoi_scan_path_analyzer_module_path.split('.')) == 1: + aoi_scan_path_analyzer_module_path = f'argaze.GazeAnalysis.{aoi_scan_path_analyzer_module_path}' - aoi_scan_path_analyzer_module = importlib.import_module(f'argaze.GazeAnalysis.{aoi_scan_path_analyzer_type}') + aoi_scan_path_analyzer_module = importlib.import_module(aoi_scan_path_analyzer_module_path) # Check aoi scan path analyzer parameters type members = getmembers(aoi_scan_path_analyzer_module.AOIScanPathAnalyzer) @@ -293,11 +320,11 @@ class ArFrame(): except KeyError: - raise EnvironmentJSONLoadingFailed(f'{aoi_scan_path_analyzer_type} aoi scan path analyzer loading fails because {parameter_module_path[2]} aoi scan path analyzer is missing.') + raise EnvironmentJSONLoadingFailed(f'{aoi_scan_path_analyzer_module_path} aoi scan path analyzer loading fails because {parameter_module_path[2]} aoi scan path analyzer is missing.') aoi_scan_path_analyzer = aoi_scan_path_analyzer_module.AOIScanPathAnalyzer(**aoi_scan_path_analyzer_parameters) - new_aoi_scan_path_analyzers[aoi_scan_path_analyzer_type] = aoi_scan_path_analyzer + new_aoi_scan_path_analyzers[aoi_scan_path_analyzer_module_path] = aoi_scan_path_analyzer # Force AOI scan path creation if len(new_aoi_scan_path_analyzers) > 0 and new_aoi_scan_path == None: @@ -343,7 +370,7 @@ class ArFrame(): @classmethod def from_json(self, json_filepath: str) -> ArEnvironmentType: """ - Load ArFrame from .json file. + Load attributes from .json file. Parameters: json_filepath: path to json file @@ -452,15 +479,22 @@ class ArFrame(): # Update looked aoi covering mean self.__looked_aoi_covering_mean = int(100 * max_covering / self.__look_count) / 100 - def look(self, timestamp: int|float, inner_gaze_position: GazeFeatures.GazePosition = GazeFeatures.UnvalidGazePosition(), identified_gaze_movement: GazeFeatures.GazeMovement = GazeFeatures.UnvalidGazeMovement()) -> Tuple[GazeFeatures.GazeMovement, dict, dict, dict]: - """ - - GazeFeatures.AOIScanStepError + def look(self, timestamp: int|float, gaze_position: GazeFeatures.GazePosition = GazeFeatures.UnvalidGazePosition(), identified_gaze_movement: GazeFeatures.GazeMovement = GazeFeatures.UnvalidGazeMovement()) -> Tuple[GazeFeatures.GazeMovement, dict, dict, dict]: + """ + Project gaze position into frame. + + !!! warning + Be aware that gaze positions are in the same range of value than size attribute. + + Parameters: + timestamp: + gaze_position: gaze position to project + identified_gaze_movement: pass identified gaze movement instead of timestamped gaze position to avoid double identification process. Returns: - temp_gaze_movement: identified gaze movement (if gaze_movement_identifier is instanciated) or current gaze movement (if current_fixation_matching is True) - scan_step: new scan step (if scan_path is instanciated) - aoi_scan_step: new scan step (if aoi_scan_path is instanciated) + identified_gaze_movement: identified gaze movement from incoming consecutive timestamped gaze positions if gaze_movement_identifier is instanciated. Current gaze movement if current_fixation_matching is True. + scan_path_analysis: scan path analysis at each new scan step if scan_path is instanciated + aoi_scan_path_analysis: new scan step at each new aoi scan step if aoi_scan_path is instanciated exception: error catched during gaze position processing """ @@ -468,7 +502,7 @@ class ArFrame(): self.__look_lock.acquire() # Update current gaze position - self.__gaze_position = inner_gaze_position + self.__gaze_position = gaze_position # No gaze movement identified by default temp_gaze_movement = GazeFeatures.UnvalidGazeMovement() @@ -535,7 +569,7 @@ class ArFrame(): # Is there a new step? if aoi_scan_step and len(self.aoi_scan_path) > 1: - for aoi_scan_path_analyzer_type, aoi_scan_path_analyzer in self.aoi_scan_path_analyzers.items(): + for aoi_scan_path_analyzer_module_path, aoi_scan_path_analyzer in self.aoi_scan_path_analyzers.items(): # Store aoi scan step analysis start date aoi_scan_step_analysis_start = time.perf_counter() @@ -544,10 +578,10 @@ class ArFrame(): aoi_scan_path_analyzer.analyze(self.aoi_scan_path) # Assess aoi scan step analysis time in ms - times['aoi_scan_step_analyzers'][aoi_scan_path_analyzer_type] = (time.perf_counter() - aoi_scan_step_analysis_start) * 1e3 + times['aoi_scan_step_analyzers'][aoi_scan_path_analyzer_module_path] = (time.perf_counter() - aoi_scan_step_analysis_start) * 1e3 # Store analysis - aoi_scan_step_analysis[aoi_scan_path_analyzer_type] = aoi_scan_path_analyzer.analysis + aoi_scan_step_analysis[aoi_scan_path_analyzer_module_path] = aoi_scan_path_analyzer.analysis elif GazeFeatures.is_saccade(temp_gaze_movement): @@ -562,7 +596,7 @@ class ArFrame(): # Is there a new step? if scan_step and len(self.scan_path) > 1: - for scan_path_analyzer_type, scan_path_analyzer in self.scan_path_analyzers.items(): + for scan_path_analyzer_module_path, scan_path_analyzer in self.scan_path_analyzers.items(): # Store scan step analysis start date scan_step_analysis_start = time.perf_counter() @@ -571,10 +605,10 @@ class ArFrame(): scan_path_analyzer.analyze(self.scan_path) # Assess scan step analysis time in ms - times['scan_step_analyzers'][scan_path_analyzer_type] = (time.perf_counter() - scan_step_analysis_start) * 1e3 + times['scan_step_analyzers'][scan_path_analyzer_module_path] = (time.perf_counter() - scan_step_analysis_start) * 1e3 # Store analysis - scan_step_analysis[scan_path_analyzer_type] = scan_path_analyzer.analysis + scan_step_analysis[scan_path_analyzer_module_path] = scan_path_analyzer.analysis # Append saccade to aoi scan path if self.aoi_scan_path != None: @@ -1280,7 +1314,7 @@ class ArEnvironment(): def look(self, timestamp: int|float, gaze_position: GazeFeatures.GazePosition): """Project timestamped gaze position into each frame. - .. warning:: detect_and_project method needs to be called first. + !!! warning detect_and_project method needs to be called first. """ # Can't use camera frame when it is locked -- cgit v1.1