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