cineon-api-format 3.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,28 @@
1
+ from .definitions import Construct, Metric
2
+ from .requests import (
3
+ CineonInferenceRequest,
4
+ ClientInfo,
5
+ InferenceRequest,
6
+ )
7
+ from .responses import (
8
+ InferenceOutput,
9
+ InferenceResponse,
10
+ PingResponse,
11
+ RootResponse,
12
+ VersionResponse,
13
+ )
14
+ from .version import __version__
15
+
16
+ __all__ = [
17
+ "__version__",
18
+ "Metric",
19
+ "Construct",
20
+ "ClientInfo",
21
+ "InferenceRequest",
22
+ "CineonInferenceRequest",
23
+ "RootResponse",
24
+ "PingResponse",
25
+ "InferenceOutput",
26
+ "InferenceResponse",
27
+ "VersionResponse",
28
+ ]
@@ -0,0 +1,189 @@
1
+ from enum import Enum
2
+
3
+
4
+ # This is part of the public API, so do not change existing names!
5
+ class Construct(Enum):
6
+ stress = "stress"
7
+ workload = "workload"
8
+ fatigue = "fatigue"
9
+
10
+
11
+ class GazetoolsInput(Enum):
12
+ t = "t"
13
+ gaze_origin_x = "gaze_origin_x"
14
+ gaze_origin_y = "gaze_origin_y"
15
+ gaze_origin_z = "gaze_origin_z"
16
+ gaze_direction_x = "gaze_direction_x"
17
+ gaze_direction_y = "gaze_direction_y"
18
+ gaze_direction_z = "gaze_direction_z"
19
+ pupil_diameter = "pupil_diameter"
20
+ object_gazed_at = "object_gazed_at"
21
+ left_eye_openness = "left_eye_openness"
22
+ right_eye_openness = "right_eye_openness"
23
+
24
+
25
+ # This is part of the public API, so do not change existing names!
26
+ class Metric(Enum):
27
+
28
+ # Fixations
29
+ fixation_duration_mean = "fixation_duration_mean"
30
+ fixation_dispersion_median = "fixation_dispersion_median"
31
+ total_fixation_displacement_mean = "total_fixation_displacement_mean"
32
+
33
+ # Saccades
34
+ saccade_speed_mean = "saccade_speed_mean"
35
+ saccade_speed_max = "saccade_speed_max"
36
+ saccade_amplitude_max = "saccade_amplitude_max"
37
+ persistent_saccade_ratio = "persistent_saccade_ratio"
38
+ saccade_rate = "saccade_rate"
39
+ saccade_angular_amplitude_mean = "saccade_angular_amplitude_mean"
40
+ saccade_angular_amplitude_std = "saccade_angular_amplitude_std"
41
+ saccade_angular_speed_mean = "saccade_angular_speed_mean"
42
+ saccade_angular_speed_std = "saccade_angular_speed_std"
43
+ saccade_antipersistent_to_persistent_ratio = (
44
+ "saccade_antipersistent_to_persistent_ratio"
45
+ )
46
+ saccade_persistent_to_total_ratio = "saccade_persistent_to_total_ratio"
47
+
48
+ # Entropy
49
+ entropy_gaze = "entropy_gaze"
50
+ entropy_gaze_efficiency = "entropy_gaze_efficiency"
51
+
52
+ # Pupillometry
53
+ pupil_diameter_mean = "pupil_diameter_mean"
54
+ pupil_diameter_std = "pupil_diameter_std"
55
+
56
+ # Blinks
57
+ blink_rate = "blink_rate"
58
+ blink_duration_mean = "blink_duration_mean"
59
+ blink_duration_std = "blink_duration_std"
60
+ percent_eyes_closed = "percent_eyes_closed"
61
+
62
+ # Head kinematics
63
+ head_acceleration_mean = "head_acceleration_mean"
64
+ head_acceleration_std = "head_acceleration_std"
65
+
66
+ # Fixations
67
+ fixation_rate = "fixation_rate"
68
+ fixation_duration_std = "fixation_duration_std"
69
+ fixation_angular_distance_mean = "fixation_angular_distance_mean"
70
+ fixation_angular_distance_std = "fixation_angular_distance_std"
71
+ fixation_yaw_dispersion_mean = "fixation_yaw_dispersion_mean"
72
+ fixation_yaw_dispersion_std = "fixation_yaw_dispersion_std"
73
+ fixation_pitch_dispersion_mean = "fixation_pitch_dispersion_mean"
74
+ fixation_pitch_dispersion_std = "fixation_pitch_dispersion_std"
75
+
76
+
77
+ feature_groups: dict[str, list[Metric | GazetoolsInput]] = {
78
+ "traditional": [
79
+ # v2
80
+ Metric.fixation_duration_mean,
81
+ Metric.fixation_rate,
82
+ Metric.fixation_dispersion_median,
83
+ Metric.total_fixation_displacement_mean,
84
+ Metric.saccade_speed_mean,
85
+ Metric.saccade_rate,
86
+ Metric.saccade_speed_max,
87
+ Metric.saccade_amplitude_max,
88
+ Metric.persistent_saccade_ratio,
89
+ Metric.entropy_gaze_efficiency,
90
+ Metric.head_acceleration_mean,
91
+ # v3
92
+ Metric.head_acceleration_std,
93
+ Metric.fixation_duration_std,
94
+ Metric.fixation_angular_distance_mean,
95
+ Metric.fixation_angular_distance_std,
96
+ Metric.fixation_yaw_dispersion_mean,
97
+ Metric.fixation_yaw_dispersion_std,
98
+ Metric.fixation_pitch_dispersion_mean,
99
+ Metric.fixation_pitch_dispersion_std,
100
+ Metric.saccade_angular_amplitude_mean,
101
+ Metric.saccade_angular_amplitude_std,
102
+ Metric.saccade_angular_speed_std,
103
+ Metric.saccade_antipersistent_to_persistent_ratio,
104
+ Metric.entropy_gaze,
105
+ ],
106
+ "pupillometry": [
107
+ # v2
108
+ Metric.pupil_diameter_mean,
109
+ # v3
110
+ Metric.pupil_diameter_std,
111
+ ],
112
+ "blink": [
113
+ # v2
114
+ Metric.blink_rate,
115
+ Metric.blink_duration_mean,
116
+ Metric.percent_eyes_closed,
117
+ # v3
118
+ Metric.blink_duration_std,
119
+ ],
120
+ # Deep-learning models do not take labelled DataFrame data
121
+ # Because of this input data is fed to the models in the order below
122
+ # This order must match what the model is expecting(!)
123
+ "deep_learning": [
124
+ GazetoolsInput.gaze_origin_x,
125
+ GazetoolsInput.gaze_origin_y,
126
+ GazetoolsInput.gaze_origin_z,
127
+ GazetoolsInput.gaze_direction_x,
128
+ GazetoolsInput.gaze_direction_y,
129
+ GazetoolsInput.gaze_direction_z,
130
+ GazetoolsInput.pupil_diameter,
131
+ GazetoolsInput.left_eye_openness,
132
+ GazetoolsInput.right_eye_openness,
133
+ ],
134
+ # Python models don't explicitly require features, and instead accept
135
+ # a `model_dump` from CineonData, that is then serialised into JSON
136
+ "python_model_features": [],
137
+ }
138
+
139
+ # Necessary because the ml-pipeline has different nomenclature
140
+ ml_metric_names: dict[Metric, str] = {
141
+ Metric.fixation_duration_mean: "MeanFixationDuration",
142
+ Metric.fixation_rate: "MeanFixationRate",
143
+ Metric.fixation_dispersion_median: "median_fix_dispersion",
144
+ Metric.total_fixation_displacement_mean: "mean_total_fix_displacement",
145
+ Metric.saccade_speed_mean: "MeanSaccadeVelocity",
146
+ Metric.saccade_rate: "MeanSaccadeRate",
147
+ Metric.saccade_speed_max: "PeakSaccadeVelocity",
148
+ Metric.saccade_amplitude_max: "SaccadeAmplitude",
149
+ Metric.persistent_saccade_ratio: "PersistenceSaccsRatio",
150
+ Metric.head_acceleration_mean: "MeanHeadAccel",
151
+ Metric.entropy_gaze_efficiency: "Entropy",
152
+ Metric.pupil_diameter_mean: "PupilDiameterMean",
153
+ }
154
+
155
+ gazetools_metric_names: dict[Metric, str] = {
156
+ Metric.fixation_duration_mean: "fixations.duration.mean",
157
+ Metric.fixation_rate: "fixations.rate",
158
+ # TODO should this be `yaw_dispersion` or `pitch_dispersion`?
159
+ Metric.fixation_dispersion_median: "fixations.yaw_dispersion.median",
160
+ Metric.total_fixation_displacement_mean: "fixations.angular_displacement.mean",
161
+ Metric.saccade_speed_mean: "saccades.angular_speed.mean",
162
+ Metric.saccade_rate: "saccades.rate",
163
+ Metric.saccade_speed_max: "saccades.angular_speed.max",
164
+ Metric.saccade_amplitude_max: "saccades.angular_straight_amplitude.max",
165
+ Metric.persistent_saccade_ratio: "saccades.persistent_to_total_ratio",
166
+ Metric.head_acceleration_mean: "head_kinematics.acceleration.mean",
167
+ Metric.pupil_diameter_mean: "pupillometry.diameter.mean",
168
+ Metric.blink_rate: "blinks.rate",
169
+ Metric.blink_duration_mean: "blinks.duration.mean",
170
+ Metric.percent_eyes_closed: "blinks.percent_eyes_closed",
171
+ Metric.head_acceleration_std: "head_kinematics.acceleration.std",
172
+ Metric.fixation_duration_std: "fixations.duration.std",
173
+ Metric.fixation_angular_distance_mean: "fixations.angular_distance.mean",
174
+ Metric.fixation_angular_distance_std: "fixations.angular_distance.std",
175
+ Metric.fixation_yaw_dispersion_mean: "fixations.yaw_dispersion.mean",
176
+ Metric.fixation_yaw_dispersion_std: "fixations.yaw_dispersion.std",
177
+ Metric.fixation_pitch_dispersion_mean: "fixations.pitch_dispersion.mean",
178
+ Metric.fixation_pitch_dispersion_std: "fixations.pitch_dispersion.std",
179
+ Metric.saccade_angular_amplitude_mean: "saccades.angular_straight_amplitude.mean",
180
+ Metric.saccade_angular_amplitude_std: "saccades.angular_straight_amplitude.std",
181
+ Metric.saccade_angular_speed_mean: "saccades.angular_speed.mean",
182
+ Metric.saccade_angular_speed_std: "saccades.angular_speed.std",
183
+ Metric.saccade_antipersistent_to_persistent_ratio: "saccades.antipersistent_to_persistent_ratio",
184
+ Metric.saccade_persistent_to_total_ratio: "saccades.persistent_to_total_ratio",
185
+ Metric.entropy_gaze: "entropy.gaze",
186
+ Metric.entropy_gaze_efficiency: "entropy.gaze_efficiency",
187
+ Metric.blink_duration_std: "blinks.duration.std",
188
+ Metric.pupil_diameter_std: "pupillometry.diameter.std",
189
+ }
@@ -0,0 +1,85 @@
1
+ from typing import Optional, Self
2
+
3
+ from cineon_format import CineonData
4
+ from pydantic import BaseModel, field_validator, model_validator
5
+
6
+ from cineon_api_format.definitions import Construct, Metric
7
+
8
+ DEFAULT_CONSTRUCRTS = [Construct.stress, Construct.workload, Construct.fatigue]
9
+ DEFAULT_METRICS = [
10
+ Metric.fixation_duration_mean,
11
+ Metric.saccade_amplitude_max,
12
+ Metric.persistent_saccade_ratio,
13
+ Metric.entropy_gaze_efficiency,
14
+ Metric.pupil_diameter_mean,
15
+ ]
16
+
17
+
18
+ class ClientInfo(BaseModel, extra="forbid"):
19
+ platform: Optional[str] = None
20
+ version: Optional[str] = None
21
+
22
+
23
+ class InferenceRequest(BaseModel, extra="forbid"):
24
+ constructs: Optional[list[Construct]] = None
25
+ metrics: Optional[list[Metric]] = None
26
+ models: Optional[list[str]] = None
27
+ device: Optional[str] = None
28
+ client: Optional[ClientInfo] = None
29
+ eye_data: CineonData
30
+
31
+ # Check data list is not empty
32
+ @field_validator("eye_data")
33
+ @classmethod
34
+ def check_data_not_empty(cls, eye_data: CineonData) -> CineonData:
35
+ if len(eye_data.timestamp) == 0:
36
+ raise ValueError("Data list must not be empty.")
37
+ return eye_data
38
+
39
+ # Check that at least one of either construct/metrics/model is requested
40
+ @model_validator(mode="after")
41
+ def check_at_least_one_requested(self) -> Self:
42
+ n = 0
43
+ if self.constructs:
44
+ n += len(self.constructs)
45
+ if self.metrics:
46
+ n += len(self.metrics)
47
+ if self.models:
48
+ n += len(self.models)
49
+ if n == 0:
50
+ raise ValueError(
51
+ "At least one of constructs/metrics/models must be requested."
52
+ )
53
+ return self
54
+
55
+
56
+ class CineonInferenceRequest(BaseModel, extra="forbid"):
57
+ device: Optional[str] = None
58
+ client: Optional[ClientInfo] = None
59
+ eye_data: CineonData
60
+
61
+ # Check data list is not empty
62
+ @field_validator("eye_data")
63
+ @classmethod
64
+ def check_data_not_empty(cls, eye_data: CineonData) -> CineonData:
65
+ if len(eye_data.timestamp) == 0:
66
+ raise ValueError("eye_data must contain at least one timestamp.")
67
+ return eye_data
68
+
69
+ def to_ele_request(
70
+ self,
71
+ constructs: list[Construct] | None = None,
72
+ metrics: list[Metric] | None = None,
73
+ ) -> InferenceRequest:
74
+ if constructs is None:
75
+ constructs = DEFAULT_CONSTRUCRTS
76
+ if metrics is None:
77
+ metrics = DEFAULT_METRICS
78
+
79
+ return InferenceRequest(
80
+ constructs=constructs,
81
+ metrics=metrics,
82
+ device=self.device,
83
+ client=self.client,
84
+ eye_data=self.eye_data,
85
+ )
@@ -0,0 +1,28 @@
1
+ from pydantic import BaseModel
2
+
3
+ from cineon_api_format.definitions import Construct, Metric
4
+
5
+
6
+ class RootResponse(BaseModel, extra="forbid"):
7
+ name: str
8
+ version: str
9
+
10
+
11
+ class PingResponse(BaseModel, extra="forbid"):
12
+ message: str
13
+
14
+
15
+ class VersionResponse(BaseModel, extra="forbid"):
16
+ ele_api: str
17
+ cineon_format: str
18
+ gazeprocessing: str
19
+ gazetools: str
20
+
21
+
22
+ class InferenceOutput(BaseModel, extra="forbid"):
23
+ prediction: Construct | Metric | str
24
+ score: float
25
+
26
+
27
+ class InferenceResponse(BaseModel, extra="forbid"):
28
+ data: list[InferenceOutput]
@@ -0,0 +1,3 @@
1
+ from importlib import metadata
2
+
3
+ __version__ = metadata.version("cineon-api-format")
@@ -0,0 +1,51 @@
1
+ Metadata-Version: 2.4
2
+ Name: cineon-api-format
3
+ Version: 3.0.0
4
+ Summary: A shared repository that describes the types used by the ELE-api, and other Cineon apis.
5
+ Requires-Python: >=3.12
6
+ Requires-Dist: cineon-format<4,>=3.0.0
7
+ Requires-Dist: pydantic>=2.12.5
8
+ Requires-Dist: typeguard>=4.4.4
9
+ Description-Content-Type: text/markdown
10
+
11
+ # Python repository template
12
+
13
+ ![Latest Release](badges/version.svg) ![Coverage Status](badges/coverage.svg) ![Code complexity](badges/complexity.svg)
14
+
15
+ This serves as an example of how to set up a new Python project.
16
+
17
+ You should update this `README` to be specific to your project. You should update `pyproject.toml` with the name of your project and rename the `src/repository_template` directory to be appropriate for your project.
18
+
19
+ ## Run the example
20
+
21
+ A simple "Hello World" example can be run using:
22
+
23
+ ```bash
24
+ uv run scripts/example.py
25
+ ```
26
+
27
+ ## Set up the hooks
28
+
29
+ These pre-push hooks ensure that the formatter is run and the badges are updated every time you attempt to `git push`. This way formatting errors are caught and be corrected before they reach the GitHub continuous-integration (CI) step. The badges are then automatically up-to-date.
30
+
31
+ ```bash
32
+ git config --local core.hooksPath .githooks/
33
+ ```
34
+
35
+ ## Check the formatting
36
+
37
+ The formatting can be checked manually using:
38
+
39
+ ```bash
40
+ ./scripts/format.sh
41
+ ```
42
+
43
+ this is exactly the script that is run in the CI pipeline and the pre-push hook. Formatting uses `Prettier` for markdown, `shfmt` for shell scripts, and `ruff` for Python.
44
+
45
+ ## Run the tests
46
+
47
+ The tests can be run manually using:
48
+
49
+ ```bash
50
+ ./scripts/test.sh
51
+ ```
@@ -0,0 +1,8 @@
1
+ cineon_api_format/__init__.py,sha256=-_SEeWHJxQvCWK-9DZNCjREQgD7jvfXdH-yLE5pQB0s,544
2
+ cineon_api_format/definitions.py,sha256=4mJqJC8UzYkHdEPSQCH86qUKhAtRKDLEXnuDk_VKrEk,8091
3
+ cineon_api_format/requests.py,sha256=4qDUBbcx1nS0TD9e93JSuR5xZRxQaCMv988oMKUfAWE,2735
4
+ cineon_api_format/responses.py,sha256=TPdZTMWEmrs5_gqWG0VeCRCgnG041gkY39rDG497x00,597
5
+ cineon_api_format/version.py,sha256=I-rGC557ia7QsoNoxmZfRBhMDA7oY8ZE62Rq2qtxD_c,84
6
+ cineon_api_format-3.0.0.dist-info/METADATA,sha256=Noje88TIM1jgbXOlRkkcYlS5uMIVBMPl8bPbCPEC2xs,1597
7
+ cineon_api_format-3.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
8
+ cineon_api_format-3.0.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.29.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any