cine-handler 0.1.1__tar.gz

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.
Files changed (32) hide show
  1. cine_handler-0.1.1/MANIFEST.in +19 -0
  2. cine_handler-0.1.1/PKG-INFO +358 -0
  3. cine_handler-0.1.1/PYPI.md +329 -0
  4. cine_handler-0.1.1/README.md +140 -0
  5. cine_handler-0.1.1/pyproject.toml +58 -0
  6. cine_handler-0.1.1/pytest.ini +3 -0
  7. cine_handler-0.1.1/python/API.md +105 -0
  8. cine_handler-0.1.1/python/README.md +208 -0
  9. cine_handler-0.1.1/python/examples/basic_usage.py +40 -0
  10. cine_handler-0.1.1/python/examples/performance_test.py +72 -0
  11. cine_handler-0.1.1/python/examples/trim_and_background.py +24 -0
  12. cine_handler-0.1.1/python/src/cine_handler.egg-info/SOURCES.txt +29 -0
  13. cine_handler-0.1.1/python/src/cine_reader/__init__.py +31 -0
  14. cine_handler-0.1.1/python/src/cine_reader/_lookup.py +72 -0
  15. cine_handler-0.1.1/python/src/cine_reader/cine.py +847 -0
  16. cine_handler-0.1.1/python/src/cine_reader/frame_decode.py +91 -0
  17. cine_handler-0.1.1/python/src/cine_reader/headers.py +452 -0
  18. cine_handler-0.1.1/python/src/cine_reader/image_ops.py +285 -0
  19. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_arm64.dylib +0 -0
  20. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_elf64.so +0 -0
  21. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_win32.dll +0 -0
  22. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_win64.dll +0 -0
  23. cine_handler-0.1.1/python/src/cine_reader/py.typed +0 -0
  24. cine_handler-0.1.1/python/src/cine_reader/stats.py +161 -0
  25. cine_handler-0.1.1/python/src/cine_reader/unpack.py +139 -0
  26. cine_handler-0.1.1/python/tests/test_cine_processing.py +72 -0
  27. cine_handler-0.1.1/python/tests/test_cine_smoke.py +44 -0
  28. cine_handler-0.1.1/python/tests/test_frame_decode.py +68 -0
  29. cine_handler-0.1.1/python/tests/test_image_ops.py +96 -0
  30. cine_handler-0.1.1/python/tests/test_stats.py +45 -0
  31. cine_handler-0.1.1/python/tests/test_unpack.py +46 -0
  32. cine_handler-0.1.1/setup.cfg +4 -0
@@ -0,0 +1,19 @@
1
+ include README.md
2
+ include PYPI.md
3
+ include pyproject.toml
4
+ include pytest.ini
5
+ graft python/src
6
+ graft python/examples
7
+ graft python/tests
8
+ include python/README.md
9
+ include python/API.md
10
+ prune python/src/cine_reader.egg-info
11
+ prune python/src/cine_handler.egg-info
12
+ prune Matlab
13
+ prune c_src
14
+ prune docs
15
+ prune release
16
+ prune sample_data
17
+ global-exclude __pycache__
18
+ global-exclude *.py[cod]
19
+ global-exclude .DS_Store
@@ -0,0 +1,358 @@
1
+ Metadata-Version: 2.4
2
+ Name: cine-handler
3
+ Version: 0.1.1
4
+ Summary: Cross-platform Python reader for Vision Research Phantom .cine files
5
+ Author: Rees Verleur
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/rverleur/cine-reader
8
+ Project-URL: Repository, https://github.com/rverleur/cine-reader
9
+ Project-URL: Documentation, https://github.com/rverleur/cine-reader/blob/main/python/API.md
10
+ Project-URL: Issues, https://github.com/rverleur/cine-reader/issues
11
+ Project-URL: Releases, https://github.com/rverleur/cine-reader/releases
12
+ Project-URL: MATLAB Implementation, https://github.com/rverleur/cine-reader/tree/main/Matlab
13
+ Keywords: phantom,cine,high-speed-camera,imaging
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Operating System :: Microsoft :: Windows
18
+ Classifier: Operating System :: POSIX :: Linux
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Topic :: Scientific/Engineering :: Image Processing
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ Requires-Dist: numpy>=1.24
25
+ Provides-Extra: dev
26
+ Requires-Dist: build>=1.2; extra == "dev"
27
+ Requires-Dist: pytest>=8.0; extra == "dev"
28
+ Requires-Dist: twine>=5.0; extra == "dev"
29
+
30
+ # cine-handler
31
+
32
+ `cine-handler` is the PyPI distribution for the `cine_reader` Python package,
33
+ which reads Vision Research Phantom `.cine` files on macOS, Linux, and
34
+ Windows.
35
+
36
+ The PyPI distribution contains only the Python package. The repository also
37
+ includes a separate MATLAB implementation that stays in GitHub:
38
+
39
+ - Repository: <https://github.com/rverleur/cine-reader>
40
+ - MATLAB implementation: <https://github.com/rverleur/cine-reader/tree/main/Matlab>
41
+ - Python examples: <https://github.com/rverleur/cine-reader/tree/main/python/examples>
42
+ - Python API notes: <https://github.com/rverleur/cine-reader/blob/main/python/API.md>
43
+
44
+ ## Installation
45
+
46
+ Install from PyPI:
47
+
48
+ ```bash
49
+ pip install cine-handler
50
+ ```
51
+
52
+ Development install from GitHub:
53
+
54
+ ```bash
55
+ pip install "git+https://github.com/rverleur/cine-reader.git"
56
+ ```
57
+
58
+ Editable install from a local checkout:
59
+
60
+ ```bash
61
+ pip install -e .[dev]
62
+ ```
63
+
64
+ ## What The Package Provides
65
+
66
+ - High-level `Cine` reader for file metadata, frame access, frame iteration,
67
+ trimming, and simple processing.
68
+ - Packed 10-bit decode with bundled native helpers and a NumPy fallback.
69
+ - Dead-pixel repair helpers for mono, Bayer/CFA, and RGB image arrays.
70
+ - Bilinear Bayer demosaic for raw color sensor frames.
71
+ - Low-memory frame statistics helpers for averaging and robust background
72
+ estimation.
73
+
74
+ ## Quick Start
75
+
76
+ ```python
77
+ from pathlib import Path
78
+
79
+ from cine_reader import Cine
80
+
81
+ cine_path = Path("my_capture.cine")
82
+
83
+ with Cine(cine_path) as cine:
84
+ print("frames:", cine.total_frames)
85
+ print("range:", cine.first_frame_number, cine.last_frame_number)
86
+ print("frame rate:", cine.frame_rate)
87
+ print("exposure (s):", cine.exposure_time_seconds)
88
+
89
+ cine.load_frame(cine.first_frame_number)
90
+ raw_frame = cine.frame
91
+
92
+ rgb_frame = cine.get_frame_rgb()
93
+ average = cine.average_frames(cine.first_frame_number, cine.first_frame_number + 9)
94
+ background = cine.mode_frames(cine.first_frame_number, cine.first_frame_number + 19)
95
+ ```
96
+
97
+ ## Frame And Color Behavior
98
+
99
+ - Mono cines load as 2D arrays.
100
+ - Raw color CFA/Bayer cines load as 2D sensor mosaics by default.
101
+ - Interpolated 24-bit and 48-bit color payloads load as 3-channel arrays.
102
+ - Set `debayer=True` on `Cine(...)` or call `debayer_frame()` to convert raw CFA
103
+ frames to RGB.
104
+ - Set `remove_dead_pixels=True` on `Cine(...)` or call `replace_dead_pixels()`
105
+ to repair dead pixels.
106
+ - `red_pixels`, `green_pixels`, and `blue_pixels` expose raw CFA sensor samples
107
+ for Bayer frames, using `NaN` at non-matching locations.
108
+
109
+ ## The `Cine` Class
110
+
111
+ ### Constructor
112
+
113
+ ```python
114
+ Cine(
115
+ filename,
116
+ keep_annotations=True,
117
+ remove_dead_pixels=False,
118
+ debayer=False,
119
+ dead_value=None,
120
+ dead_is_threshold=True,
121
+ bayer_pattern="auto",
122
+ )
123
+ ```
124
+
125
+ - `filename`: path to a `.cine` file.
126
+ - `keep_annotations`: keep annotation block bytes in `annotation_data` and
127
+ `annotation`.
128
+ - `remove_dead_pixels`: repair dead pixels on each `load_frame`.
129
+ - `debayer`: debayer raw CFA/Bayer frames on each `load_frame`.
130
+ - `dead_value`: optional dead-pixel marker or threshold. If omitted, the value
131
+ is inferred from camera metadata.
132
+ - `dead_is_threshold`: when `True`, values greater than or equal to
133
+ `dead_value` are treated as dead pixels.
134
+ - `bayer_pattern`: `"auto"`, `"RGGB"`, `"BGGR"`, `"GRBG"`, or `"GBRG"`.
135
+
136
+ ### Reader Lifecycle
137
+
138
+ - `open_cine_file(filename)`: reopen a `.cine` file and parse the top-level
139
+ metadata blocks.
140
+ - `close_file()`: close the active file handle.
141
+ - Context manager support: `with Cine(path) as cine: ...`
142
+
143
+ ### Metadata And Aliases
144
+
145
+ These properties are the most useful entry points for file metadata:
146
+
147
+ - `first_frame_number`
148
+ - `total_frames`
149
+ - `last_frame_number`
150
+ - `frame_rate`
151
+ - `exposure_time_ns`
152
+ - `exposure_time_seconds`
153
+ - `exposure_time`
154
+ - `recording_datetime`
155
+ - `recording_date`
156
+ - `cfa_code`
157
+ - `bayer_pattern`
158
+
159
+ The specification-aligned metadata objects are also available directly:
160
+
161
+ - `file_header` as `CineHeader`
162
+ - `image_header` as `BitmapHeader`
163
+ - `camera_setup` as `Setup`
164
+ - `image_locations` as `ImageOffsets`
165
+
166
+ ### Frame Access
167
+
168
+ - `load_frame(image_no, convert_bgr_to_rgb=False)`
169
+ - Loads a single frame by global frame number.
170
+ - `convert_bgr_to_rgb=True` converts 3-channel payloads to RGB on load.
171
+ - `next_frame(increment=1, convert_bgr_to_rgb=False)`
172
+ - Loads the next frame relative to `current_frame`.
173
+ - Negative increments are allowed.
174
+ - `frame` and `image`
175
+ - Aliases for the currently loaded NumPy array.
176
+ - `get_frame_rgb(image_no=None, bayer_pattern="auto")`
177
+ - Returns the current frame, or a selected frame, as RGB.
178
+ - Raw CFA/Bayer frames are demosaiced first.
179
+
180
+ Example:
181
+
182
+ ```python
183
+ with Cine("capture.cine") as cine:
184
+ cine.load_frame(cine.first_frame_number)
185
+ raw = cine.frame
186
+ rgb = cine.get_frame_rgb()
187
+ ```
188
+
189
+ ### Pixel Repair And Demosaic
190
+
191
+ - `replace_dead_pixels(dead_value=None, dead_is_threshold=True)`
192
+ - Repairs dead pixels on the current frame.
193
+ - Works for mono, raw Bayer/CFA, and RGB data.
194
+ - `debayer_frame(bayer_pattern="auto")`
195
+ - Converts the current raw CFA/Bayer frame to RGB in place.
196
+
197
+ Example:
198
+
199
+ ```python
200
+ with Cine("capture.cine") as cine:
201
+ cine.load_frame(cine.first_frame_number)
202
+ cine.replace_dead_pixels()
203
+ cine.debayer_frame()
204
+ rgb = cine.frame
205
+ ```
206
+
207
+ ### Multi-Frame Operations
208
+
209
+ - `average_frames(start_frame, end_frame, replace_dead_pixels=False, chunk_size=8)`
210
+ - Computes a per-pixel average over an inclusive frame range.
211
+ - `mode_frames(start_frame, end_frame, replace_dead_pixels=False, method="auto", q_bg=0.80, k_sigma=2.5, min_keep=3, max_keep=96, stack_limit=128)`
212
+ - Computes a robust bright-background estimate.
213
+ - `method="mad"` uses a full-stack quantile/MAD estimator.
214
+ - `method="topk"` uses a bounded-memory top-k estimator.
215
+ - `method="auto"` chooses between them from the range length.
216
+ - `load_frames_batch(start_frame, count)`
217
+ - Loads consecutive frames into one stacked array.
218
+ - Output shape is `[H, W, N]` for mono/raw CFA and `[H, W, 3, N]` for color.
219
+ - `save_frames_to_new_file(output_filename, start_frame, end_frame)`
220
+ - Writes a trimmed `.cine` file for an inclusive frame range.
221
+
222
+ Example:
223
+
224
+ ```python
225
+ with Cine("capture.cine") as cine:
226
+ first = cine.first_frame_number
227
+ last = min(first + 49, cine.last_frame_number)
228
+
229
+ avg = cine.average_frames(first, last, chunk_size=8)
230
+ bg = cine.mode_frames(first, last, method="topk")
231
+ batch = cine.load_frames_batch(first, 5)
232
+ cine.save_frames_to_new_file("trimmed.cine", first, last)
233
+ ```
234
+
235
+ ## Standalone Helper Functions
236
+
237
+ ### Packed 10-bit Decode
238
+
239
+ - `unpack_10bit_data(data)`
240
+ - Decodes Phantom packed 10-bit payloads.
241
+ - Uses a bundled native unpack helper when one is available.
242
+ - Falls back to NumPy automatically.
243
+ - `unpack_10bit_numpy(data)`
244
+ - Pure-NumPy packed 10-bit decoder.
245
+
246
+ To force the NumPy path:
247
+
248
+ ```bash
249
+ export CINE_READER_DISABLE_C_UNPACK=1
250
+ ```
251
+
252
+ ### Dead-Pixel Repair
253
+
254
+ - `replace_dead_pixels(frame, dead_value=4095, dead_is_threshold=False, bayer_raw=False)`
255
+ - Dispatches to the right repair strategy for mono, Bayer, or RGB input.
256
+ - `replace_dead_pixels_mono(frame, dead_value=4095, dead_is_threshold=False)`
257
+ - Repairs dead pixels in a 2D mono frame from valid 8-neighbor values.
258
+ - `replace_dead_pixels_bayer(frame, dead_value=4095, dead_is_threshold=False)`
259
+ - Repairs a 2D raw Bayer/CFA frame phase-by-phase before demosaic.
260
+ - `replace_dead_pixels_rgb(frame, dead_value=4095, dead_is_threshold=False)`
261
+ - Repairs each color channel independently in a 3D image.
262
+
263
+ Example:
264
+
265
+ ```python
266
+ from cine_reader import replace_dead_pixels_bayer
267
+
268
+ clean = replace_dead_pixels_bayer(raw_bayer_frame, dead_value=4095)
269
+ ```
270
+
271
+ ### Demosaic
272
+
273
+ - `demosaic_bilinear(frame, pattern="RGGB")`
274
+ - Bilinear Bayer demosaic for raw CFA frames.
275
+ - Supported patterns are `"RGGB"`, `"BGGR"`, `"GRBG"`, and `"GBRG"`.
276
+
277
+ Example:
278
+
279
+ ```python
280
+ from cine_reader import demosaic_bilinear
281
+
282
+ rgb = demosaic_bilinear(raw_bayer_frame, pattern="RGGB")
283
+ ```
284
+
285
+ ### Frame Statistics
286
+
287
+ - `average_from_frame_iter(frames, out_dtype=None, chunk_size=8)`
288
+ - Computes a per-pixel mean from an iterable of equally shaped frames.
289
+ - Returns `(average_frame, frame_count)`.
290
+ - `robust_background_mad_stack(frames, q_bg=0.80, k_sigma=2.5, min_keep=3, out_dtype=np.uint16)`
291
+ - Full-stack bright-background estimator based on quantile and MAD rejection.
292
+ - `robust_background_topk(frames, frame_count, q_bg=0.80, min_keep=3, max_keep=96, out_dtype=np.uint16)`
293
+ - Bounded-memory bright-background estimator that keeps the top-k samples per
294
+ pixel.
295
+
296
+ Example:
297
+
298
+ ```python
299
+ from cine_reader import average_from_frame_iter, robust_background_topk
300
+
301
+ avg, count = average_from_frame_iter(frames, chunk_size=16)
302
+ bg = robust_background_topk(frames, frame_count=count, q_bg=0.80)
303
+ ```
304
+
305
+ ## Metadata Classes
306
+
307
+ These classes are returned by the reader for direct access to CINE metadata:
308
+
309
+ - `CineHeader`
310
+ - File header fields such as `FirstImageNo`, `ImageCount`, and
311
+ `OffImageOffsets`.
312
+ - `BitmapHeader`
313
+ - Image header fields such as `biWidth`, `biHeight`, and `biBitCount`.
314
+ - `ImageOffsets`
315
+ - Frame byte-offset table as `pImage`.
316
+ - `Setup`
317
+ - Camera setup metadata including frame rate, exposure, bit depth, color
318
+ flags, and descriptive strings.
319
+
320
+ Example:
321
+
322
+ ```python
323
+ with Cine("capture.cine") as cine:
324
+ print(cine.file_header.FirstImageNo)
325
+ print(cine.image_header.biWidth, cine.image_header.biHeight)
326
+ print(cine.camera_setup.FrameRate, cine.camera_setup.RealBPP)
327
+ ```
328
+
329
+ ## Included Native Helpers
330
+
331
+ The wheel ships with runtime unpack libraries for packed 10-bit payloads:
332
+
333
+ - `unpack_data_win32.dll`
334
+ - `unpack_data_win64.dll`
335
+ - `unpack_data_elf64.so`
336
+ - `unpack_data_arm64.dylib`
337
+
338
+ If no matching helper can be loaded, `cine-handler` falls back to the NumPy
339
+ decoder automatically.
340
+
341
+ ## MATLAB Implementation
342
+
343
+ The PyPI package is intentionally Python-only. If you also need the MATLAB
344
+ reader, use the same GitHub repository:
345
+
346
+ - MATLAB package entry point:
347
+ <https://github.com/rverleur/cine-reader/blob/main/Matlab/Cine.m>
348
+ - MATLAB setup and examples:
349
+ <https://github.com/rverleur/cine-reader/blob/main/Matlab/README.md>
350
+
351
+ ## More Examples
352
+
353
+ - Basic usage:
354
+ <https://github.com/rverleur/cine-reader/blob/main/python/examples/basic_usage.py>
355
+ - Trimming and background estimation:
356
+ <https://github.com/rverleur/cine-reader/blob/main/python/examples/trim_and_background.py>
357
+ - Performance test:
358
+ <https://github.com/rverleur/cine-reader/blob/main/python/examples/performance_test.py>
@@ -0,0 +1,329 @@
1
+ # cine-handler
2
+
3
+ `cine-handler` is the PyPI distribution for the `cine_reader` Python package,
4
+ which reads Vision Research Phantom `.cine` files on macOS, Linux, and
5
+ Windows.
6
+
7
+ The PyPI distribution contains only the Python package. The repository also
8
+ includes a separate MATLAB implementation that stays in GitHub:
9
+
10
+ - Repository: <https://github.com/rverleur/cine-reader>
11
+ - MATLAB implementation: <https://github.com/rverleur/cine-reader/tree/main/Matlab>
12
+ - Python examples: <https://github.com/rverleur/cine-reader/tree/main/python/examples>
13
+ - Python API notes: <https://github.com/rverleur/cine-reader/blob/main/python/API.md>
14
+
15
+ ## Installation
16
+
17
+ Install from PyPI:
18
+
19
+ ```bash
20
+ pip install cine-handler
21
+ ```
22
+
23
+ Development install from GitHub:
24
+
25
+ ```bash
26
+ pip install "git+https://github.com/rverleur/cine-reader.git"
27
+ ```
28
+
29
+ Editable install from a local checkout:
30
+
31
+ ```bash
32
+ pip install -e .[dev]
33
+ ```
34
+
35
+ ## What The Package Provides
36
+
37
+ - High-level `Cine` reader for file metadata, frame access, frame iteration,
38
+ trimming, and simple processing.
39
+ - Packed 10-bit decode with bundled native helpers and a NumPy fallback.
40
+ - Dead-pixel repair helpers for mono, Bayer/CFA, and RGB image arrays.
41
+ - Bilinear Bayer demosaic for raw color sensor frames.
42
+ - Low-memory frame statistics helpers for averaging and robust background
43
+ estimation.
44
+
45
+ ## Quick Start
46
+
47
+ ```python
48
+ from pathlib import Path
49
+
50
+ from cine_reader import Cine
51
+
52
+ cine_path = Path("my_capture.cine")
53
+
54
+ with Cine(cine_path) as cine:
55
+ print("frames:", cine.total_frames)
56
+ print("range:", cine.first_frame_number, cine.last_frame_number)
57
+ print("frame rate:", cine.frame_rate)
58
+ print("exposure (s):", cine.exposure_time_seconds)
59
+
60
+ cine.load_frame(cine.first_frame_number)
61
+ raw_frame = cine.frame
62
+
63
+ rgb_frame = cine.get_frame_rgb()
64
+ average = cine.average_frames(cine.first_frame_number, cine.first_frame_number + 9)
65
+ background = cine.mode_frames(cine.first_frame_number, cine.first_frame_number + 19)
66
+ ```
67
+
68
+ ## Frame And Color Behavior
69
+
70
+ - Mono cines load as 2D arrays.
71
+ - Raw color CFA/Bayer cines load as 2D sensor mosaics by default.
72
+ - Interpolated 24-bit and 48-bit color payloads load as 3-channel arrays.
73
+ - Set `debayer=True` on `Cine(...)` or call `debayer_frame()` to convert raw CFA
74
+ frames to RGB.
75
+ - Set `remove_dead_pixels=True` on `Cine(...)` or call `replace_dead_pixels()`
76
+ to repair dead pixels.
77
+ - `red_pixels`, `green_pixels`, and `blue_pixels` expose raw CFA sensor samples
78
+ for Bayer frames, using `NaN` at non-matching locations.
79
+
80
+ ## The `Cine` Class
81
+
82
+ ### Constructor
83
+
84
+ ```python
85
+ Cine(
86
+ filename,
87
+ keep_annotations=True,
88
+ remove_dead_pixels=False,
89
+ debayer=False,
90
+ dead_value=None,
91
+ dead_is_threshold=True,
92
+ bayer_pattern="auto",
93
+ )
94
+ ```
95
+
96
+ - `filename`: path to a `.cine` file.
97
+ - `keep_annotations`: keep annotation block bytes in `annotation_data` and
98
+ `annotation`.
99
+ - `remove_dead_pixels`: repair dead pixels on each `load_frame`.
100
+ - `debayer`: debayer raw CFA/Bayer frames on each `load_frame`.
101
+ - `dead_value`: optional dead-pixel marker or threshold. If omitted, the value
102
+ is inferred from camera metadata.
103
+ - `dead_is_threshold`: when `True`, values greater than or equal to
104
+ `dead_value` are treated as dead pixels.
105
+ - `bayer_pattern`: `"auto"`, `"RGGB"`, `"BGGR"`, `"GRBG"`, or `"GBRG"`.
106
+
107
+ ### Reader Lifecycle
108
+
109
+ - `open_cine_file(filename)`: reopen a `.cine` file and parse the top-level
110
+ metadata blocks.
111
+ - `close_file()`: close the active file handle.
112
+ - Context manager support: `with Cine(path) as cine: ...`
113
+
114
+ ### Metadata And Aliases
115
+
116
+ These properties are the most useful entry points for file metadata:
117
+
118
+ - `first_frame_number`
119
+ - `total_frames`
120
+ - `last_frame_number`
121
+ - `frame_rate`
122
+ - `exposure_time_ns`
123
+ - `exposure_time_seconds`
124
+ - `exposure_time`
125
+ - `recording_datetime`
126
+ - `recording_date`
127
+ - `cfa_code`
128
+ - `bayer_pattern`
129
+
130
+ The specification-aligned metadata objects are also available directly:
131
+
132
+ - `file_header` as `CineHeader`
133
+ - `image_header` as `BitmapHeader`
134
+ - `camera_setup` as `Setup`
135
+ - `image_locations` as `ImageOffsets`
136
+
137
+ ### Frame Access
138
+
139
+ - `load_frame(image_no, convert_bgr_to_rgb=False)`
140
+ - Loads a single frame by global frame number.
141
+ - `convert_bgr_to_rgb=True` converts 3-channel payloads to RGB on load.
142
+ - `next_frame(increment=1, convert_bgr_to_rgb=False)`
143
+ - Loads the next frame relative to `current_frame`.
144
+ - Negative increments are allowed.
145
+ - `frame` and `image`
146
+ - Aliases for the currently loaded NumPy array.
147
+ - `get_frame_rgb(image_no=None, bayer_pattern="auto")`
148
+ - Returns the current frame, or a selected frame, as RGB.
149
+ - Raw CFA/Bayer frames are demosaiced first.
150
+
151
+ Example:
152
+
153
+ ```python
154
+ with Cine("capture.cine") as cine:
155
+ cine.load_frame(cine.first_frame_number)
156
+ raw = cine.frame
157
+ rgb = cine.get_frame_rgb()
158
+ ```
159
+
160
+ ### Pixel Repair And Demosaic
161
+
162
+ - `replace_dead_pixels(dead_value=None, dead_is_threshold=True)`
163
+ - Repairs dead pixels on the current frame.
164
+ - Works for mono, raw Bayer/CFA, and RGB data.
165
+ - `debayer_frame(bayer_pattern="auto")`
166
+ - Converts the current raw CFA/Bayer frame to RGB in place.
167
+
168
+ Example:
169
+
170
+ ```python
171
+ with Cine("capture.cine") as cine:
172
+ cine.load_frame(cine.first_frame_number)
173
+ cine.replace_dead_pixels()
174
+ cine.debayer_frame()
175
+ rgb = cine.frame
176
+ ```
177
+
178
+ ### Multi-Frame Operations
179
+
180
+ - `average_frames(start_frame, end_frame, replace_dead_pixels=False, chunk_size=8)`
181
+ - Computes a per-pixel average over an inclusive frame range.
182
+ - `mode_frames(start_frame, end_frame, replace_dead_pixels=False, method="auto", q_bg=0.80, k_sigma=2.5, min_keep=3, max_keep=96, stack_limit=128)`
183
+ - Computes a robust bright-background estimate.
184
+ - `method="mad"` uses a full-stack quantile/MAD estimator.
185
+ - `method="topk"` uses a bounded-memory top-k estimator.
186
+ - `method="auto"` chooses between them from the range length.
187
+ - `load_frames_batch(start_frame, count)`
188
+ - Loads consecutive frames into one stacked array.
189
+ - Output shape is `[H, W, N]` for mono/raw CFA and `[H, W, 3, N]` for color.
190
+ - `save_frames_to_new_file(output_filename, start_frame, end_frame)`
191
+ - Writes a trimmed `.cine` file for an inclusive frame range.
192
+
193
+ Example:
194
+
195
+ ```python
196
+ with Cine("capture.cine") as cine:
197
+ first = cine.first_frame_number
198
+ last = min(first + 49, cine.last_frame_number)
199
+
200
+ avg = cine.average_frames(first, last, chunk_size=8)
201
+ bg = cine.mode_frames(first, last, method="topk")
202
+ batch = cine.load_frames_batch(first, 5)
203
+ cine.save_frames_to_new_file("trimmed.cine", first, last)
204
+ ```
205
+
206
+ ## Standalone Helper Functions
207
+
208
+ ### Packed 10-bit Decode
209
+
210
+ - `unpack_10bit_data(data)`
211
+ - Decodes Phantom packed 10-bit payloads.
212
+ - Uses a bundled native unpack helper when one is available.
213
+ - Falls back to NumPy automatically.
214
+ - `unpack_10bit_numpy(data)`
215
+ - Pure-NumPy packed 10-bit decoder.
216
+
217
+ To force the NumPy path:
218
+
219
+ ```bash
220
+ export CINE_READER_DISABLE_C_UNPACK=1
221
+ ```
222
+
223
+ ### Dead-Pixel Repair
224
+
225
+ - `replace_dead_pixels(frame, dead_value=4095, dead_is_threshold=False, bayer_raw=False)`
226
+ - Dispatches to the right repair strategy for mono, Bayer, or RGB input.
227
+ - `replace_dead_pixels_mono(frame, dead_value=4095, dead_is_threshold=False)`
228
+ - Repairs dead pixels in a 2D mono frame from valid 8-neighbor values.
229
+ - `replace_dead_pixels_bayer(frame, dead_value=4095, dead_is_threshold=False)`
230
+ - Repairs a 2D raw Bayer/CFA frame phase-by-phase before demosaic.
231
+ - `replace_dead_pixels_rgb(frame, dead_value=4095, dead_is_threshold=False)`
232
+ - Repairs each color channel independently in a 3D image.
233
+
234
+ Example:
235
+
236
+ ```python
237
+ from cine_reader import replace_dead_pixels_bayer
238
+
239
+ clean = replace_dead_pixels_bayer(raw_bayer_frame, dead_value=4095)
240
+ ```
241
+
242
+ ### Demosaic
243
+
244
+ - `demosaic_bilinear(frame, pattern="RGGB")`
245
+ - Bilinear Bayer demosaic for raw CFA frames.
246
+ - Supported patterns are `"RGGB"`, `"BGGR"`, `"GRBG"`, and `"GBRG"`.
247
+
248
+ Example:
249
+
250
+ ```python
251
+ from cine_reader import demosaic_bilinear
252
+
253
+ rgb = demosaic_bilinear(raw_bayer_frame, pattern="RGGB")
254
+ ```
255
+
256
+ ### Frame Statistics
257
+
258
+ - `average_from_frame_iter(frames, out_dtype=None, chunk_size=8)`
259
+ - Computes a per-pixel mean from an iterable of equally shaped frames.
260
+ - Returns `(average_frame, frame_count)`.
261
+ - `robust_background_mad_stack(frames, q_bg=0.80, k_sigma=2.5, min_keep=3, out_dtype=np.uint16)`
262
+ - Full-stack bright-background estimator based on quantile and MAD rejection.
263
+ - `robust_background_topk(frames, frame_count, q_bg=0.80, min_keep=3, max_keep=96, out_dtype=np.uint16)`
264
+ - Bounded-memory bright-background estimator that keeps the top-k samples per
265
+ pixel.
266
+
267
+ Example:
268
+
269
+ ```python
270
+ from cine_reader import average_from_frame_iter, robust_background_topk
271
+
272
+ avg, count = average_from_frame_iter(frames, chunk_size=16)
273
+ bg = robust_background_topk(frames, frame_count=count, q_bg=0.80)
274
+ ```
275
+
276
+ ## Metadata Classes
277
+
278
+ These classes are returned by the reader for direct access to CINE metadata:
279
+
280
+ - `CineHeader`
281
+ - File header fields such as `FirstImageNo`, `ImageCount`, and
282
+ `OffImageOffsets`.
283
+ - `BitmapHeader`
284
+ - Image header fields such as `biWidth`, `biHeight`, and `biBitCount`.
285
+ - `ImageOffsets`
286
+ - Frame byte-offset table as `pImage`.
287
+ - `Setup`
288
+ - Camera setup metadata including frame rate, exposure, bit depth, color
289
+ flags, and descriptive strings.
290
+
291
+ Example:
292
+
293
+ ```python
294
+ with Cine("capture.cine") as cine:
295
+ print(cine.file_header.FirstImageNo)
296
+ print(cine.image_header.biWidth, cine.image_header.biHeight)
297
+ print(cine.camera_setup.FrameRate, cine.camera_setup.RealBPP)
298
+ ```
299
+
300
+ ## Included Native Helpers
301
+
302
+ The wheel ships with runtime unpack libraries for packed 10-bit payloads:
303
+
304
+ - `unpack_data_win32.dll`
305
+ - `unpack_data_win64.dll`
306
+ - `unpack_data_elf64.so`
307
+ - `unpack_data_arm64.dylib`
308
+
309
+ If no matching helper can be loaded, `cine-handler` falls back to the NumPy
310
+ decoder automatically.
311
+
312
+ ## MATLAB Implementation
313
+
314
+ The PyPI package is intentionally Python-only. If you also need the MATLAB
315
+ reader, use the same GitHub repository:
316
+
317
+ - MATLAB package entry point:
318
+ <https://github.com/rverleur/cine-reader/blob/main/Matlab/Cine.m>
319
+ - MATLAB setup and examples:
320
+ <https://github.com/rverleur/cine-reader/blob/main/Matlab/README.md>
321
+
322
+ ## More Examples
323
+
324
+ - Basic usage:
325
+ <https://github.com/rverleur/cine-reader/blob/main/python/examples/basic_usage.py>
326
+ - Trimming and background estimation:
327
+ <https://github.com/rverleur/cine-reader/blob/main/python/examples/trim_and_background.py>
328
+ - Performance test:
329
+ <https://github.com/rverleur/cine-reader/blob/main/python/examples/performance_test.py>