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.
@@ -0,0 +1,285 @@
1
+ """Image-space operations for CINE frame arrays."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+
7
+
8
+ _NEIGHBOR_OFFSETS = (
9
+ (-1, -1), (-1, 0), (-1, 1),
10
+ (0, -1), (0, 1),
11
+ (1, -1), (1, 0), (1, 1),
12
+ )
13
+
14
+ _BAYER_PHASE_ROLES = {
15
+ "RGGB": ((0, 0, "R"), (0, 1, "G_R"), (1, 0, "G_B"), (1, 1, "B")),
16
+ "BGGR": ((0, 0, "B"), (0, 1, "G_B"), (1, 0, "G_R"), (1, 1, "R")),
17
+ "GRBG": ((0, 0, "G_R"), (0, 1, "R"), (1, 0, "B"), (1, 1, "G_B")),
18
+ "GBRG": ((0, 0, "G_B"), (0, 1, "B"), (1, 0, "R"), (1, 1, "G_R")),
19
+ }
20
+
21
+
22
+ def _bayer_phase_roles(pattern: str) -> tuple[tuple[int, int, str], ...]:
23
+ token = pattern.upper()
24
+ try:
25
+ return _BAYER_PHASE_ROLES[token]
26
+ except KeyError as exc:
27
+ raise ValueError(f"Unsupported Bayer pattern: {pattern}") from exc
28
+
29
+
30
+ def _dead_mask(frame: np.ndarray, dead_value: int, *, dead_is_threshold: bool) -> np.ndarray:
31
+ if dead_is_threshold:
32
+ return frame >= dead_value
33
+ return frame == dead_value
34
+
35
+
36
+ def _repair_sparse_dead_pixels(frame: np.ndarray, dead_mask: np.ndarray, out: np.ndarray) -> None:
37
+ """Repair sparse dead pixels into `out` from valid 8-neighbor values."""
38
+ y_bad, x_bad = np.nonzero(dead_mask)
39
+ if y_bad.size == 0:
40
+ return
41
+
42
+ height, width = frame.shape
43
+ sums = np.zeros(y_bad.size, dtype=np.float32)
44
+ counts = np.zeros(y_bad.size, dtype=np.uint8)
45
+
46
+ for row_offset, col_offset in _NEIGHBOR_OFFSETS:
47
+ y_nbr = y_bad + row_offset
48
+ x_nbr = x_bad + col_offset
49
+ in_bounds = (y_nbr >= 0) & (y_nbr < height) & (x_nbr >= 0) & (x_nbr < width)
50
+ if not np.any(in_bounds):
51
+ continue
52
+
53
+ idx = np.nonzero(in_bounds)[0]
54
+ y_valid = y_nbr[idx]
55
+ x_valid = x_nbr[idx]
56
+ valid = ~dead_mask[y_valid, x_valid]
57
+ if not np.any(valid):
58
+ continue
59
+
60
+ valid_idx = idx[valid]
61
+ sums[valid_idx] += frame[y_valid[valid], x_valid[valid]]
62
+ counts[valid_idx] += 1
63
+
64
+ replace = counts > 0
65
+ if np.any(replace):
66
+ out[y_bad[replace], x_bad[replace]] = (sums[replace] / counts[replace]).astype(frame.dtype, copy=False)
67
+
68
+
69
+ def _replace_dead_pixels_dense_mask(frame: np.ndarray, dead_mask: np.ndarray) -> np.ndarray:
70
+ """Dense vectorized repair path for images with many dead pixels."""
71
+ if frame.ndim != 2:
72
+ return frame
73
+
74
+ frame_f = frame.astype(np.float32, copy=False)
75
+ valid = ~dead_mask
76
+ values = np.where(valid, frame_f, 0.0)
77
+ valid_i = valid.astype(np.int16)
78
+
79
+ pv = np.pad(values, ((1, 1), (1, 1)), mode="constant", constant_values=0.0)
80
+ pm = np.pad(valid_i, ((1, 1), (1, 1)), mode="constant", constant_values=0)
81
+
82
+ nbr_sum = (
83
+ pv[:-2, :-2] + pv[:-2, 1:-1] + pv[:-2, 2:] +
84
+ pv[1:-1, :-2] + pv[1:-1, 2:] +
85
+ pv[2:, :-2] + pv[2:, 1:-1] + pv[2:, 2:]
86
+ )
87
+ nbr_cnt = (
88
+ pm[:-2, :-2] + pm[:-2, 1:-1] + pm[:-2, 2:] +
89
+ pm[1:-1, :-2] + pm[1:-1, 2:] +
90
+ pm[2:, :-2] + pm[2:, 1:-1] + pm[2:, 2:]
91
+ )
92
+
93
+ out = frame_f.copy()
94
+ replace_mask = dead_mask & (nbr_cnt > 0)
95
+ out[replace_mask] = nbr_sum[replace_mask] / nbr_cnt[replace_mask]
96
+ return out.astype(frame.dtype, copy=False)
97
+
98
+
99
+ def _replace_dead_pixels_mono_mask(frame: np.ndarray, dead_mask: np.ndarray) -> np.ndarray:
100
+ """Replace dead pixels in a 2D image from a precomputed dead-pixel mask."""
101
+ if frame.ndim != 2:
102
+ return frame
103
+ if dead_mask.shape != frame.shape:
104
+ raise ValueError("dead_mask must have the same shape as frame")
105
+
106
+ dead_count = int(np.count_nonzero(dead_mask))
107
+ if dead_count == 0:
108
+ return frame
109
+
110
+ if dead_count <= max(64, frame.size // 25):
111
+ out = frame.copy()
112
+ _repair_sparse_dead_pixels(frame, dead_mask, out)
113
+ return out
114
+
115
+ return _replace_dead_pixels_dense_mask(frame, dead_mask)
116
+
117
+
118
+ def replace_dead_pixels_mono(
119
+ frame: np.ndarray,
120
+ dead_value: int = 4095,
121
+ *,
122
+ dead_is_threshold: bool = False,
123
+ ) -> np.ndarray:
124
+ """Replace dead pixels in a mono frame using valid 8-neighbor mean.
125
+
126
+ Parameters
127
+ ----------
128
+ frame:
129
+ 2D mono image.
130
+ dead_value:
131
+ Dead-pixel marker value or threshold.
132
+ dead_is_threshold:
133
+ If `False`, dead pixels are `frame == dead_value`.
134
+ If `True`, dead pixels are `frame >= dead_value`.
135
+ """
136
+ if frame.ndim != 2:
137
+ return frame
138
+ mask = _dead_mask(frame, dead_value, dead_is_threshold=dead_is_threshold)
139
+ return _replace_dead_pixels_mono_mask(frame, mask)
140
+
141
+
142
+ def replace_dead_pixels_bayer(
143
+ frame: np.ndarray,
144
+ dead_value: int = 4095,
145
+ *,
146
+ dead_is_threshold: bool = False,
147
+ ) -> np.ndarray:
148
+ """Repair dead pixels in raw Bayer/CFA frame by processing each 2x2 phase separately.
149
+
150
+ This follows the CINE guidance for raw color cines: bad pixels are not repaired in
151
+ camera output and should be repaired in software before demosaic. Splitting by 2x2
152
+ phase preserves color consistency of the CFA mosaic.
153
+ """
154
+ if frame.ndim != 2:
155
+ return frame
156
+
157
+ dead_mask = _dead_mask(frame, dead_value, dead_is_threshold=dead_is_threshold)
158
+ dead_count = int(np.count_nonzero(dead_mask))
159
+ if dead_count == 0:
160
+ return frame
161
+
162
+ if dead_count <= max(64, frame.size // 25):
163
+ out = frame.copy()
164
+ for row_phase in (0, 1):
165
+ for col_phase in (0, 1):
166
+ _repair_sparse_dead_pixels(
167
+ frame[row_phase::2, col_phase::2],
168
+ dead_mask[row_phase::2, col_phase::2],
169
+ out[row_phase::2, col_phase::2],
170
+ )
171
+ return out
172
+
173
+ out = frame.copy()
174
+ for row_phase in (0, 1):
175
+ for col_phase in (0, 1):
176
+ sub = frame[row_phase::2, col_phase::2]
177
+ mask = dead_mask[row_phase::2, col_phase::2]
178
+ out[row_phase::2, col_phase::2] = _replace_dead_pixels_mono_mask(sub, mask)
179
+ return out
180
+
181
+
182
+ def replace_dead_pixels_rgb(
183
+ frame: np.ndarray,
184
+ dead_value: int = 4095,
185
+ *,
186
+ dead_is_threshold: bool = False,
187
+ ) -> np.ndarray:
188
+ """Repair dead pixels per channel in RGB/BGR image data."""
189
+ if frame.ndim != 3:
190
+ return frame
191
+ if frame.shape[-1] <= 1:
192
+ return frame.reshape(frame.shape[:2])
193
+
194
+ out = frame.copy()
195
+ for ch in range(frame.shape[-1]):
196
+ channel = frame[..., ch]
197
+ mask = _dead_mask(channel, dead_value, dead_is_threshold=dead_is_threshold)
198
+ out[..., ch] = _replace_dead_pixels_mono_mask(channel, mask)
199
+ return out
200
+
201
+
202
+ def replace_dead_pixels(
203
+ frame: np.ndarray,
204
+ *,
205
+ dead_value: int = 4095,
206
+ dead_is_threshold: bool = False,
207
+ bayer_raw: bool = False,
208
+ ) -> np.ndarray:
209
+ """Dispatch dead-pixel repair for mono, Bayer raw, and RGB data.
210
+
211
+ Parameters
212
+ ----------
213
+ frame:
214
+ Input image array (2D mono/Bayer or 3D RGB/BGR).
215
+ dead_value:
216
+ Dead-pixel marker value or threshold.
217
+ dead_is_threshold:
218
+ If `True`, treat values `>= dead_value` as dead.
219
+ bayer_raw:
220
+ If `True` and `frame` is 2D, process as CFA mosaic by 2x2 phase.
221
+ """
222
+ if frame.ndim == 3:
223
+ return replace_dead_pixels_rgb(
224
+ frame,
225
+ dead_value=dead_value,
226
+ dead_is_threshold=dead_is_threshold,
227
+ )
228
+ if frame.ndim == 2 and bayer_raw:
229
+ return replace_dead_pixels_bayer(
230
+ frame,
231
+ dead_value=dead_value,
232
+ dead_is_threshold=dead_is_threshold,
233
+ )
234
+ return replace_dead_pixels_mono(
235
+ frame,
236
+ dead_value=dead_value,
237
+ dead_is_threshold=dead_is_threshold,
238
+ )
239
+
240
+
241
+ def demosaic_bilinear(frame: np.ndarray, pattern: str = "RGGB") -> np.ndarray:
242
+ """Fast bilinear Bayer demosaic for mono raw frames."""
243
+ input_dtype = frame.dtype
244
+ frame_f = frame.astype(np.float32, copy=False)
245
+ h, w = frame_f.shape
246
+
247
+ pad = np.pad(frame_f, ((1, 1), (1, 1)), mode="edge")
248
+ c = pad[1:-1, 1:-1]
249
+ up = pad[:-2, 1:-1]
250
+ dn = pad[2:, 1:-1]
251
+ lf = pad[1:-1, :-2]
252
+ rt = pad[1:-1, 2:]
253
+ ul = pad[:-2, :-2]
254
+ ur = pad[:-2, 2:]
255
+ dl = pad[2:, :-2]
256
+ dr = pad[2:, 2:]
257
+
258
+ g_cross = (up + dn + lf + rt) * 0.25
259
+ rb_diag = (ul + ur + dl + dr) * 0.25
260
+ lr = (lf + rt) * 0.5
261
+ ud = (up + dn) * 0.5
262
+
263
+ rgb = np.empty((h, w, 3), dtype=np.float32)
264
+ for row_phase, col_phase, role in _bayer_phase_roles(pattern):
265
+ rows = slice(row_phase, None, 2)
266
+ cols = slice(col_phase, None, 2)
267
+ if role == "R":
268
+ rgb[rows, cols, 0] = c[rows, cols]
269
+ rgb[rows, cols, 1] = g_cross[rows, cols]
270
+ rgb[rows, cols, 2] = rb_diag[rows, cols]
271
+ elif role == "B":
272
+ rgb[rows, cols, 0] = rb_diag[rows, cols]
273
+ rgb[rows, cols, 1] = g_cross[rows, cols]
274
+ rgb[rows, cols, 2] = c[rows, cols]
275
+ elif role == "G_R":
276
+ rgb[rows, cols, 0] = lr[rows, cols]
277
+ rgb[rows, cols, 1] = c[rows, cols]
278
+ rgb[rows, cols, 2] = ud[rows, cols]
279
+ else:
280
+ rgb[rows, cols, 0] = ud[rows, cols]
281
+ rgb[rows, cols, 1] = c[rows, cols]
282
+ rgb[rows, cols, 2] = lr[rows, cols]
283
+
284
+ np.rint(rgb, out=rgb)
285
+ return rgb.astype(input_dtype, copy=False)
Binary file
Binary file
Binary file
Binary file
cine_reader/py.typed ADDED
File without changes
cine_reader/stats.py ADDED
@@ -0,0 +1,161 @@
1
+ """Frame statistics helpers with low-memory implementations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+ from typing import Iterable
7
+
8
+ import numpy as np
9
+
10
+
11
+ def robust_background_mad_stack(
12
+ frames: Iterable[np.ndarray],
13
+ *,
14
+ q_bg: float = 0.80,
15
+ k_sigma: float = 2.5,
16
+ min_keep: int = 3,
17
+ out_dtype: np.dtype = np.uint16,
18
+ ) -> np.ndarray:
19
+ """Quantile/MAD robust background estimator (full-stack implementation).
20
+
21
+ Works with mono (2D) and color (3D) frames by operating element-wise over
22
+ all trailing dimensions.
23
+ """
24
+ if not (0.0 < q_bg < 1.0):
25
+ raise ValueError("q_bg must be between 0 and 1")
26
+
27
+ data = [np.asarray(frame, dtype=np.float32) for frame in frames]
28
+ if not data:
29
+ raise RuntimeError("No frames were provided.")
30
+
31
+ shape0 = data[0].shape
32
+ if any(arr.shape != shape0 for arr in data[1:]):
33
+ raise ValueError("All frames must have the same shape")
34
+
35
+ stack = np.stack(data, axis=0)
36
+ bg = np.quantile(stack, q_bg, axis=0)
37
+ med = np.median(stack, axis=0)
38
+ mad = np.median(np.abs(stack - med[None, ...]), axis=0)
39
+ sigma = np.maximum(1.4826 * mad, 1e-6)
40
+ keep = stack >= (bg[None, ...] - k_sigma * sigma[None, ...])
41
+ num = np.sum(np.where(keep, stack, 0.0), axis=0)
42
+ den = np.sum(keep, axis=0)
43
+ out = np.divide(num, den, out=bg.copy(), where=(den >= min_keep))
44
+ out = np.clip(np.rint(out), 0, np.iinfo(np.uint16).max)
45
+ return out.astype(out_dtype, copy=False)
46
+
47
+
48
+ def average_from_frame_iter(
49
+ frames: Iterable[np.ndarray],
50
+ *,
51
+ out_dtype: np.dtype | None = None,
52
+ chunk_size: int = 8,
53
+ ) -> tuple[np.ndarray, int]:
54
+ """Compute per-pixel mean from a frame iterator.
55
+
56
+ Uses chunked accumulation to reduce Python overhead while keeping memory bounded.
57
+
58
+ Returns
59
+ -------
60
+ (avg, count)
61
+ Averaged frame and number of frames consumed.
62
+ """
63
+ if chunk_size <= 0:
64
+ raise ValueError("chunk_size must be > 0")
65
+
66
+ acc = None
67
+ count = 0
68
+ pending = []
69
+ resolved_dtype = out_dtype
70
+ expected_shape = None
71
+
72
+ def flush_pending() -> None:
73
+ nonlocal acc, count, pending, resolved_dtype
74
+ if not pending:
75
+ return
76
+ stack = np.stack(pending, axis=0).astype(np.float64, copy=False)
77
+ if acc is None:
78
+ acc = np.zeros_like(stack[0], dtype=np.float64)
79
+ acc += np.sum(stack, axis=0, dtype=np.float64)
80
+ count += stack.shape[0]
81
+ pending = []
82
+
83
+ for frame in frames:
84
+ arr = np.asarray(frame)
85
+ if expected_shape is None:
86
+ expected_shape = arr.shape
87
+ elif arr.shape != expected_shape:
88
+ raise ValueError("All frames must have the same shape")
89
+ if resolved_dtype is None:
90
+ resolved_dtype = arr.dtype
91
+ pending.append(arr)
92
+ if len(pending) >= chunk_size:
93
+ flush_pending()
94
+
95
+ flush_pending()
96
+
97
+ if acc is None or count == 0:
98
+ raise RuntimeError("No frames were provided.")
99
+ avg = np.rint(acc / count)
100
+ return avg.astype(resolved_dtype), count
101
+
102
+
103
+ def robust_background_topk(
104
+ frames: Iterable[np.ndarray],
105
+ *,
106
+ frame_count: int,
107
+ q_bg: float = 0.80,
108
+ min_keep: int = 3,
109
+ max_keep: int | None = 96,
110
+ out_dtype: np.dtype = np.uint16,
111
+ ) -> np.ndarray:
112
+ """Estimate bright background by keeping top-k samples per element.
113
+
114
+ This is a low-memory alternative to full-stack quantile/MAD estimation.
115
+ It supports mono and color frames by flattening each frame then restoring
116
+ its original shape.
117
+ """
118
+ if frame_count <= 0:
119
+ raise ValueError("frame_count must be > 0")
120
+ if not (0.0 < q_bg < 1.0):
121
+ raise ValueError("q_bg must be between 0 and 1")
122
+
123
+ k_keep = max(min_keep, int(math.ceil((1.0 - q_bg) * frame_count)))
124
+ if max_keep is not None:
125
+ k_keep = min(k_keep, max_keep)
126
+ k_keep = max(1, k_keep)
127
+
128
+ topk = None
129
+ index = None
130
+ loaded = 0
131
+ shape = None
132
+
133
+ for frame in frames:
134
+ arr = np.asarray(frame)
135
+ if shape is None:
136
+ shape = arr.shape
137
+ elif arr.shape != shape:
138
+ raise ValueError("All frames must have the same shape")
139
+ arr_f = arr.astype(np.float32, copy=False).reshape(-1)
140
+
141
+ if topk is None:
142
+ topk = np.full((k_keep, arr_f.size), -np.inf, dtype=np.float32)
143
+ index = np.arange(arr_f.size)
144
+
145
+ if loaded < k_keep:
146
+ topk[loaded] = arr_f
147
+ else:
148
+ min_idx = np.argmin(topk, axis=0)
149
+ min_vals = topk[min_idx, index]
150
+ replace = arr_f > min_vals
151
+ if np.any(replace):
152
+ topk[min_idx[replace], index[replace]] = arr_f[replace]
153
+ loaded += 1
154
+
155
+ if topk is None or loaded == 0 or shape is None or index is None:
156
+ raise RuntimeError("No frames were provided.")
157
+
158
+ used = min(loaded, k_keep)
159
+ out = np.mean(topk[:used], axis=0)
160
+ out = np.clip(np.rint(out), 0, np.iinfo(np.uint16).max)
161
+ return out.reshape(shape).astype(out_dtype, copy=False)
cine_reader/unpack.py ADDED
@@ -0,0 +1,139 @@
1
+ """Packed 10-bit Phantom unpack helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ctypes
6
+ import os
7
+ import platform
8
+ from dataclasses import dataclass
9
+ from importlib import resources
10
+ from typing import Optional
11
+
12
+ import numpy as np
13
+
14
+ from ._lookup import LOOKUP_TABLE
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class _LibrarySpec:
19
+ filename: str
20
+ symbol: str
21
+
22
+
23
+ _LIB_CACHE: dict[str, object] = {
24
+ "loaded": False,
25
+ "lib": None,
26
+ "symbol": None,
27
+ "error": None,
28
+ }
29
+
30
+
31
+ def _platform_spec() -> Optional[_LibrarySpec]:
32
+ system = platform.system()
33
+ arch = platform.architecture()[0]
34
+ if system == "Windows":
35
+ if arch == "64bit":
36
+ return _LibrarySpec("unpack_data_win64.dll", "unpack_data_win64")
37
+ return _LibrarySpec("unpack_data_win32.dll", "unpack_data_win32")
38
+ if system == "Darwin":
39
+ return _LibrarySpec("unpack_data_arm64.dylib", "unpack_data_arm64")
40
+ if system == "Linux":
41
+ return _LibrarySpec("unpack_data_elf64.so", "unpack_data_elf64")
42
+ return None
43
+
44
+
45
+ def _try_load_library() -> tuple[Optional[ctypes.CDLL], Optional[str]]:
46
+ if _LIB_CACHE["loaded"]:
47
+ return _LIB_CACHE["lib"], _LIB_CACHE["symbol"]
48
+
49
+ spec = _platform_spec()
50
+ if spec is None:
51
+ _LIB_CACHE.update(loaded=True, lib=None, symbol=None, error="unsupported platform")
52
+ return None, None
53
+
54
+ try:
55
+ package_lib = resources.files("cine_reader").joinpath("libs", spec.filename)
56
+ if not package_lib.is_file():
57
+ _LIB_CACHE.update(loaded=True, lib=None, symbol=None, error="library file not found")
58
+ return None, None
59
+ with resources.as_file(package_lib) as lib_path:
60
+ lib = ctypes.CDLL(str(lib_path))
61
+
62
+ unpack_fn = getattr(lib, spec.symbol)
63
+ unpack_fn.argtypes = [
64
+ ctypes.POINTER(ctypes.c_uint8),
65
+ ctypes.c_size_t,
66
+ ctypes.POINTER(ctypes.c_size_t),
67
+ ]
68
+ unpack_fn.restype = ctypes.POINTER(ctypes.c_uint16)
69
+
70
+ lib.free_pixel_data.argtypes = [ctypes.POINTER(ctypes.c_uint16)]
71
+ lib.free_pixel_data.restype = None
72
+
73
+ _LIB_CACHE.update(loaded=True, lib=lib, symbol=spec.symbol, error=None)
74
+ return lib, spec.symbol
75
+ except Exception as exc: # pragma: no cover - platform dependent
76
+ _LIB_CACHE.update(loaded=True, lib=None, symbol=None, error=str(exc))
77
+ return None, None
78
+
79
+
80
+ def unpack_10bit_numpy(data: bytes) -> np.ndarray:
81
+ """Decode packed 10-bit payload with NumPy and the C-equivalent lookup table."""
82
+ byte_data = np.frombuffer(data, dtype=np.uint8)
83
+ groups = byte_data.size // 5
84
+ if groups == 0:
85
+ return np.empty(0, dtype=np.uint16)
86
+
87
+ packed = byte_data[: groups * 5].reshape(groups, 5).astype(np.uint64, copy=False)
88
+ combined = (
89
+ (packed[:, 0] << 32)
90
+ | (packed[:, 1] << 24)
91
+ | (packed[:, 2] << 16)
92
+ | (packed[:, 3] << 8)
93
+ | packed[:, 4]
94
+ )
95
+
96
+ idx0 = (combined >> 30) & 0x3FF
97
+ idx1 = (combined >> 20) & 0x3FF
98
+ idx2 = (combined >> 10) & 0x3FF
99
+ idx3 = combined & 0x3FF
100
+
101
+ out = np.empty(groups * 4, dtype=np.uint16)
102
+ out[0::4] = LOOKUP_TABLE[idx0]
103
+ out[1::4] = LOOKUP_TABLE[idx1]
104
+ out[2::4] = LOOKUP_TABLE[idx2]
105
+ out[3::4] = LOOKUP_TABLE[idx3]
106
+ return out
107
+
108
+
109
+ def _unpack_10bit_c(data: bytes) -> Optional[np.ndarray]:
110
+ if os.environ.get("CINE_READER_DISABLE_C_UNPACK", "0") == "1":
111
+ return None
112
+
113
+ lib, symbol = _try_load_library()
114
+ if lib is None or symbol is None:
115
+ return None
116
+
117
+ unpack_fn = getattr(lib, symbol)
118
+ payload = np.frombuffer(data, dtype=np.uint8)
119
+ num_pixels = ctypes.c_size_t()
120
+ ptr = unpack_fn(
121
+ payload.ctypes.data_as(ctypes.POINTER(ctypes.c_uint8)),
122
+ ctypes.c_size_t(payload.size),
123
+ ctypes.byref(num_pixels),
124
+ )
125
+ if not ptr:
126
+ raise RuntimeError("C unpack routine returned NULL")
127
+
128
+ try:
129
+ return np.ctypeslib.as_array(ptr, shape=(num_pixels.value,)).copy()
130
+ finally:
131
+ lib.free_pixel_data(ptr)
132
+
133
+
134
+ def unpack_10bit_data(data: bytes) -> np.ndarray:
135
+ """Decode packed 10-bit payload using C library when available."""
136
+ decoded = _unpack_10bit_c(data)
137
+ if decoded is not None:
138
+ return decoded
139
+ return unpack_10bit_numpy(data)