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_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