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.
- cineon_api_format/__init__.py +28 -0
- cineon_api_format/definitions.py +189 -0
- cineon_api_format/requests.py +85 -0
- cineon_api_format/responses.py +28 -0
- cineon_api_format/version.py +3 -0
- cineon_api_format-3.0.0.dist-info/METADATA +51 -0
- cineon_api_format-3.0.0.dist-info/RECORD +8 -0
- cineon_api_format-3.0.0.dist-info/WHEEL +4 -0
|
@@ -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,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
|
+
  
|
|
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,,
|