gazeMapper 0.5.0__tar.gz

gazemapper-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Diederick Niehorster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gazemapper-0.5.0/MANIFEST.in

@@ -0,0 +1 @@
+include requirements.txt

gazemapper-0.5.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: gazeMapper
+Version: 0.5.0
+Summary: Automated world-based analysis of wearable eye tracker data.
+Home-page: https://github.com/dcnieho/gazeMapper
+Author: Diederick Niehorster
+Author-email: diederick_c.niehorster@humlab.lu.se
+License: MIT License
+        
+        Copyright (c) 2024 Diederick Niehorster
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Source Code, https://github.com/dcnieho/gazeMapper
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: glassesTools[GUI]==1.4.0
+Requires-Dist: glassesValidator==2.0.0
+
+[![Downloads](https://static.pepy.tech/badge/gazeMapper)](https://pepy.tech/project/gazeMapper)
+[![Citation Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.juleskreuer.eu%2Fcitation-badge.php%3Fshield%26doi%3D10.3758%2Fs13428-023-02105-5&color=blue)](https://scholar.google.com/citations?view_op=view_citation&citation_for_view=uRUYoVgAAAAJ:uWQEDVKXjbEC)
+[![PyPI Latest Release](https://img.shields.io/pypi/v/gazeMapper.svg)](https://pypi.org/project/gazeMapper/)
+[![image](https://img.shields.io/pypi/pyversions/gazeMapper.svg)](https://pypi.org/project/gazeMapper/)
+
+# gazeMapper v0.5.0
+Tool for automated world-based analysis of wearable eye tracker data.
+
+If you use this tool or any of the code in this repository, please cite:<br>
+Niehorster, D.C., Hessels, R.S., Nyström, M., Benjamins, J.S. and Hooge, I.T.C. (in prep). gazeMapper: A tool for automated world-based analysis of wearable eye tracker data
+
+# How to acquire
+GlassesValidator is available from `https://github.com/dcnieho/gazeMapper`, and supports Python 3.10 and 3.11 on Windows, MacOS and Linux.
+
+For Windows users who wish to use the gazeMapper GUI, the easiest way to acquire gazeMapper is to [download
+a standalone executable](https://github.com/dcnieho/gazeMapper/releases/latest). The standalone executable is not
+available for MacOS or Linux.
+
+For users on Windows, Mac or Linux who wish to use gazeMapper in their Python code, the easiest way to acquire
+gazeMapper is to install it directly into your Python distribution using the command
+`python -m pip install gazeMapper`. Should that fail, this repository is pip-installable as well:
+`python -m pip install git+https://github.com/dcnieho/gazeMapper.git#egg=gazeMapper`. NB: on some platforms you may have
+to replace `python` with `python3` in the above command lines.
+
+Once pip-installed in your Python distribution, there are three ways to run the GUI on any of the supported operating systems:
+1. Directly in the terminal of your operating system, type `gazeMapper` and run it.
+2. Open a Python console. From such a console, running the GUI requires only the following two lines of code:
+    ```python
+    import gazeMapper
+    gazeMapper.GUI.run()
+    ```
+3. If you run the gazeMapper's GUI from a script, make sure to wrap your script in `if __name__=="__main__"`. This is required for correct operation from a script because the GUI uses multiprocessing functionality. Do as follows:
+    ```python
+    if __name__=="__main__":
+        import gazeMapper
+        gazeMapper.GUI.run()
+    ```

gazemapper-0.5.0/README.md

@@ -0,0 +1,37 @@
+[![Downloads](https://static.pepy.tech/badge/gazeMapper)](https://pepy.tech/project/gazeMapper)
+[![Citation Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.juleskreuer.eu%2Fcitation-badge.php%3Fshield%26doi%3D10.3758%2Fs13428-023-02105-5&color=blue)](https://scholar.google.com/citations?view_op=view_citation&citation_for_view=uRUYoVgAAAAJ:uWQEDVKXjbEC)
+[![PyPI Latest Release](https://img.shields.io/pypi/v/gazeMapper.svg)](https://pypi.org/project/gazeMapper/)
+[![image](https://img.shields.io/pypi/pyversions/gazeMapper.svg)](https://pypi.org/project/gazeMapper/)
+
+# gazeMapper v0.5.0
+Tool for automated world-based analysis of wearable eye tracker data.
+
+If you use this tool or any of the code in this repository, please cite:<br>
+Niehorster, D.C., Hessels, R.S., Nyström, M., Benjamins, J.S. and Hooge, I.T.C. (in prep). gazeMapper: A tool for automated world-based analysis of wearable eye tracker data
+
+# How to acquire
+GlassesValidator is available from `https://github.com/dcnieho/gazeMapper`, and supports Python 3.10 and 3.11 on Windows, MacOS and Linux.
+
+For Windows users who wish to use the gazeMapper GUI, the easiest way to acquire gazeMapper is to [download
+a standalone executable](https://github.com/dcnieho/gazeMapper/releases/latest). The standalone executable is not
+available for MacOS or Linux.
+
+For users on Windows, Mac or Linux who wish to use gazeMapper in their Python code, the easiest way to acquire
+gazeMapper is to install it directly into your Python distribution using the command
+`python -m pip install gazeMapper`. Should that fail, this repository is pip-installable as well:
+`python -m pip install git+https://github.com/dcnieho/gazeMapper.git#egg=gazeMapper`. NB: on some platforms you may have
+to replace `python` with `python3` in the above command lines.
+
+Once pip-installed in your Python distribution, there are three ways to run the GUI on any of the supported operating systems:
+1. Directly in the terminal of your operating system, type `gazeMapper` and run it.
+2. Open a Python console. From such a console, running the GUI requires only the following two lines of code:
+    ```python
+    import gazeMapper
+    gazeMapper.GUI.run()
+    ```
+3. If you run the gazeMapper's GUI from a script, make sure to wrap your script in `if __name__=="__main__"`. This is required for correct operation from a script because the GUI uses multiprocessing functionality. Do as follows:
+    ```python
+    if __name__=="__main__":
+        import gazeMapper
+        gazeMapper.GUI.run()
+    ```

gazemapper-0.5.0/pyproject.toml

@@ -0,0 +1,6 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"

gazemapper-0.5.0/requirements.txt

@@ -0,0 +1,2 @@
+glassesTools[GUI]==1.4.0    # pulls in various other dependencies such as opencv, imgui_bundle, numpy, pandas
+glassesValidator==2.0.0

gazemapper-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gazemapper-0.5.0/setup.py

@@ -0,0 +1,50 @@
+import setuptools
+import runpy
+
+info = runpy.run_path("src/gazeMapper/version.py")
+
+with open('README.md') as f:
+    readme = f.read()
+
+with open('LICENSE') as f:
+    license = f.read()
+
+with open('requirements.txt') as f:
+    requirements = f.read().splitlines()
+
+required = []
+
+# get required packages
+for line in requirements:
+    required.append(line)
+
+setuptools.setup(
+    name=info['__title__'],
+    version=info['__version__'],
+    author=info['__author__'],
+    author_email=info['__email__'],
+    description=info['__description__'],
+    long_description=readme,
+    long_description_content_type="text/markdown",
+    url=info['__url__'],
+    project_urls={
+        "Source Code": info['__url__'],
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    license=license,
+    package_dir={"": "src"},
+    packages=setuptools.find_packages(where="src"),
+    include_package_data=True,
+    python_requires=">=3.10",
+    install_requires=required,
+    # entry_points={
+    #     "gui_scripts": [
+    #         "gazeMapper = gazeMapper.GUI:run",
+    #     ],
+    # },
+)

gazemapper-0.5.0/src/gazeMapper/camera_recording.py

@@ -0,0 +1,79 @@
+import dataclasses
+import pathlib
+import typing
+import shutil
+import json
+
+from glassesTools import utils, video_utils
+
+
+@dataclasses.dataclass
+class Recording:
+    default_json_file_name      : typing.ClassVar[str] = 'recording_info.json'
+
+    name                        : str
+    video_file                  : str
+    source_directory            : pathlib.Path
+    working_directory           : pathlib.Path  = ""
+    duration                    : int           = None
+
+    def store_as_json(self, path: str | pathlib.Path):
+        path = pathlib.Path(path)
+        if path.is_dir():
+            path /= self.default_json_file_name
+        with open(path, 'w') as f:
+            # remove any crap potentially added by subclasses
+            to_dump = dataclasses.asdict(self)
+            to_dump = {k:to_dump[k] for k in to_dump if k in Recording.__annotations__}
+            # dump to file
+            json.dump(to_dump, f, cls=utils.CustomTypeEncoder, indent=2)
+
+    @staticmethod
+    def load_from_json(path: str | pathlib.Path):
+        path = pathlib.Path(path)
+        if path.is_dir():
+            path /= Recording.default_json_file_name
+        with open(path, 'r') as f:
+            return Recording(**json.load(f, object_hook=utils.json_reconstitute))
+
+
+    def get_video_path(self):
+        vid = self.working_directory / self.video_file
+        if not vid.is_file():
+            vid = self.source_directory / self.video_file
+        return vid
+
+
+
+def do_import(rec_info: Recording, cam_cal_file: str|pathlib.Path=None, copy_video=True):
+    assert rec_info.working_directory
+    rec_info.working_directory = pathlib.Path(rec_info.working_directory)
+    ifile = (rec_info.source_directory / rec_info.video_file)
+    assert ifile.is_file()
+    print(f'processing: {rec_info.video_file} -> {rec_info.working_directory}')
+
+    if not rec_info.working_directory.is_dir():
+        rec_info.working_directory.mkdir()
+
+    if copy_video:
+        ofile = rec_info.working_directory / rec_info.video_file
+        print('  Copy video file...')
+        shutil.copy2(ifile, ofile)
+
+    # also get its calibration
+    print('  Getting camera calibration...')
+    if cam_cal_file is not None:
+        shutil.copy2(str(cam_cal_file), str(rec_info.working_directory / 'calibration.xml'))
+    else:
+        print('  !! No camera calibration provided! Defaulting to hardcoded')
+
+    # and frame timestamps
+    print('  Getting frame timestamps...')
+    ts = video_utils.getFrameTimestampsFromVideo(rec_info.get_video_path())
+    ts.to_csv(str(rec_info.working_directory / 'frameTimestamps.tsv'), sep='\t')
+    rec_info.duration = (ts.timestamp.iat[-1]-ts.timestamp.iat[0])/1000.    # ms -> s
+
+    # store recording info to folder
+    rec_info.store_as_json(rec_info.working_directory)
+
+    return rec_info

gazemapper-0.5.0/src/gazeMapper/config.py

@@ -0,0 +1,82 @@
+import pathlib
+import json
+from typing import Any
+
+from glassesTools import utils
+
+from . import episode, plane, session
+
+
+class Marker:
+    def __init__(self, id:int, size:float):
+        self.id     = id
+        self.size   = size
+utils.register_type(utils.CustomTypeEntry(Marker,'__config.Marker__',lambda x: {'id': x.id, 'size': x.size}, lambda x: Marker(**x)))
+
+def get_marker_dict_from_list(markers: list[Marker]) -> dict[int,dict[str,Any]]:
+    out = {}
+    for m in markers:
+        out[m.id] = {'marker_size': m.size}
+    return out
+
+class Study:
+    default_json_file_name = 'study_def.json'
+
+    def __init__(self, session_def: session.SessionDefinition, planes: list[plane.Definition], planes_per_interval: dict[episode.Event,list[str]], individual_markers: list[Marker], working_directory: str|pathlib.Path):
+        self.session_def        = session_def
+        self.planes             = planes
+        self.planes_per_interval= planes_per_interval
+        self.working_directory  = working_directory
+        self.individual_markers = individual_markers
+
+        self._check_planes_per_interval()
+
+    def _check_planes_per_interval(self):
+        for e in self.planes_per_interval:
+            for p in self.planes_per_interval[e]:
+                if not any([p==pl.name for pl in self.planes]):
+                    raise ValueError(f'plane {p} not known')
+
+    def store_as_json(self, path: str | pathlib.Path):
+        path = pathlib.Path(path)
+        # this stores only the planes_per_interval variable to json, rest is read from other files
+        # instead to remain flexible and make it easy for users to rename, etc
+        d_path = path / self.default_json_file_name
+        with open(d_path, 'w') as f:
+            to_dump = {k:getattr(self,k) for k in ['planes_per_interval','individual_markers']}    # only these fields. Name will be populated from name of session/provided folder, recordings from each subfolder in the session/provided folder, and working_directory as the provided path
+            to_dump['planes_per_interval'] = [(k, to_dump['planes_per_interval'][k]) for k in to_dump['planes_per_interval']]   # pack as list of tuples for storage
+            # dump to file
+            json.dump(to_dump, f, cls=utils.CustomTypeEncoder, indent=2)
+        # this doesn't story any files itself, but triggers the contained info to be stored
+        self.session_def.store_as_json(self.working_directory / 'session_def.json')
+        for p in self.planes:
+            p_dir = self.working_directory / p.name
+            if not p_dir.is_dir():
+                p_dir.mkdir()
+            p.store_as_json(p_dir)
+
+    @staticmethod
+    def load_from_json(path: str | pathlib.Path) -> 'Study':
+        path = pathlib.Path(path)
+        # get kwds
+        d_path = path / Study.default_json_file_name
+        with open(d_path, 'r') as f:
+            kwds = json.load(f, object_hook=utils.json_reconstitute)
+        kwds['planes_per_interval'] = {k:v for k,v in kwds['planes_per_interval']}  # stored as list of tuples, unpack
+        # get session def
+        s_path = path / 'session_def.json'
+        if not s_path.is_file():
+            return None
+        sess_def = session.SessionDefinition.load_from_json(s_path)
+
+        # get planes
+        planes: list[plane.Definition] = []
+        for p_dir in path.iterdir():
+            if not p_dir.is_dir():
+                continue
+            p_file = p_dir / plane.Definition.default_json_file_name
+            if not p_file.is_file():
+                continue
+            planes.append(plane.Definition.load_from_json(p_file))
+
+        return Study(sess_def, planes, working_directory=path, **kwds)

gazemapper-0.5.0/src/gazeMapper/episode.py

@@ -0,0 +1,106 @@
+from enum import Enum, auto
+import pathlib
+import pandas as pd
+from collections import defaultdict
+
+from glassesTools import utils
+
+
+
+class Type(Enum):
+    Point       = auto()
+    Interval    = auto()
+
+
+class Event(utils.AutoName):
+    Validate    = auto()    # interval to be used for running glassesValidator
+    Sync_Camera = auto()    # point to be used for synchronizing different cameras
+    Sync_VOR    = auto()    # episode to be used for VOR synchronization
+    Map         = auto()    # episode for which to map gaze to plane(s): output for files to be provided to user
+events = [x.value for x in Event]
+utils.register_type(utils.CustomTypeEntry(Event,'__enum.Event__',str, lambda x: getattr(Event, x.split('.')[1])))
+
+type_map = {
+    Event.Validate    : Type.Interval,
+    Event.Sync_Camera : Type.Point,
+    Event.Sync_VOR    : Type.Interval,
+    Event.Map         : Type.Interval,
+}
+
+
+class Episode:
+    def __init__(self, event:Event, start_frame:int, end_frame:int=None):
+        self.event          = event
+        self.start_frame    = start_frame
+
+        if type_map[event]==Type.Interval:
+            assert end_frame is not None, f"end frame expected for an interval-type episode ({event.value}), but not provided"
+        if type_map[event]==Type.Point:
+            assert end_frame is None, f"end frame provided but not expected for a point-type episode ({event.value})"
+        self.end_frame      = end_frame
+
+
+# for dealing with lists of events
+def read_list_from_file(fileName: str|pathlib.Path) -> list[Episode]:
+    df = pd.read_csv(str(fileName), delimiter='\t', index_col=False, dtype=defaultdict(lambda: int, event=str, end_frame=pd.Int64Dtype()))
+    df['event']     = [Event(x) for x in df['event'].values]
+    df['end_frame'] = df['end_frame'].astype('object')
+    df.loc[pd.isnull(df['end_frame']),'end_frame'] = None   # set missing to None
+    return [Episode(**kwargs) for kwargs in df.to_dict(orient='records')]
+
+def write_list_to_file(episodes: list[Episode],
+                       fileName: str|pathlib.Path):
+    if not episodes:
+        return
+
+    records = [{k:getattr(p,k) for k in vars(p) if not k.startswith('_')} for p in episodes]
+    df = pd.DataFrame.from_records(records)
+    df['event'] = [x.value for x in df['event'].values]
+
+    # keep only columns to be written out and order them correctly
+    df = df[['event','start_frame','end_frame']]
+    df.to_csv(str(fileName), index=False, sep='\t', na_rep='nan')
+
+
+def get_empty_marker_dict() -> dict[Event,list[int]]:
+    return {e:[] for e in Event}
+
+def list_to_marker_dict(episodes: list[Episode]) -> dict[Event,list[list[int]]]:
+    e_dict = get_empty_marker_dict()
+    for e in episodes:
+        if e.end_frame is not None:
+            e_dict[e.event].append([e.start_frame, e.end_frame])
+        else:
+            e_dict[e.event].append([e.start_frame])
+    return e_dict
+
+def marker_dict_to_list(episodes: dict[Event,list[int]]|dict[Event,list[list[int]]]) -> list[Episode]:
+    e_list: list[Episode] = []
+    for e in episodes:
+        if not episodes[e]:
+            continue
+        if isinstance(episodes[e][0],list):
+            e_list.extend([Episode(e, *v) for v in episodes[e]])
+        else:
+            if type_map[e]==Type.Interval:
+                for m in range(0,len(episodes[e])-1,2): # read in batches of two, and run until -1 to make sure we don't pick up incomplete intervals
+                    e_list.append(Episode(e, *episodes[e][m:m+2]))
+            else:
+                e_list.extend([Episode(e,m) for m in episodes[e]])
+
+    return sorted(e_list, key=lambda x: x.start_frame)
+
+
+def is_in_interval(episodes: dict[Event,list[int]]|list[Episode], idx: int) -> dict[Event, bool]:
+    if isinstance(episodes,dict):
+        episodes = marker_dict_to_list(episodes)
+
+    e_dict: dict[Event,bool] = {e:False for e in Event}
+    for e in episodes:
+        if type_map[e.event]==Type.Interval:
+            if idx>=e.start_frame and idx<=e.end_frame:
+                e_dict[e.event] = True
+        else:
+            if idx==e.start_frame:
+                e_dict[e.event] = True
+    return e_dict

gazemapper-0.5.0/src/gazeMapper/plane.py

@@ -0,0 +1,109 @@
+from enum import auto
+import pathlib
+import cv2
+import json
+import numpy as np
+
+from glassesTools import plane, utils
+from glassesValidator.config import get_validation_setup
+from glassesValidator.config.poster import Poster
+
+
+class Type(utils.AutoName):
+    GlassesValidator= auto()
+    Plane_2D        = auto()
+utils.register_type(utils.CustomTypeEntry(Type,'__enum.plane.Type__',str, lambda x: getattr(Type, x.split('.')[1])))
+
+
+class Definition:
+    default_json_file_name = 'plane_def.json'
+
+    def __init__(self, type:Type, name:str=None, use_default:bool=False, marker_file: str|pathlib.Path=None, marker_size: float=None, marker_border_bits: int=1, min_num_markers: int=3, center: np.ndarray=None, unit: str=None, aruco_dict: int=cv2.aruco.DICT_4X4_250, ref_image_width: int=1920):
+        self.type                                       = type
+        self.name                                       = name
+        self.use_default            : bool              = use_default           # applies only to glassesValidator planes. If False, denotes this is the default/built-in glassesValidator plane, if True, denotes custom settings are expected
+        # the below are only for non-glassesValidator planes
+        self.marker_file            : str|pathlib.Path  = marker_file           # if str or Path: file from which to read markers. Else direction N_markerx4 array. Should contain centers of markers
+        self.marker_size            : float             = marker_size           # in "unit" units
+        self.marker_border_bits     : int               = marker_border_bits
+        self.min_num_markers        : int               = min_num_markers       # minimum number of markers that should be to run pose estimation w.r.t. the plane
+        self.center                 : np.ndarray        = center                # center of plane, in coordinates of the input file
+        self.unit                   : str               = unit
+        self.aruco_dict             : int               = aruco_dict
+        self.ref_image_width        : int               = ref_image_width
+
+        if isinstance(self.center,list):
+            self.center = np.array(self.center)
+
+        # check provided info
+        if self.type==Type.GlassesValidator:
+            # prevent bugs
+            assert self.marker_file is None, "The marker_file input argument should not be set when the plane is a GlassesValidator plane (would be ignored)"
+            assert self.marker_size is None, "The marker_size input argument should not be set when the plane is a GlassesValidator plane (would be ignored)"
+            # NB: all the other parameters are also ignored, but have meaningful defaults, so can't be checked
+        else:
+            assert self.marker_file is not None, "The marker_file input argument should be provided"
+            assert self.marker_size is not None, "The marker_size input argument should be provided"
+            # prevent bugs
+            assert self.use_default is False, "The use_default input argument is for GlassesValidator planes. It should be set to False (default) when the plane is not a GlassesValidator plane (would be ignored)"
+
+    def store_as_json(self, path: str | pathlib.Path):
+        path = pathlib.Path(path)
+        if path.is_dir():
+            path /= self.default_json_file_name
+        with open(path, 'w') as f:
+            json.dump(self, f, cls=utils.CustomTypeEncoder, indent=2)
+
+    @staticmethod
+    def load_from_json(path: str | pathlib.Path) -> 'Definition':
+        path = pathlib.Path(path)
+        if path.is_dir():
+            path /= Definition.default_json_file_name
+        with open(path, 'r') as f:
+            dfntn = json.load(f, object_hook=utils.json_reconstitute)
+        dfntn.name=path.parent.name
+        return dfntn
+
+    def _to_dict(self):
+        return {
+            'type': self.type,
+            'use_default': self.use_default,
+            'marker_file': self.marker_file,
+            'marker_size': self.marker_size,
+            'marker_border_bits': self.marker_border_bits,
+            'min_num_markers': self.min_num_markers,
+            'center': self.center,
+            'unit': self.unit,
+            'aruco_dict': self.aruco_dict,
+            'ref_image_width': self.ref_image_width
+        }
+utils.register_type(utils.CustomTypeEntry(Definition,'__plane.Definition',lambda x: x._to_dict(), lambda x: Definition(**x)))
+
+
+def get_plane_from_path(path: str|pathlib.Path) -> plane.Plane:
+    path = pathlib.Path(path)
+    plane_def = Definition.load_from_json(path)
+    return get_plane_from_definition(plane_def, path)
+
+def get_plane_from_definition(plane_def: Definition, path: str | pathlib.Path) -> plane.Plane:
+    # for loading a plane from a directory that doesn't contain a plane definition json file
+    # use the provided definition instead
+    if plane_def.type==Type.GlassesValidator:
+        validator_config_dir = None # use glassesValidator built-in/default
+        if not plane_def.use_default:
+            validator_config_dir = path
+        validation_setup = get_validation_setup(validator_config_dir)
+        return Poster(validator_config_dir, validation_setup, ref_image_store_path=path / plane.Plane.default_ref_image_name)
+    else:
+        pl = plane.Plane(
+            markers             = path / plane_def.marker_file,
+            marker_size         = plane_def.marker_size,
+            aruco_dict          = plane_def.aruco_dict,
+            marker_border_bits  = plane_def.marker_border_bits,
+            unit                = plane_def.unit,
+            ref_image_store_path= path / plane.Plane.default_ref_image_name,
+            ref_image_width     = plane_def.ref_image_width
+        )
+        if plane_def.center is not None:
+            pl.set_center(plane_def.center)
+        return pl

gazemapper-0.5.0/src/gazeMapper/session.py

@@ -0,0 +1,193 @@
+from enum import Enum, auto
+import pathlib
+import json
+
+from glassesTools import importing, utils
+from glassesTools.recording import Recording as EyeTrackerRecording
+
+from . import camera_recording
+
+
+class RecordingType(Enum):
+    EyeTracker  = auto()
+    Camera      = auto()
+utils.register_type(utils.CustomTypeEntry(RecordingType,'__enum.session.RecordingType__',str, lambda x: getattr(RecordingType, x.split('.')[1])))
+
+
+
+class RecordingDefinition:
+    def __init__(self, name:str, type:RecordingType):
+        self.name = name
+        self.type = type
+utils.register_type(utils.CustomTypeEntry(RecordingDefinition,'__session.RecordingDefinition__',lambda x: {'name': x.name, 'type': x.type}, lambda x: RecordingDefinition(**x)))
+
+
+class Recording:
+    def __init__(self, defition: RecordingDefinition, info:EyeTrackerRecording|camera_recording.Recording=None):
+        self.defition   = defition
+        self.info       = info
+utils.register_type(utils.CustomTypeEntry(Recording,'__session.Recording__',lambda x: {'defition': x.defition, 'info': x.info}, lambda x: Recording(**x)))
+
+def read_recording_info(working_dir: pathlib.Path, rec_type: RecordingType) -> tuple[EyeTrackerRecording|camera_recording.Recording, pathlib.Path]:
+    if rec_type==RecordingType.Camera:
+        rec_info = camera_recording.Recording.load_from_json(working_dir)
+        in_video = rec_info.get_video_path()
+    elif rec_type==RecordingType.EyeTracker:
+        rec_info = EyeTrackerRecording.load_from_json(working_dir)
+        in_video = rec_info.get_scene_video_path()
+    return rec_info, in_video
+
+class SessionDefinition:
+    def __init__(self, recordings: list[RecordingDefinition]=None, sync_ref: str=None):
+        if recordings is None:
+            recordings = []
+        self.recordings = recordings
+
+        self.sync_ref: str = None
+        self.set_sync_ref(sync_ref)
+
+    def add_recording(self, recording: RecordingDefinition):
+        self.recordings.append(recording)
+
+    def set_sync_ref(self, which: str):
+        if not any([r.name==which for r in self.recordings]):
+            raise ValueError(f'recording "{which}" not known')
+        self.sync_ref = which
+
+    def get_recording(self, which: str) -> RecordingDefinition:
+        for r in self.recordings:
+            if r.name==which:
+                return r
+        raise ValueError(f'recording "{which}" not found')
+
+    def store_as_json(self, path: str | pathlib.Path):
+        path = pathlib.Path(path)
+        with open(path, 'w') as f:
+            json.dump(self, f, cls=utils.CustomTypeEncoder, indent=2)
+
+    @staticmethod
+    def load_from_json(path: str | pathlib.Path) -> 'Session':
+        path = pathlib.Path(path)
+        with open(path, 'r') as f:
+            return json.load(f, object_hook=utils.json_reconstitute)
+utils.register_type(utils.CustomTypeEntry(SessionDefinition,'__session.SessionDefinition__',lambda x: {'recordings': x.recordings, 'sync_ref': x.sync_ref}, lambda x: SessionDefinition(**x)))
+
+
+class Session:
+    default_json_file_name = 'session_info.json'
+
+    def __init__(self, definition: SessionDefinition, name: str, working_directory: str|pathlib.Path = None, recordings: dict[str,Recording] = None):
+        self.definition = definition
+        self.name = name
+        self.working_directory: pathlib.Path = pathlib.Path(working_directory) if working_directory else None
+        if not recordings:
+            recordings = {}
+        self.recordings = recordings
+
+    def create_working_directory(self, parent_directory: str|pathlib.Path):
+        self.working_directory = pathlib.Path(parent_directory) / self.name
+        if not self.working_directory.is_dir():
+            self.working_directory.mkdir()
+
+    def import_and_add_recording(self, which: str, rec_info: EyeTrackerRecording|camera_recording.Recording, copy_video = True) -> Recording:
+        rec_def = self.definition.get_recording(which)
+        self.check_recording_info(which, rec_info)
+
+        # do import
+        rec_info.working_directory = self.working_directory / rec_def.name
+        if rec_def.type==RecordingType.EyeTracker:
+            rec_info = importing.do_import(rec_info=rec_info, copy_scene_video=copy_video)
+        else:
+            rec_info = camera_recording.do_import(rec_info=rec_info, copy_video=copy_video)
+
+        # add recording
+        self.add_recording_from_info(which, rec_info)
+        return self.recordings[which]
+
+    def load_existing_recordings(self):
+        # load recordings that are present
+        for r in self.definition.recordings:
+            if (self.working_directory / r.name).is_dir():
+                self.add_existing_recording(r.name)
+
+    def add_existing_recording(self, which: str) -> Recording:
+        r_fold = self.working_directory / which
+        if not r_fold.is_dir():
+            return
+
+        # get info about recording
+        rec_def = self.definition.get_recording(which)
+        if rec_def.type==RecordingType.EyeTracker:
+            rec_info = EyeTrackerRecording.load_from_json(r_fold)
+        else:
+            rec_info = camera_recording.Recording.load_from_json(r_fold)
+
+        # add recording
+        self.add_recording_from_info(which, rec_info)
+        return self.recordings[which]
+
+    def check_recording_info(self, which: str, rec_info: EyeTrackerRecording|camera_recording.Recording):
+        rec_def = self.definition.get_recording(which)
+        if rec_def.type==RecordingType.EyeTracker:
+            assert isinstance(rec_info,EyeTrackerRecording), f"The provided rec_info is not for an eye tracker recording, but {which} is an eye tracker recording"
+        elif rec_def.type==RecordingType.Camera:
+            assert isinstance(rec_info,camera_recording.Recording), f"The provided rec_info is not for a camera recording, but {which} is a camera recording"
+
+    def add_recording_from_info(self, which: str, rec_info: EyeTrackerRecording|camera_recording.Recording):
+        rec_def = self.definition.get_recording(which)
+        self.check_recording_info(which, rec_info)
+        self.recordings[which] = Recording(rec_def, rec_info)
+
+    def has_all_recordings(self) -> bool:
+        return all([r.name in self.recordings for r in self.definition.recordings])
+
+    def store_as_json(self, path: str | pathlib.Path = None):
+        if path is None:
+            path = self.working_directory
+        path = pathlib.Path(path)
+        if path.is_dir():
+            path /= self.default_json_file_name
+        with open(path, 'w') as f:
+            to_dump = {k:getattr(self,k) for k in ['definition']}    # only this field. Name will be populated from name of session/provided folder, recordings from each subfolder in the session/provided folder, and working_directory as the provided path
+            # dump to file
+            json.dump(to_dump, f, cls=utils.CustomTypeEncoder, indent=2)
+
+    @staticmethod
+    def load_from_json(path: str | pathlib.Path) -> 'Session':
+        path = pathlib.Path(path)
+        if path.is_dir():
+            path /= Session.default_json_file_name
+        # load session setup
+        with open(path, 'r') as f:
+            sess = Session(**json.load(f, object_hook=utils.json_reconstitute), name=path.parent.name, working_directory=path.parent)
+        # load recordings that are present
+        sess.load_existing_recordings()
+
+        return sess
+
+    @staticmethod
+    def from_definition(definition: SessionDefinition, path: str | pathlib.Path) -> 'Session':
+        # for loading a recording directory that doesn't contain a session json file
+        # use the provided definition instead
+        sess = Session(definition, name=path.name, working_directory=path)
+        sess.load_existing_recordings()
+        return sess
+
+
+def get_sessions_from_directory(path: str|pathlib.Path, session_json_name=Session.default_json_file_name) -> list[Session]:
+    path = pathlib.Path(path)
+
+    # iterate through all folders in the provided path and check if the folder contains a file with the session_json_name
+    # then its potentially a session
+    sessions: list[Session] = []
+    for d in path.iterdir():
+        if not d.is_dir():
+            continue
+
+        f = d / session_json_name
+        if not f.is_file():
+            continue
+
+        sessions.append(Session.load_from_json(f))
+
+    return sessions

gazemapper-0.5.0/src/gazeMapper/version.py

@@ -0,0 +1,13 @@
+__version__ = "0.5.0"
+
+__title__ = "gazeMapper"
+__description__ = "Automated world-based analysis of wearable eye tracker data."
+__url__ = "https://github.com/dcnieho/gazeMapper"
+__uri__ = __url__
+__doc__ = __description__ + " <" + __url__ + ">"
+
+__author__ = "Diederick Niehorster"
+__email__ = "diederick_c.niehorster@humlab.lu.se"
+
+__license__ = "MIT"
+__copyright__ = "Copyright (c) 2024 " + __author__

gazemapper-0.5.0/src/gazeMapper.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: gazeMapper
+Version: 0.5.0
+Summary: Automated world-based analysis of wearable eye tracker data.
+Home-page: https://github.com/dcnieho/gazeMapper
+Author: Diederick Niehorster
+Author-email: diederick_c.niehorster@humlab.lu.se
+License: MIT License
+        
+        Copyright (c) 2024 Diederick Niehorster
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Source Code, https://github.com/dcnieho/gazeMapper
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: glassesTools[GUI]==1.4.0
+Requires-Dist: glassesValidator==2.0.0
+
+[![Downloads](https://static.pepy.tech/badge/gazeMapper)](https://pepy.tech/project/gazeMapper)
+[![Citation Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.juleskreuer.eu%2Fcitation-badge.php%3Fshield%26doi%3D10.3758%2Fs13428-023-02105-5&color=blue)](https://scholar.google.com/citations?view_op=view_citation&citation_for_view=uRUYoVgAAAAJ:uWQEDVKXjbEC)
+[![PyPI Latest Release](https://img.shields.io/pypi/v/gazeMapper.svg)](https://pypi.org/project/gazeMapper/)
+[![image](https://img.shields.io/pypi/pyversions/gazeMapper.svg)](https://pypi.org/project/gazeMapper/)
+
+# gazeMapper v0.5.0
+Tool for automated world-based analysis of wearable eye tracker data.
+
+If you use this tool or any of the code in this repository, please cite:<br>
+Niehorster, D.C., Hessels, R.S., Nyström, M., Benjamins, J.S. and Hooge, I.T.C. (in prep). gazeMapper: A tool for automated world-based analysis of wearable eye tracker data
+
+# How to acquire
+GlassesValidator is available from `https://github.com/dcnieho/gazeMapper`, and supports Python 3.10 and 3.11 on Windows, MacOS and Linux.
+
+For Windows users who wish to use the gazeMapper GUI, the easiest way to acquire gazeMapper is to [download
+a standalone executable](https://github.com/dcnieho/gazeMapper/releases/latest). The standalone executable is not
+available for MacOS or Linux.
+
+For users on Windows, Mac or Linux who wish to use gazeMapper in their Python code, the easiest way to acquire
+gazeMapper is to install it directly into your Python distribution using the command
+`python -m pip install gazeMapper`. Should that fail, this repository is pip-installable as well:
+`python -m pip install git+https://github.com/dcnieho/gazeMapper.git#egg=gazeMapper`. NB: on some platforms you may have
+to replace `python` with `python3` in the above command lines.
+
+Once pip-installed in your Python distribution, there are three ways to run the GUI on any of the supported operating systems:
+1. Directly in the terminal of your operating system, type `gazeMapper` and run it.
+2. Open a Python console. From such a console, running the GUI requires only the following two lines of code:
+    ```python
+    import gazeMapper
+    gazeMapper.GUI.run()
+    ```
+3. If you run the gazeMapper's GUI from a script, make sure to wrap your script in `if __name__=="__main__"`. This is required for correct operation from a script because the GUI uses multiprocessing functionality. Do as follows:
+    ```python
+    if __name__=="__main__":
+        import gazeMapper
+        gazeMapper.GUI.run()
+    ```

gazemapper-0.5.0/src/gazeMapper.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+setup.py
+src/gazeMapper/__init__.py
+src/gazeMapper/camera_recording.py
+src/gazeMapper/config.py
+src/gazeMapper/episode.py
+src/gazeMapper/plane.py
+src/gazeMapper/session.py
+src/gazeMapper/version.py
+src/gazeMapper.egg-info/PKG-INFO
+src/gazeMapper.egg-info/SOURCES.txt
+src/gazeMapper.egg-info/dependency_links.txt
+src/gazeMapper.egg-info/requires.txt
+src/gazeMapper.egg-info/top_level.txt

gazemapper-0.5.0/src/gazeMapper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gazemapper-0.5.0/src/gazeMapper.egg-info/requires.txt

@@ -0,0 +1,2 @@
+glassesTools[GUI]==1.4.0
+glassesValidator==2.0.0

gazemapper-0.5.0/src/gazeMapper.egg-info/top_level.txt

@@ -0,0 +1 @@
+gazeMapper