cine-handler 0.1.1__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.
- cine_handler-0.1.1.dist-info/METADATA +358 -0
- cine_handler-0.1.1.dist-info/RECORD +17 -0
- cine_handler-0.1.1.dist-info/WHEEL +5 -0
- cine_handler-0.1.1.dist-info/top_level.txt +1 -0
- cine_reader/__init__.py +31 -0
- cine_reader/_lookup.py +72 -0
- cine_reader/cine.py +847 -0
- cine_reader/frame_decode.py +91 -0
- cine_reader/headers.py +452 -0
- cine_reader/image_ops.py +285 -0
- cine_reader/libs/unpack_data_arm64.dylib +0 -0
- cine_reader/libs/unpack_data_elf64.so +0 -0
- cine_reader/libs/unpack_data_win32.dll +0 -0
- cine_reader/libs/unpack_data_win64.dll +0 -0
- cine_reader/py.typed +0 -0
- cine_reader/stats.py +161 -0
- cine_reader/unpack.py +139 -0
cine_reader/cine.py
ADDED
|
@@ -0,0 +1,847 @@
|
|
|
1
|
+
"""High-level Phantom CINE reader with pythonic APIs and documented aliases."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import struct
|
|
6
|
+
from datetime import date, datetime, timedelta, timezone
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import BinaryIO, Iterator
|
|
9
|
+
|
|
10
|
+
import numpy as np
|
|
11
|
+
|
|
12
|
+
from .frame_decode import decode_frame_payload
|
|
13
|
+
from .headers import (
|
|
14
|
+
BitmapHeader,
|
|
15
|
+
CineHeader,
|
|
16
|
+
ImageOffsets,
|
|
17
|
+
Setup,
|
|
18
|
+
read_bitmap_header,
|
|
19
|
+
read_cine_header,
|
|
20
|
+
read_image_offsets,
|
|
21
|
+
read_setup,
|
|
22
|
+
)
|
|
23
|
+
from .image_ops import demosaic_bilinear, replace_dead_pixels as repair_dead_pixels
|
|
24
|
+
from .stats import average_from_frame_iter, robust_background_mad_stack, robust_background_topk
|
|
25
|
+
from .unpack import unpack_10bit_data
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class Cine:
|
|
29
|
+
"""High-level reader for Vision Research Phantom `.cine` files.
|
|
30
|
+
|
|
31
|
+
Notes
|
|
32
|
+
-----
|
|
33
|
+
Metadata field names inside `file_header`, `image_header`, and `camera_setup`
|
|
34
|
+
follow the CINE specification naming (CamelCase / `bi*` fields). Python-facing
|
|
35
|
+
methods and top-level aliases use snake_case.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
def __init__(
|
|
39
|
+
self,
|
|
40
|
+
filename: str | Path,
|
|
41
|
+
keep_annotations: bool = True,
|
|
42
|
+
*,
|
|
43
|
+
remove_dead_pixels: bool = False,
|
|
44
|
+
debayer: bool = False,
|
|
45
|
+
dead_value: int | None = None,
|
|
46
|
+
dead_is_threshold: bool = True,
|
|
47
|
+
bayer_pattern: str = "auto",
|
|
48
|
+
):
|
|
49
|
+
"""Create and open a CINE file reader.
|
|
50
|
+
|
|
51
|
+
Parameters
|
|
52
|
+
----------
|
|
53
|
+
filename:
|
|
54
|
+
Path to the `.cine` file.
|
|
55
|
+
keep_annotations:
|
|
56
|
+
If `True`, keep per-frame annotation payload bytes available in
|
|
57
|
+
`annotation_data` and `annotation`.
|
|
58
|
+
remove_dead_pixels:
|
|
59
|
+
If `True`, dead-pixel repair is applied every time a frame is loaded.
|
|
60
|
+
debayer:
|
|
61
|
+
If `True`, raw color CFA/Bayer frames are debayered every time a
|
|
62
|
+
frame is loaded.
|
|
63
|
+
dead_value:
|
|
64
|
+
Optional dead-pixel marker/threshold used when `remove_dead_pixels`
|
|
65
|
+
is enabled. If `None`, it is inferred from setup metadata.
|
|
66
|
+
dead_is_threshold:
|
|
67
|
+
If `True`, values `>= dead_value` are repaired.
|
|
68
|
+
bayer_pattern:
|
|
69
|
+
Bayer layout token for debayering. Use `"auto"` to infer from setup
|
|
70
|
+
`CFA`.
|
|
71
|
+
"""
|
|
72
|
+
self.filename = str(filename)
|
|
73
|
+
self.keep_annotations = bool(keep_annotations)
|
|
74
|
+
self.remove_dead_pixels = bool(remove_dead_pixels)
|
|
75
|
+
self.debayer = bool(debayer)
|
|
76
|
+
self.dead_value = dead_value
|
|
77
|
+
self.dead_is_threshold = bool(dead_is_threshold)
|
|
78
|
+
self.bayer_pattern_mode = str(bayer_pattern)
|
|
79
|
+
|
|
80
|
+
self.file_handle: BinaryIO | None = None
|
|
81
|
+
self.file_header: CineHeader | None = None
|
|
82
|
+
self.image_header: BitmapHeader | None = None
|
|
83
|
+
self.camera_setup: Setup | None = None
|
|
84
|
+
self.image_locations: ImageOffsets | None = None
|
|
85
|
+
|
|
86
|
+
self.current_frame: int | None = None
|
|
87
|
+
self.pixel_array: np.ndarray | None = None
|
|
88
|
+
self.pixel_data: np.ndarray | None = None
|
|
89
|
+
self.red_pixels: np.ndarray | None = None
|
|
90
|
+
self.green_pixels: np.ndarray | None = None
|
|
91
|
+
self.blue_pixels: np.ndarray | None = None
|
|
92
|
+
self.annotation_size: int = 0
|
|
93
|
+
self.annotation_data: bytes = b""
|
|
94
|
+
self.annotation: bytes = b""
|
|
95
|
+
self.image_size: int = 0
|
|
96
|
+
self.image_data: bytes = b""
|
|
97
|
+
self._pixel_array_channel_order: str | None = None
|
|
98
|
+
self._color_samples_from_raw_cfa = False
|
|
99
|
+
|
|
100
|
+
self._recording_datetime: datetime | None = None
|
|
101
|
+
|
|
102
|
+
self.open_cine_file(self.filename)
|
|
103
|
+
|
|
104
|
+
def __enter__(self) -> "Cine":
|
|
105
|
+
return self
|
|
106
|
+
|
|
107
|
+
def __exit__(self, exc_type, exc, tb) -> bool:
|
|
108
|
+
self.close_file()
|
|
109
|
+
return False
|
|
110
|
+
|
|
111
|
+
def __del__(self) -> None:
|
|
112
|
+
try:
|
|
113
|
+
self.close_file()
|
|
114
|
+
except Exception:
|
|
115
|
+
pass
|
|
116
|
+
|
|
117
|
+
@property
|
|
118
|
+
def first_frame_number(self) -> int:
|
|
119
|
+
"""Alias for `file_header.FirstImageNo`."""
|
|
120
|
+
header = self._require_file_header()
|
|
121
|
+
return int(header.FirstImageNo)
|
|
122
|
+
|
|
123
|
+
@property
|
|
124
|
+
def total_frames(self) -> int:
|
|
125
|
+
"""Alias for `file_header.ImageCount`."""
|
|
126
|
+
header = self._require_file_header()
|
|
127
|
+
return int(header.ImageCount)
|
|
128
|
+
|
|
129
|
+
@property
|
|
130
|
+
def last_frame_number(self) -> int:
|
|
131
|
+
"""Derived final frame number (`FirstImageNo + ImageCount - 1`)."""
|
|
132
|
+
return self.first_frame_number + self.total_frames - 1
|
|
133
|
+
|
|
134
|
+
@property
|
|
135
|
+
def frame_rate(self) -> float:
|
|
136
|
+
"""Best available frame rate in Hz (prefers floating-point setup value)."""
|
|
137
|
+
setup = self._require_camera_setup()
|
|
138
|
+
return setup.frame_rate_hz
|
|
139
|
+
|
|
140
|
+
@property
|
|
141
|
+
def exposure_time_ns(self) -> int:
|
|
142
|
+
"""Best available exposure time in nanoseconds."""
|
|
143
|
+
setup = self._require_camera_setup()
|
|
144
|
+
return setup.exposure_time_ns
|
|
145
|
+
|
|
146
|
+
@property
|
|
147
|
+
def exposure_time_seconds(self) -> float:
|
|
148
|
+
"""Best available exposure time in seconds."""
|
|
149
|
+
setup = self._require_camera_setup()
|
|
150
|
+
return setup.exposure_time_seconds
|
|
151
|
+
|
|
152
|
+
@property
|
|
153
|
+
def exposure_time(self) -> float:
|
|
154
|
+
"""Alias for `exposure_time_seconds`."""
|
|
155
|
+
return self.exposure_time_seconds
|
|
156
|
+
|
|
157
|
+
@property
|
|
158
|
+
def recording_datetime(self) -> datetime | None:
|
|
159
|
+
"""Recording timestamp derived from `TriggerTime` and setup timezone."""
|
|
160
|
+
return self._recording_datetime
|
|
161
|
+
|
|
162
|
+
@property
|
|
163
|
+
def recording_date(self) -> date | None:
|
|
164
|
+
"""Recording calendar date derived from `recording_datetime`."""
|
|
165
|
+
dt = self._recording_datetime
|
|
166
|
+
return dt.date() if dt is not None else None
|
|
167
|
+
|
|
168
|
+
@property
|
|
169
|
+
def cfa_code(self) -> int:
|
|
170
|
+
"""Color Filter Array code from setup metadata."""
|
|
171
|
+
setup = self._require_camera_setup()
|
|
172
|
+
return int(getattr(setup, "CFA", 0))
|
|
173
|
+
|
|
174
|
+
@property
|
|
175
|
+
def bayer_pattern(self) -> str | None:
|
|
176
|
+
"""Best-effort Bayer pattern inferred from `camera_setup.CFA`."""
|
|
177
|
+
return self._resolve_bayer_pattern()
|
|
178
|
+
|
|
179
|
+
@property
|
|
180
|
+
def image(self) -> np.ndarray:
|
|
181
|
+
"""Alias for latest decoded frame array (`pixel_array`)."""
|
|
182
|
+
arr = self.pixel_array
|
|
183
|
+
if arr is None:
|
|
184
|
+
raise RuntimeError("No frame loaded.")
|
|
185
|
+
return arr
|
|
186
|
+
|
|
187
|
+
@image.setter
|
|
188
|
+
def image(self, value: np.ndarray) -> None:
|
|
189
|
+
self.pixel_array = np.asarray(value)
|
|
190
|
+
self.pixel_data = self.pixel_array.reshape(-1)
|
|
191
|
+
self._pixel_array_channel_order = "RGB" if self.pixel_array.ndim == 3 else None
|
|
192
|
+
self._update_color_sample_arrays(self.pixel_array)
|
|
193
|
+
|
|
194
|
+
@property
|
|
195
|
+
def frame(self) -> np.ndarray:
|
|
196
|
+
"""Alias for latest decoded frame array (`pixel_array`)."""
|
|
197
|
+
return self.image
|
|
198
|
+
|
|
199
|
+
@frame.setter
|
|
200
|
+
def frame(self, value: np.ndarray) -> None:
|
|
201
|
+
self.image = value
|
|
202
|
+
|
|
203
|
+
def open_cine_file(self, filename: str | Path) -> None:
|
|
204
|
+
"""Open a CINE file and parse all top-level metadata blocks.
|
|
205
|
+
|
|
206
|
+
Parameters
|
|
207
|
+
----------
|
|
208
|
+
filename:
|
|
209
|
+
Path to the CINE file to open.
|
|
210
|
+
"""
|
|
211
|
+
self.filename = str(filename)
|
|
212
|
+
self.close_file()
|
|
213
|
+
self.file_handle = open(self.filename, mode="rb")
|
|
214
|
+
try:
|
|
215
|
+
self.file_header = read_cine_header(self.file_handle)
|
|
216
|
+
self.image_header = read_bitmap_header(
|
|
217
|
+
self.file_handle,
|
|
218
|
+
off_image_header=int(self.file_header.OffImageHeader),
|
|
219
|
+
)
|
|
220
|
+
self.camera_setup = read_setup(
|
|
221
|
+
self.file_handle,
|
|
222
|
+
off_setup=int(self.file_header.OffSetup),
|
|
223
|
+
off_image_offsets=int(self.file_header.OffImageOffsets),
|
|
224
|
+
)
|
|
225
|
+
self.image_locations = read_image_offsets(
|
|
226
|
+
self.file_handle,
|
|
227
|
+
off_image_offsets=int(self.file_header.OffImageOffsets),
|
|
228
|
+
image_count=int(self.file_header.ImageCount),
|
|
229
|
+
version=int(self.file_header.Version),
|
|
230
|
+
)
|
|
231
|
+
self._recording_datetime = self._decode_recording_datetime(
|
|
232
|
+
trigger_time=int(self.file_header.TriggerTime),
|
|
233
|
+
recording_tz_minutes=int(self.camera_setup.RecordingTimeZone),
|
|
234
|
+
)
|
|
235
|
+
self.current_frame = int(self.file_header.FirstImageNo)
|
|
236
|
+
self.load_frame(self.current_frame)
|
|
237
|
+
except Exception:
|
|
238
|
+
self.close_file()
|
|
239
|
+
raise
|
|
240
|
+
|
|
241
|
+
def close_file(self) -> None:
|
|
242
|
+
"""Close the active CINE file handle."""
|
|
243
|
+
if self.file_handle is not None and not self.file_handle.closed:
|
|
244
|
+
self.file_handle.close()
|
|
245
|
+
self.file_handle = None
|
|
246
|
+
|
|
247
|
+
def next_frame(self, increment: int = 1, *, convert_bgr_to_rgb: bool = False) -> None:
|
|
248
|
+
"""Load the next frame relative to `current_frame`.
|
|
249
|
+
|
|
250
|
+
Parameters
|
|
251
|
+
----------
|
|
252
|
+
increment:
|
|
253
|
+
Number of frame numbers to advance (negative values are allowed).
|
|
254
|
+
convert_bgr_to_rgb:
|
|
255
|
+
If `True` and data is 3-channel, convert BGR payload order to RGB.
|
|
256
|
+
"""
|
|
257
|
+
if self.current_frame is None:
|
|
258
|
+
raise RuntimeError("No current frame is set.")
|
|
259
|
+
self.load_frame(self.current_frame + int(increment), convert_bgr_to_rgb=convert_bgr_to_rgb)
|
|
260
|
+
|
|
261
|
+
def load_frame(self, image_no: int, *, convert_bgr_to_rgb: bool = False) -> None:
|
|
262
|
+
"""Load one frame into `pixel_array`.
|
|
263
|
+
|
|
264
|
+
Parameters
|
|
265
|
+
----------
|
|
266
|
+
image_no:
|
|
267
|
+
Global frame number (`FirstImageNo .. last_frame_number`) as defined
|
|
268
|
+
by the CINE header table.
|
|
269
|
+
convert_bgr_to_rgb:
|
|
270
|
+
If `True`, convert 3-channel frame data from BGR to RGB.
|
|
271
|
+
"""
|
|
272
|
+
handle = self._require_file_handle()
|
|
273
|
+
header = self._require_file_header()
|
|
274
|
+
offsets = self._require_image_locations().pImage
|
|
275
|
+
|
|
276
|
+
first = int(header.FirstImageNo)
|
|
277
|
+
count = int(header.ImageCount)
|
|
278
|
+
index = int(image_no) - first
|
|
279
|
+
if index < 0 or index >= count:
|
|
280
|
+
raise IndexError("image_no is out of bounds")
|
|
281
|
+
|
|
282
|
+
self.current_frame = int(image_no)
|
|
283
|
+
start = int(offsets[index])
|
|
284
|
+
stop = int(offsets[index + 1])
|
|
285
|
+
|
|
286
|
+
handle.seek(start, 0)
|
|
287
|
+
ann_size_raw = handle.read(4)
|
|
288
|
+
if len(ann_size_raw) != 4:
|
|
289
|
+
raise EOFError("Unexpected EOF while reading annotation size")
|
|
290
|
+
annotation_size = int.from_bytes(ann_size_raw, "little", signed=False)
|
|
291
|
+
self.annotation_size = annotation_size
|
|
292
|
+
|
|
293
|
+
if self.keep_annotations:
|
|
294
|
+
handle.seek(start, 0)
|
|
295
|
+
annotation_data = handle.read(annotation_size)
|
|
296
|
+
if len(annotation_data) != annotation_size:
|
|
297
|
+
raise EOFError("Unexpected EOF while reading annotation block")
|
|
298
|
+
self.annotation_data = annotation_data
|
|
299
|
+
if annotation_size >= 8:
|
|
300
|
+
self.annotation = annotation_data[4:annotation_size - 4]
|
|
301
|
+
else:
|
|
302
|
+
self.annotation = b""
|
|
303
|
+
image_size = int.from_bytes(annotation_data[-4:], "little", signed=False) if annotation_size >= 4 else 0
|
|
304
|
+
handle.seek(start + annotation_size, 0)
|
|
305
|
+
else:
|
|
306
|
+
self.annotation_data = b""
|
|
307
|
+
self.annotation = b""
|
|
308
|
+
image_size = 0
|
|
309
|
+
if annotation_size >= 4:
|
|
310
|
+
handle.seek(start + annotation_size - 4, 0)
|
|
311
|
+
tail_size = handle.read(4)
|
|
312
|
+
if len(tail_size) == 4:
|
|
313
|
+
image_size = int.from_bytes(tail_size, "little", signed=False)
|
|
314
|
+
handle.seek(start + annotation_size, 0)
|
|
315
|
+
|
|
316
|
+
frame_size_from_offsets = max(0, stop - start - annotation_size)
|
|
317
|
+
if frame_size_from_offsets and (image_size == 0 or image_size > frame_size_from_offsets):
|
|
318
|
+
image_size = frame_size_from_offsets
|
|
319
|
+
self.image_size = image_size
|
|
320
|
+
|
|
321
|
+
image_data = handle.read(image_size)
|
|
322
|
+
if len(image_data) != image_size:
|
|
323
|
+
raise EOFError("Unexpected EOF while reading frame payload")
|
|
324
|
+
self.image_data = image_data
|
|
325
|
+
|
|
326
|
+
frame = self._decode_frame(image_data)
|
|
327
|
+
|
|
328
|
+
if self.remove_dead_pixels:
|
|
329
|
+
frame = self._repair_dead_pixels_array(frame)
|
|
330
|
+
|
|
331
|
+
self._pixel_array_channel_order = None
|
|
332
|
+
self._update_color_sample_arrays(frame)
|
|
333
|
+
|
|
334
|
+
if self.debayer and self._is_raw_bayer_frame(frame):
|
|
335
|
+
frame = self._debayer_array(frame, bayer_pattern=self.bayer_pattern_mode)
|
|
336
|
+
|
|
337
|
+
self.pixel_array = frame
|
|
338
|
+
self._pixel_array_channel_order = self._decoded_channel_order(self.pixel_array)
|
|
339
|
+
self.pixel_data = self.pixel_array.reshape(-1)
|
|
340
|
+
|
|
341
|
+
if convert_bgr_to_rgb and self._pixel_array_channel_order == "BGR":
|
|
342
|
+
self.pixel_array = self.pixel_array[..., ::-1].copy()
|
|
343
|
+
self._pixel_array_channel_order = "RGB"
|
|
344
|
+
self._update_color_sample_arrays(self.pixel_array)
|
|
345
|
+
self.pixel_data = self.pixel_array.reshape(-1)
|
|
346
|
+
|
|
347
|
+
def replace_dead_pixels(
|
|
348
|
+
self,
|
|
349
|
+
dead_value: int | None = None,
|
|
350
|
+
*,
|
|
351
|
+
dead_is_threshold: bool = True,
|
|
352
|
+
) -> None:
|
|
353
|
+
"""Replace dead pixels in mono, Bayer raw, or RGB frames.
|
|
354
|
+
|
|
355
|
+
Parameters
|
|
356
|
+
----------
|
|
357
|
+
dead_value:
|
|
358
|
+
Dead-pixel marker value or threshold. If `None`, inferred from
|
|
359
|
+
setup metadata (`WhiteLevel + 1` when available, else sensor max).
|
|
360
|
+
dead_is_threshold:
|
|
361
|
+
If `True`, repair pixels where value is `>= dead_value`.
|
|
362
|
+
If `False`, repair pixels where value equals `dead_value`.
|
|
363
|
+
"""
|
|
364
|
+
frame = self._require_pixel_array()
|
|
365
|
+
self.pixel_array = self._repair_dead_pixels_array(
|
|
366
|
+
frame,
|
|
367
|
+
dead_value=dead_value,
|
|
368
|
+
dead_is_threshold=dead_is_threshold,
|
|
369
|
+
)
|
|
370
|
+
if not (self.pixel_array.ndim == 3 and self._color_samples_from_raw_cfa):
|
|
371
|
+
self._update_color_sample_arrays(self.pixel_array)
|
|
372
|
+
self.pixel_data = self.pixel_array.reshape(-1)
|
|
373
|
+
|
|
374
|
+
def debayer_frame(self, *, bayer_pattern: str = "auto") -> None:
|
|
375
|
+
"""Debayer the currently loaded raw CFA/Bayer frame in-place.
|
|
376
|
+
|
|
377
|
+
This mutates `pixel_array` to an RGB `[H, W, 3]` image. Raw CFA sample
|
|
378
|
+
arrays (`red_pixels`, `green_pixels`, `blue_pixels`) remain based on the
|
|
379
|
+
pre-debayer sensor mosaic.
|
|
380
|
+
"""
|
|
381
|
+
frame = self._require_pixel_array()
|
|
382
|
+
if frame.ndim == 3:
|
|
383
|
+
if self._pixel_array_channel_order == "BGR":
|
|
384
|
+
self.pixel_array = frame[..., ::-1].copy()
|
|
385
|
+
self._pixel_array_channel_order = "RGB"
|
|
386
|
+
self._update_color_sample_arrays(self.pixel_array)
|
|
387
|
+
self.pixel_data = self.pixel_array.reshape(-1)
|
|
388
|
+
return
|
|
389
|
+
if not self._is_raw_bayer_frame(frame):
|
|
390
|
+
raise ValueError("Current frame is not a raw color CFA/Bayer frame.")
|
|
391
|
+
|
|
392
|
+
self._update_color_sample_arrays(frame)
|
|
393
|
+
self.pixel_array = self._debayer_array(frame, bayer_pattern=bayer_pattern)
|
|
394
|
+
self._pixel_array_channel_order = "RGB"
|
|
395
|
+
self.pixel_data = self.pixel_array.reshape(-1)
|
|
396
|
+
|
|
397
|
+
def save_frames_to_new_file(self, output_filename: str | Path, start_frame: int, end_frame: int) -> None:
|
|
398
|
+
"""Write a trimmed CINE file for frame range `[start_frame, end_frame]`.
|
|
399
|
+
|
|
400
|
+
Parameters
|
|
401
|
+
----------
|
|
402
|
+
output_filename:
|
|
403
|
+
Output path for the new CINE file.
|
|
404
|
+
start_frame:
|
|
405
|
+
First global frame number to include.
|
|
406
|
+
end_frame:
|
|
407
|
+
Last global frame number to include (inclusive).
|
|
408
|
+
"""
|
|
409
|
+
handle = self._require_file_handle()
|
|
410
|
+
header = self._require_file_header()
|
|
411
|
+
image_header = self._require_image_header()
|
|
412
|
+
setup = self._require_camera_setup()
|
|
413
|
+
offsets = self._require_image_locations().pImage
|
|
414
|
+
|
|
415
|
+
first, _ = self._validate_frame_range(start_frame, end_frame)
|
|
416
|
+
new_image_count = int(end_frame - start_frame + 1)
|
|
417
|
+
bytes_per_offset = 8 if int(header.Version) == 1 else 4
|
|
418
|
+
|
|
419
|
+
with open(output_filename, "wb") as output_file:
|
|
420
|
+
new_file_header = bytearray(header.FileHeaderData)
|
|
421
|
+
struct.pack_into("<I", new_file_header, 12, new_image_count)
|
|
422
|
+
struct.pack_into("<i", new_file_header, 16, int(start_frame))
|
|
423
|
+
struct.pack_into("<I", new_file_header, 20, new_image_count)
|
|
424
|
+
output_file.write(new_file_header)
|
|
425
|
+
output_file.write(image_header.ImageHeaderData)
|
|
426
|
+
output_file.write(setup.SetupData)
|
|
427
|
+
|
|
428
|
+
offsets_start = output_file.tell()
|
|
429
|
+
offset_position = offsets_start + new_image_count * bytes_per_offset
|
|
430
|
+
output_offsets = []
|
|
431
|
+
|
|
432
|
+
for frame_no in range(start_frame, end_frame + 1):
|
|
433
|
+
idx = frame_no - first
|
|
434
|
+
frame_start = int(offsets[idx])
|
|
435
|
+
frame_stop = int(offsets[idx + 1])
|
|
436
|
+
frame_size = frame_stop - frame_start
|
|
437
|
+
output_offsets.append(offset_position)
|
|
438
|
+
offset_position += frame_size
|
|
439
|
+
|
|
440
|
+
for offset in output_offsets:
|
|
441
|
+
if bytes_per_offset == 8:
|
|
442
|
+
output_file.write(struct.pack("<Q", int(offset)))
|
|
443
|
+
else:
|
|
444
|
+
output_file.write(struct.pack("<I", int(offset)))
|
|
445
|
+
|
|
446
|
+
for frame_no in range(start_frame, end_frame + 1):
|
|
447
|
+
idx = frame_no - first
|
|
448
|
+
frame_start = int(offsets[idx])
|
|
449
|
+
frame_stop = int(offsets[idx + 1])
|
|
450
|
+
frame_size = frame_stop - frame_start
|
|
451
|
+
handle.seek(frame_start, 0)
|
|
452
|
+
output_file.write(handle.read(frame_size))
|
|
453
|
+
|
|
454
|
+
def average_frames(
|
|
455
|
+
self,
|
|
456
|
+
start_frame: int,
|
|
457
|
+
end_frame: int,
|
|
458
|
+
*,
|
|
459
|
+
replace_dead_pixels: bool = False,
|
|
460
|
+
chunk_size: int = 8,
|
|
461
|
+
) -> np.ndarray:
|
|
462
|
+
"""Compute per-pixel mean over an inclusive frame range.
|
|
463
|
+
|
|
464
|
+
Parameters
|
|
465
|
+
----------
|
|
466
|
+
start_frame:
|
|
467
|
+
First global frame number to include.
|
|
468
|
+
end_frame:
|
|
469
|
+
Last global frame number to include (inclusive).
|
|
470
|
+
replace_dead_pixels:
|
|
471
|
+
If `True`, run dead-pixel replacement per frame before averaging.
|
|
472
|
+
chunk_size:
|
|
473
|
+
Number of frames accumulated per chunk for lower Python overhead.
|
|
474
|
+
|
|
475
|
+
Returns
|
|
476
|
+
-------
|
|
477
|
+
numpy.ndarray
|
|
478
|
+
Averaged frame with dtype matching the currently loaded frame.
|
|
479
|
+
"""
|
|
480
|
+
self._validate_frame_range(start_frame, end_frame)
|
|
481
|
+
current = self._require_pixel_array()
|
|
482
|
+
frame_iter = self._iter_loaded_frames(
|
|
483
|
+
start_frame,
|
|
484
|
+
end_frame,
|
|
485
|
+
replace_dead_pixels=replace_dead_pixels,
|
|
486
|
+
)
|
|
487
|
+
avg, _ = average_from_frame_iter(frame_iter, out_dtype=current.dtype, chunk_size=chunk_size)
|
|
488
|
+
return avg
|
|
489
|
+
|
|
490
|
+
def mode_frames(
|
|
491
|
+
self,
|
|
492
|
+
start_frame: int,
|
|
493
|
+
end_frame: int,
|
|
494
|
+
*,
|
|
495
|
+
replace_dead_pixels: bool = False,
|
|
496
|
+
method: str = "auto",
|
|
497
|
+
q_bg: float = 0.80,
|
|
498
|
+
k_sigma: float = 2.5,
|
|
499
|
+
min_keep: int = 3,
|
|
500
|
+
max_keep: int | None = 96,
|
|
501
|
+
stack_limit: int = 128,
|
|
502
|
+
) -> np.ndarray:
|
|
503
|
+
"""Estimate robust bright background over a frame range.
|
|
504
|
+
|
|
505
|
+
Parameters
|
|
506
|
+
----------
|
|
507
|
+
start_frame:
|
|
508
|
+
First global frame number to include.
|
|
509
|
+
end_frame:
|
|
510
|
+
Last global frame number to include (inclusive).
|
|
511
|
+
replace_dead_pixels:
|
|
512
|
+
If `True`, run dead-pixel replacement per frame before processing.
|
|
513
|
+
method:
|
|
514
|
+
`"auto"`, `"mad"`, or `"topk"` background estimator.
|
|
515
|
+
q_bg:
|
|
516
|
+
Bright-background quantile threshold (0..1).
|
|
517
|
+
k_sigma:
|
|
518
|
+
MAD rejection multiplier used by `method="mad"`.
|
|
519
|
+
min_keep:
|
|
520
|
+
Minimum accepted samples per pixel.
|
|
521
|
+
max_keep:
|
|
522
|
+
Upper cap for top-k memory (used by `method="topk"`).
|
|
523
|
+
stack_limit:
|
|
524
|
+
For `method="auto"`, frame-count threshold for switching from
|
|
525
|
+
full-stack MAD to top-k.
|
|
526
|
+
|
|
527
|
+
Returns
|
|
528
|
+
-------
|
|
529
|
+
numpy.ndarray
|
|
530
|
+
Robust background image (`uint16`).
|
|
531
|
+
"""
|
|
532
|
+
self._validate_frame_range(start_frame, end_frame)
|
|
533
|
+
frame_count = end_frame - start_frame + 1
|
|
534
|
+
method_norm = method.lower().strip()
|
|
535
|
+
if method_norm == "auto":
|
|
536
|
+
method_norm = "mad" if frame_count <= stack_limit else "topk"
|
|
537
|
+
|
|
538
|
+
frame_iter = self._iter_loaded_frames(
|
|
539
|
+
start_frame,
|
|
540
|
+
end_frame,
|
|
541
|
+
replace_dead_pixels=replace_dead_pixels,
|
|
542
|
+
)
|
|
543
|
+
if method_norm == "mad":
|
|
544
|
+
return robust_background_mad_stack(
|
|
545
|
+
frame_iter,
|
|
546
|
+
q_bg=q_bg,
|
|
547
|
+
k_sigma=k_sigma,
|
|
548
|
+
min_keep=min_keep,
|
|
549
|
+
out_dtype=np.uint16,
|
|
550
|
+
)
|
|
551
|
+
if method_norm == "topk":
|
|
552
|
+
return robust_background_topk(
|
|
553
|
+
frame_iter,
|
|
554
|
+
frame_count=frame_count,
|
|
555
|
+
q_bg=q_bg,
|
|
556
|
+
min_keep=min_keep,
|
|
557
|
+
max_keep=max_keep,
|
|
558
|
+
out_dtype=np.uint16,
|
|
559
|
+
)
|
|
560
|
+
raise ValueError("method must be one of: 'auto', 'mad', 'topk'")
|
|
561
|
+
|
|
562
|
+
def load_frames_batch(self, start_frame: int, count: int) -> np.ndarray:
|
|
563
|
+
"""Load `count` consecutive frames into one stacked array.
|
|
564
|
+
|
|
565
|
+
Parameters
|
|
566
|
+
----------
|
|
567
|
+
start_frame:
|
|
568
|
+
First global frame number to include.
|
|
569
|
+
count:
|
|
570
|
+
Number of consecutive frames to load.
|
|
571
|
+
|
|
572
|
+
Returns
|
|
573
|
+
-------
|
|
574
|
+
numpy.ndarray
|
|
575
|
+
Stacked array with frame dimension on the last axis.
|
|
576
|
+
Mono/raw CFA: `[H, W, N]`; debayered/interpolated color:
|
|
577
|
+
`[H, W, 3, N]`.
|
|
578
|
+
"""
|
|
579
|
+
if count <= 0:
|
|
580
|
+
raise ValueError("count must be > 0")
|
|
581
|
+
stop_frame = start_frame + count - 1
|
|
582
|
+
self._validate_frame_range(start_frame, stop_frame)
|
|
583
|
+
|
|
584
|
+
self.load_frame(start_frame)
|
|
585
|
+
first = self._require_pixel_array().copy()
|
|
586
|
+
out = np.empty(first.shape + (count,), dtype=first.dtype)
|
|
587
|
+
out[..., 0] = first
|
|
588
|
+
|
|
589
|
+
for idx, frame_no in enumerate(range(start_frame + 1, stop_frame + 1), start=1):
|
|
590
|
+
self.load_frame(frame_no)
|
|
591
|
+
out[..., idx] = self._require_pixel_array()
|
|
592
|
+
return out
|
|
593
|
+
|
|
594
|
+
def get_frame_rgb(self, image_no: int | None = None, *, bayer_pattern: str = "auto") -> np.ndarray:
|
|
595
|
+
"""Return current or selected frame as RGB.
|
|
596
|
+
|
|
597
|
+
Parameters
|
|
598
|
+
----------
|
|
599
|
+
image_no:
|
|
600
|
+
Optional global frame number to load before conversion.
|
|
601
|
+
bayer_pattern:
|
|
602
|
+
Bayer layout token for mono demosaic (`RGGB`, `BGGR`, `GRBG`, `GBRG`).
|
|
603
|
+
Use `"auto"` to infer from setup `CFA`.
|
|
604
|
+
|
|
605
|
+
Returns
|
|
606
|
+
-------
|
|
607
|
+
numpy.ndarray
|
|
608
|
+
RGB frame.
|
|
609
|
+
"""
|
|
610
|
+
if image_no is not None:
|
|
611
|
+
self.load_frame(image_no)
|
|
612
|
+
|
|
613
|
+
frame = self._require_pixel_array()
|
|
614
|
+
if frame.ndim == 3:
|
|
615
|
+
if self._pixel_array_channel_order == "BGR":
|
|
616
|
+
return frame[..., ::-1].copy()
|
|
617
|
+
return frame.copy()
|
|
618
|
+
if frame.ndim == 2:
|
|
619
|
+
pattern = self._resolve_bayer_pattern(bayer_pattern) or "RGGB"
|
|
620
|
+
return demosaic_bilinear(frame, pattern=pattern)
|
|
621
|
+
raise ValueError("Unsupported frame shape for RGB conversion")
|
|
622
|
+
|
|
623
|
+
def _decode_frame(self, raw: bytes) -> np.ndarray:
|
|
624
|
+
image_header = self._require_image_header()
|
|
625
|
+
setup = self._require_camera_setup()
|
|
626
|
+
return decode_frame_payload(
|
|
627
|
+
raw,
|
|
628
|
+
bit_count=int(image_header.biBitCount),
|
|
629
|
+
width=int(image_header.biWidth),
|
|
630
|
+
height_signed=int(image_header.biHeight),
|
|
631
|
+
real_bpp=int(setup.RealBPP),
|
|
632
|
+
unpack_10bit_fn=unpack_10bit_data,
|
|
633
|
+
)
|
|
634
|
+
|
|
635
|
+
def _repair_dead_pixels_array(
|
|
636
|
+
self,
|
|
637
|
+
frame: np.ndarray,
|
|
638
|
+
*,
|
|
639
|
+
dead_value: int | None = None,
|
|
640
|
+
dead_is_threshold: bool | None = None,
|
|
641
|
+
) -> np.ndarray:
|
|
642
|
+
resolved_dead = self._resolve_dead_value(self.dead_value if dead_value is None else dead_value)
|
|
643
|
+
resolved_threshold = self.dead_is_threshold if dead_is_threshold is None else bool(dead_is_threshold)
|
|
644
|
+
return repair_dead_pixels(
|
|
645
|
+
frame,
|
|
646
|
+
dead_value=resolved_dead,
|
|
647
|
+
dead_is_threshold=resolved_threshold,
|
|
648
|
+
bayer_raw=self._is_raw_bayer_frame(frame),
|
|
649
|
+
)
|
|
650
|
+
|
|
651
|
+
def _debayer_array(self, frame: np.ndarray, *, bayer_pattern: str = "auto") -> np.ndarray:
|
|
652
|
+
pattern = self._resolve_bayer_pattern(bayer_pattern) or "RGGB"
|
|
653
|
+
return demosaic_bilinear(frame, pattern=pattern)
|
|
654
|
+
|
|
655
|
+
def _update_color_sample_arrays(self, frame: np.ndarray) -> None:
|
|
656
|
+
self._color_samples_from_raw_cfa = False
|
|
657
|
+
|
|
658
|
+
if self._is_raw_bayer_frame(frame):
|
|
659
|
+
pattern = self._resolve_bayer_pattern(self.bayer_pattern_mode) or "RGGB"
|
|
660
|
+
red, green, blue = self._raw_cfa_sample_arrays(frame.shape)
|
|
661
|
+
for row_phase, col_phase, channel in self._bayer_color_phases(pattern):
|
|
662
|
+
rows = slice(row_phase, None, 2)
|
|
663
|
+
cols = slice(col_phase, None, 2)
|
|
664
|
+
if channel == "R":
|
|
665
|
+
red[rows, cols] = frame[rows, cols]
|
|
666
|
+
elif channel == "G":
|
|
667
|
+
green[rows, cols] = frame[rows, cols]
|
|
668
|
+
else:
|
|
669
|
+
blue[rows, cols] = frame[rows, cols]
|
|
670
|
+
self.red_pixels = red
|
|
671
|
+
self.green_pixels = green
|
|
672
|
+
self.blue_pixels = blue
|
|
673
|
+
self._color_samples_from_raw_cfa = True
|
|
674
|
+
return
|
|
675
|
+
|
|
676
|
+
self.red_pixels = None
|
|
677
|
+
self.green_pixels = None
|
|
678
|
+
self.blue_pixels = None
|
|
679
|
+
|
|
680
|
+
if frame.ndim == 3 and frame.shape[-1] >= 3:
|
|
681
|
+
image_header = self._require_image_header()
|
|
682
|
+
channels = frame
|
|
683
|
+
if int(image_header.biBitCount) in (24, 48) and self._pixel_array_channel_order != "RGB":
|
|
684
|
+
channels = frame[..., ::-1]
|
|
685
|
+
self.red_pixels = channels[..., 0].astype(np.float32, copy=True)
|
|
686
|
+
self.green_pixels = channels[..., 1].astype(np.float32, copy=True)
|
|
687
|
+
self.blue_pixels = channels[..., 2].astype(np.float32, copy=True)
|
|
688
|
+
|
|
689
|
+
def _raw_cfa_sample_arrays(self, shape: tuple[int, int]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
|
|
690
|
+
arrays = []
|
|
691
|
+
for current in (self.red_pixels, self.green_pixels, self.blue_pixels):
|
|
692
|
+
if current is not None and current.shape == shape and current.dtype == np.float32:
|
|
693
|
+
sample = current
|
|
694
|
+
sample.fill(np.nan)
|
|
695
|
+
else:
|
|
696
|
+
sample = np.full(shape, np.nan, dtype=np.float32)
|
|
697
|
+
arrays.append(sample)
|
|
698
|
+
return arrays[0], arrays[1], arrays[2]
|
|
699
|
+
|
|
700
|
+
@staticmethod
|
|
701
|
+
def _bayer_color_phases(pattern: str) -> tuple[tuple[int, int, str], ...]:
|
|
702
|
+
token = pattern.upper()
|
|
703
|
+
mapping = {
|
|
704
|
+
"RGGB": ((0, 0, "R"), (0, 1, "G"), (1, 0, "G"), (1, 1, "B")),
|
|
705
|
+
"BGGR": ((0, 0, "B"), (0, 1, "G"), (1, 0, "G"), (1, 1, "R")),
|
|
706
|
+
"GRBG": ((0, 0, "G"), (0, 1, "R"), (1, 0, "B"), (1, 1, "G")),
|
|
707
|
+
"GBRG": ((0, 0, "G"), (0, 1, "B"), (1, 0, "R"), (1, 1, "G")),
|
|
708
|
+
}
|
|
709
|
+
try:
|
|
710
|
+
return mapping[token]
|
|
711
|
+
except KeyError as exc:
|
|
712
|
+
raise ValueError(f"Unsupported Bayer pattern: {pattern}") from exc
|
|
713
|
+
|
|
714
|
+
def _decoded_channel_order(self, frame: np.ndarray) -> str | None:
|
|
715
|
+
if frame.ndim != 3:
|
|
716
|
+
return None
|
|
717
|
+
image_header = self._require_image_header()
|
|
718
|
+
if int(image_header.biBitCount) in (24, 48):
|
|
719
|
+
return "BGR"
|
|
720
|
+
return "RGB"
|
|
721
|
+
|
|
722
|
+
def _validate_frame_range(self, start_frame: int, end_frame: int) -> tuple[int, int]:
|
|
723
|
+
header = self._require_file_header()
|
|
724
|
+
first = int(header.FirstImageNo)
|
|
725
|
+
last = first + int(header.ImageCount) - 1
|
|
726
|
+
if start_frame < first or end_frame > last or end_frame < start_frame:
|
|
727
|
+
raise ValueError("Frame range out of bounds.")
|
|
728
|
+
return first, last
|
|
729
|
+
|
|
730
|
+
def _iter_loaded_frames(
|
|
731
|
+
self,
|
|
732
|
+
start_frame: int,
|
|
733
|
+
end_frame: int,
|
|
734
|
+
*,
|
|
735
|
+
replace_dead_pixels: bool = False,
|
|
736
|
+
) -> Iterator[np.ndarray]:
|
|
737
|
+
"""Yield decoded frame arrays over `[start_frame, end_frame]`."""
|
|
738
|
+
load_frame = self.load_frame
|
|
739
|
+
replace = self.replace_dead_pixels
|
|
740
|
+
for frame_no in range(start_frame, end_frame + 1):
|
|
741
|
+
load_frame(frame_no)
|
|
742
|
+
if replace_dead_pixels and not self.remove_dead_pixels:
|
|
743
|
+
replace()
|
|
744
|
+
yield self._require_pixel_array()
|
|
745
|
+
|
|
746
|
+
def _is_raw_bayer_frame(self, frame: np.ndarray) -> bool:
|
|
747
|
+
"""Return True when frame is 2D and setup indicates uninterpolated color."""
|
|
748
|
+
if frame.ndim != 2:
|
|
749
|
+
return False
|
|
750
|
+
image_header = self._require_image_header()
|
|
751
|
+
if int(image_header.biBitCount) not in (8, 16):
|
|
752
|
+
return False
|
|
753
|
+
setup = self._require_camera_setup()
|
|
754
|
+
return bool(getattr(setup, "bEnableColor", False)) and self.cfa_code != 0
|
|
755
|
+
|
|
756
|
+
def _resolve_bayer_pattern(self, bayer_pattern: str = "auto") -> str | None:
|
|
757
|
+
"""Resolve Bayer pattern from explicit token or setup CFA code."""
|
|
758
|
+
token = bayer_pattern.upper().strip()
|
|
759
|
+
if token != "AUTO":
|
|
760
|
+
if token not in {"RGGB", "BGGR", "GRBG", "GBRG"}:
|
|
761
|
+
raise ValueError("bayer_pattern must be one of: auto, RGGB, BGGR, GRBG, GBRG")
|
|
762
|
+
return token
|
|
763
|
+
|
|
764
|
+
cfa = self.cfa_code
|
|
765
|
+
mapping = {
|
|
766
|
+
0: None, # CFA_NONE
|
|
767
|
+
1: "GBRG", # CFA_VRI (gbrg/rggb variants; best-effort default)
|
|
768
|
+
2: "BGGR", # CFA_VRIV6 (bggr/grbg variants; best-effort default)
|
|
769
|
+
3: "GBRG", # CFA_BAYER (gb/rg)
|
|
770
|
+
4: "RGGB", # CFA_BAYERFLIP (rg/gb)
|
|
771
|
+
5: "GRBG", # CFA_BAYERFLIPB (gr/bg variant)
|
|
772
|
+
6: "BGGR", # CFA_BAYERFLIPH (bg/gr)
|
|
773
|
+
}
|
|
774
|
+
return mapping.get(cfa, None)
|
|
775
|
+
|
|
776
|
+
def _resolve_dead_value(self, dead_value: int | None) -> int:
|
|
777
|
+
"""Infer dead-pixel threshold from setup metadata when not provided."""
|
|
778
|
+
if dead_value is not None:
|
|
779
|
+
return int(dead_value)
|
|
780
|
+
|
|
781
|
+
setup = self._require_camera_setup()
|
|
782
|
+
white_level = int(getattr(setup, "WhiteLevel", -1))
|
|
783
|
+
if white_level >= 0:
|
|
784
|
+
return white_level + 1
|
|
785
|
+
|
|
786
|
+
real_bpp = int(getattr(setup, "RealBPP", 0))
|
|
787
|
+
if real_bpp > 0:
|
|
788
|
+
return (1 << real_bpp) - 1
|
|
789
|
+
|
|
790
|
+
frame = self._require_pixel_array()
|
|
791
|
+
if np.issubdtype(frame.dtype, np.integer):
|
|
792
|
+
return int(np.iinfo(frame.dtype).max)
|
|
793
|
+
return 4095
|
|
794
|
+
|
|
795
|
+
@staticmethod
|
|
796
|
+
def _decode_recording_datetime(trigger_time: int, recording_tz_minutes: int) -> datetime | None:
|
|
797
|
+
"""Decode CINE `TriggerTime` token to timezone-aware datetime when possible."""
|
|
798
|
+
seconds = int(trigger_time >> 32)
|
|
799
|
+
frac = int(trigger_time & 0xFFFFFFFF)
|
|
800
|
+
if seconds <= 0:
|
|
801
|
+
return None
|
|
802
|
+
|
|
803
|
+
try:
|
|
804
|
+
dt_utc = datetime.fromtimestamp(seconds, tz=timezone.utc)
|
|
805
|
+
except (OverflowError, OSError, ValueError):
|
|
806
|
+
return None
|
|
807
|
+
|
|
808
|
+
micros = int(round((frac / float(1 << 32)) * 1_000_000.0))
|
|
809
|
+
if micros >= 1_000_000:
|
|
810
|
+
dt_utc += timedelta(seconds=1)
|
|
811
|
+
micros -= 1_000_000
|
|
812
|
+
dt_utc = dt_utc.replace(microsecond=micros)
|
|
813
|
+
|
|
814
|
+
if abs(int(recording_tz_minutes)) > 24 * 60:
|
|
815
|
+
return dt_utc
|
|
816
|
+
tzinfo = timezone(timedelta(minutes=int(recording_tz_minutes)))
|
|
817
|
+
return dt_utc.astimezone(tzinfo)
|
|
818
|
+
|
|
819
|
+
def _require_file_handle(self) -> BinaryIO:
|
|
820
|
+
if self.file_handle is None:
|
|
821
|
+
raise RuntimeError("No CINE file is open.")
|
|
822
|
+
return self.file_handle
|
|
823
|
+
|
|
824
|
+
def _require_file_header(self) -> CineHeader:
|
|
825
|
+
if self.file_header is None:
|
|
826
|
+
raise RuntimeError("File header is not loaded.")
|
|
827
|
+
return self.file_header
|
|
828
|
+
|
|
829
|
+
def _require_image_header(self) -> BitmapHeader:
|
|
830
|
+
if self.image_header is None:
|
|
831
|
+
raise RuntimeError("Image header is not loaded.")
|
|
832
|
+
return self.image_header
|
|
833
|
+
|
|
834
|
+
def _require_camera_setup(self) -> Setup:
|
|
835
|
+
if self.camera_setup is None:
|
|
836
|
+
raise RuntimeError("Camera setup is not loaded.")
|
|
837
|
+
return self.camera_setup
|
|
838
|
+
|
|
839
|
+
def _require_image_locations(self) -> ImageOffsets:
|
|
840
|
+
if self.image_locations is None:
|
|
841
|
+
raise RuntimeError("Image offsets are not loaded.")
|
|
842
|
+
return self.image_locations
|
|
843
|
+
|
|
844
|
+
def _require_pixel_array(self) -> np.ndarray:
|
|
845
|
+
if self.pixel_array is None:
|
|
846
|
+
raise RuntimeError("No frame loaded.")
|
|
847
|
+
return self.pixel_array
|