ponkan-python 0.1.0__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.
Files changed (39) hide show
  1. ponkan_python-0.1.0.dist-info/METADATA +157 -0
  2. ponkan_python-0.1.0.dist-info/RECORD +39 -0
  3. ponkan_python-0.1.0.dist-info/WHEEL +4 -0
  4. ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
  5. ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
  6. ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
  7. py3dscapture/__init__.py +36 -0
  8. py3dscapture/artifacts.py +66 -0
  9. py3dscapture/capture.py +599 -0
  10. py3dscapture/devices/__init__.py +1 -0
  11. py3dscapture/devices/n3dsxl_ftd3.py +238 -0
  12. py3dscapture/errors.py +120 -0
  13. py3dscapture/hardware_gate.py +143 -0
  14. py3dscapture/image/__init__.py +1 -0
  15. py3dscapture/image/frame.py +166 -0
  16. py3dscapture/protocol/__init__.py +1 -0
  17. py3dscapture/protocol/layout_3ds.py +60 -0
  18. py3dscapture/protocol/n3dsxl.py +249 -0
  19. py3dscapture/protocol/sizes.py +128 -0
  20. py3dscapture/py.typed +1 -0
  21. py3dscapture/streaming/__init__.py +1 -0
  22. py3dscapture/streaming/buffers.py +156 -0
  23. py3dscapture/streaming/engine.py +285 -0
  24. py3dscapture/streaming/policies.py +157 -0
  25. py3dscapture/streaming/stats.py +254 -0
  26. py3dscapture/tools/__init__.py +1 -0
  27. py3dscapture/tools/capture_raw.py +44 -0
  28. py3dscapture/tools/list_devices.py +68 -0
  29. py3dscapture/tools/raw_to_png.py +251 -0
  30. py3dscapture/tools/stream_n3dsxl.py +152 -0
  31. py3dscapture/transport/__init__.py +1 -0
  32. py3dscapture/transport/d3xx_backend.py +850 -0
  33. py3dscapture/transport/d3xx_native.py +268 -0
  34. py3dscapture/transport/d3xx_native_streaming.py +306 -0
  35. py3dscapture/transport/d3xx_streaming.py +202 -0
  36. py3dscapture/transport/ftd3_backend.py +275 -0
  37. py3dscapture/transport/ftd3_pipe.py +387 -0
  38. py3dscapture/transport/libusb_async.py +134 -0
  39. py3dscapture/transport/libusb_backend.py +357 -0
@@ -0,0 +1,285 @@
1
+ """Streaming engine built around async raw completions."""
2
+
3
+ import asyncio
4
+ import queue
5
+ import time
6
+ from collections.abc import AsyncIterator, Callable, Iterator
7
+
8
+ from py3dscapture.errors import DecodeError
9
+ from py3dscapture.image.frame import CaptureFrame
10
+ from py3dscapture.protocol.layout_3ds import decode_rgb8_2d
11
+ from py3dscapture.protocol.sizes import capture_size, video_size
12
+ from py3dscapture.streaming.buffers import BufferPool, RawFrameResult, RawFrameSlot
13
+ from py3dscapture.streaming.policies import BoundedFrameQueue, DropPolicy, put_frame_with_policy
14
+ from py3dscapture.streaming.stats import StreamStats, StreamTimingCollector, TimingSummary
15
+ from py3dscapture.transport.libusb_async import AsyncTransferBackend
16
+
17
+ Decoder = Callable[[bytes], CaptureFrame]
18
+
19
+
20
+ class StreamingEngine:
21
+ """Coordinate raw async acquisition, decode handoff, and frame delivery.
22
+
23
+ Transfer callbacks only enqueue raw completion metadata. Decoding and
24
+ decoded-frame queue policy are handled by ``process_completed`` outside the
25
+ callback path.
26
+ """
27
+
28
+ def __init__(
29
+ self,
30
+ backend: AsyncTransferBackend,
31
+ *,
32
+ raw_slots: int = 2,
33
+ raw_slot_size: int | None = None,
34
+ output_queue_size: int = 2,
35
+ drop_policy: DropPolicy = "drop_oldest",
36
+ decoder: Decoder | None = None,
37
+ collect_timing: bool = False,
38
+ ) -> None:
39
+ """Create a streaming engine over an async transfer backend.
40
+
41
+ Args:
42
+ backend: Async transfer backend that fills raw slots and invokes a
43
+ completion callback.
44
+ raw_slots: Number of in-flight raw transfer buffers.
45
+ raw_slot_size: Byte size for each raw slot. Defaults to the 2D
46
+ capture size.
47
+ output_queue_size: Number of decoded frames retained for consumers.
48
+ drop_policy: Overflow behavior for decoded-frame delivery.
49
+ decoder: Optional raw-video decoder used for tests or alternate
50
+ decode strategies.
51
+ collect_timing: Collect per-transfer timing samples and expose a
52
+ summary through ``timing_summary`` when true.
53
+
54
+ Raises:
55
+ ValueError: Slot or queue sizes are not positive.
56
+ """
57
+ self.raw_slot_size = raw_slot_size or capture_size(mode_3d=False)
58
+ self.buffer_pool = BufferPool(raw_slots=raw_slots, raw_slot_size=self.raw_slot_size)
59
+ self.backend = backend
60
+ self.output_queue = BoundedFrameQueue(output_queue_size)
61
+ self.drop_policy = drop_policy
62
+ self._decoder = decoder or _decode_2d_default
63
+ self._stats = StreamStats()
64
+ self._completion_queue: queue.Queue[RawFrameResult] = queue.Queue(maxsize=raw_slots)
65
+ self._running = False
66
+ self._next_sequence = 0
67
+ self._timing = StreamTimingCollector() if collect_timing else None
68
+
69
+ def start(self) -> None:
70
+ """Submit initial raw-slot async reads.
71
+
72
+ The method is idempotent while already running. Each slot is checked out
73
+ and submitted once.
74
+ """
75
+ if self._running:
76
+ return
77
+ self._running = True
78
+ for slot in self.buffer_pool.slots:
79
+ self._submit_slot(self.buffer_pool.checkout(slot.index))
80
+
81
+ def stop(self, timeout: float | None = None) -> None:
82
+ """Cancel, drain, release backend resources, and release raw slots.
83
+
84
+ Args:
85
+ timeout: Reserved for future bounded shutdown support. Current
86
+ shutdown drains using the backend's own semantics.
87
+ """
88
+ _ = timeout
89
+ if not self._running and self.buffer_pool.in_use_count() == 0:
90
+ return
91
+ self._running = False
92
+ self._stats.cancelled += self.buffer_pool.in_use_count()
93
+ self.backend.cancel_all()
94
+ self.backend.drain()
95
+ for slot in self.buffer_pool.slots:
96
+ if slot.in_use:
97
+ self.buffer_pool.release(slot.index)
98
+ self.backend.release()
99
+
100
+ def process_completed(self, *, limit: int | None = None) -> int:
101
+ """Decode completed raw results outside the callback.
102
+
103
+ Args:
104
+ limit: Maximum number of completions to process, or ``None`` to
105
+ process until the completion queue is empty.
106
+
107
+ Returns:
108
+ Number of raw completions consumed from the completion queue.
109
+ """
110
+ processed = 0
111
+ while limit is None or processed < limit:
112
+ try:
113
+ result = self._completion_queue.get_nowait()
114
+ except queue.Empty:
115
+ break
116
+ processed += 1
117
+ self._process_result(result)
118
+ return processed
119
+
120
+ def frames(self, *, max_frames: int | None = None) -> Iterator[CaptureFrame]:
121
+ """Yield decoded frames currently available to consumers.
122
+
123
+ Args:
124
+ max_frames: Maximum number of frames to yield, or ``None`` to drain
125
+ all currently queued frames.
126
+
127
+ Yields:
128
+ Decoded frames from the output queue in delivery order.
129
+ """
130
+ delivered = 0
131
+ while max_frames is None or delivered < max_frames:
132
+ try:
133
+ frame = self.output_queue.get_nowait()
134
+ except IndexError:
135
+ break
136
+ delivered += 1
137
+ yield frame
138
+
139
+ async def frames_async(self, *, max_frames: int | None = None) -> AsyncIterator[CaptureFrame]:
140
+ """Yield decoded frames through an async iterator.
141
+
142
+ Args:
143
+ max_frames: Maximum number of frames to yield, or ``None`` to drain
144
+ all currently queued frames.
145
+
146
+ Yields:
147
+ Decoded frames from the output queue in delivery order.
148
+ """
149
+ delivered = 0
150
+ while max_frames is None or delivered < max_frames:
151
+ frame = next(self.frames(max_frames=1), None)
152
+ if frame is None:
153
+ break
154
+ delivered += 1
155
+ yield frame
156
+ await asyncio.sleep(0)
157
+
158
+ def stats(self) -> StreamStats:
159
+ """Return a snapshot of current stream counters.
160
+
161
+ Returns:
162
+ Independent counter snapshot for reporting.
163
+ """
164
+ return self._stats.snapshot()
165
+
166
+ def timing_summary(self) -> TimingSummary | None:
167
+ """Return opt-in timing summary for completed samples.
168
+
169
+ Returns:
170
+ Timing summary when collection is enabled, otherwise ``None``.
171
+ """
172
+ if self._timing is None:
173
+ return None
174
+ return self._timing.summary()
175
+
176
+ def _submit_slot(self, slot: RawFrameSlot) -> None:
177
+ slot.submitted_ns = time.monotonic_ns()
178
+ slot.backend_started_ns = None
179
+ slot.completed_ns = None
180
+ slot.transferred = 0
181
+ slot.sequence = self._next_sequence
182
+ self._next_sequence += 1
183
+ self.backend.submit_read(
184
+ slot,
185
+ length=self.raw_slot_size,
186
+ callback=self._on_transfer_complete,
187
+ )
188
+ self._stats.submitted += 1
189
+
190
+ def _on_transfer_complete(
191
+ self,
192
+ slot_index: int,
193
+ transferred: int,
194
+ status: int,
195
+ completed_ns: int,
196
+ ) -> None:
197
+ slot = self.buffer_pool.get(slot_index)
198
+ slot.completed_ns = completed_ns
199
+ slot.transferred = transferred
200
+ submitted_ns = slot.submitted_ns
201
+ backend_started_ns = slot.backend_started_ns
202
+ sequence = 0 if slot.sequence is None else slot.sequence
203
+ result = RawFrameResult(
204
+ slot_index=slot_index,
205
+ view=slot.view,
206
+ transferred=transferred,
207
+ status=status,
208
+ submitted_ns=submitted_ns,
209
+ backend_started_ns=backend_started_ns,
210
+ completed_ns=completed_ns,
211
+ sequence=sequence,
212
+ )
213
+ if self._timing is not None:
214
+ self._timing.record_completion_interval(completed_ns)
215
+ if submitted_ns is not None:
216
+ self._timing.record_ns_delta(
217
+ "submit_to_complete_ms",
218
+ completed_ns - submitted_ns,
219
+ )
220
+ if backend_started_ns is not None:
221
+ self._timing.record_ns_delta(
222
+ "backend_queue_wait_ms",
223
+ backend_started_ns - submitted_ns,
224
+ )
225
+ if backend_started_ns is not None:
226
+ self._timing.record_ns_delta(
227
+ "read_duration_ms",
228
+ completed_ns - backend_started_ns,
229
+ )
230
+ try:
231
+ self._completion_queue.put_nowait(result)
232
+ except queue.Full:
233
+ self._stats.dropped_raw += 1
234
+ self.buffer_pool.release(slot_index)
235
+ else:
236
+ self._stats.completed += 1
237
+
238
+ def _process_result(self, result: RawFrameResult) -> None:
239
+ if self._timing is not None:
240
+ process_started_ns = time.monotonic_ns()
241
+ self._timing.record_ns_delta(
242
+ "completion_queue_wait_ms",
243
+ process_started_ns - result.completed_ns,
244
+ )
245
+ try:
246
+ if result.status != 0:
247
+ self._stats.usb_errors += 1
248
+ return
249
+ expected_video_size = video_size(mode_3d=False)
250
+ if result.transferred < expected_video_size:
251
+ self._stats.dropped_raw += 1
252
+ return
253
+ raw_video = bytes(result.view[:expected_video_size])
254
+ if self._timing is None:
255
+ frame = self._decoder(raw_video)
256
+ else:
257
+ decode_started_ns = time.monotonic_ns()
258
+ try:
259
+ frame = self._decoder(raw_video)
260
+ finally:
261
+ self._timing.record_ns_delta(
262
+ "decode_ms",
263
+ time.monotonic_ns() - decode_started_ns,
264
+ )
265
+ frame.sequence = result.sequence
266
+ frame.timestamp_ns = result.completed_ns
267
+ self._stats.decoded += 1
268
+ put_frame_with_policy(self.output_queue, frame, self.drop_policy, self._stats)
269
+ except DecodeError as exc:
270
+ self._stats.decode_errors += 1
271
+ self._stats.last_error = exc.__class__.__name__
272
+ finally:
273
+ self.buffer_pool.release(result.slot_index)
274
+ if self._running:
275
+ if self._timing is not None:
276
+ resubmit_started_ns = time.monotonic_ns()
277
+ self._timing.record_ns_delta(
278
+ "callback_to_resubmit_ms",
279
+ resubmit_started_ns - result.completed_ns,
280
+ )
281
+ self._submit_slot(self.buffer_pool.checkout(result.slot_index))
282
+
283
+
284
+ def _decode_2d_default(raw_video: bytes) -> CaptureFrame:
285
+ return decode_rgb8_2d(raw_video)
@@ -0,0 +1,157 @@
1
+ """Bounded frame delivery queues and drop policies."""
2
+
3
+ from collections import deque
4
+ from collections.abc import Iterator
5
+ from typing import Literal
6
+
7
+ from py3dscapture.image.frame import CaptureFrame
8
+ from py3dscapture.streaming.stats import StreamStats
9
+
10
+ DropPolicy = Literal["drop_oldest", "drop_newest", "block"]
11
+ CopyPolicy = Literal["copy_decoded_frame_before_release_raw_slot", "zero_copy_experimental"]
12
+
13
+
14
+ class BoundedFrameQueue:
15
+ """Small FIFO queue for decoded frames.
16
+
17
+ The queue is intentionally simple and non-blocking for callback-adjacent
18
+ paths. Blocking behavior is modeled explicitly by ``put_frame_with_policy``.
19
+ """
20
+
21
+ def __init__(self, max_size: int) -> None:
22
+ """Create a bounded queue.
23
+
24
+ Args:
25
+ max_size: Maximum number of decoded frames retained.
26
+
27
+ Raises:
28
+ ValueError: ``max_size`` is not positive.
29
+ """
30
+ if max_size <= 0:
31
+ raise ValueError
32
+ self._max_size = max_size
33
+ self._items: deque[CaptureFrame] = deque()
34
+
35
+ @property
36
+ def max_size(self) -> int:
37
+ """Return the queue capacity.
38
+
39
+ Returns:
40
+ Maximum number of frames retained by the queue.
41
+ """
42
+ return self._max_size
43
+
44
+ def __len__(self) -> int:
45
+ """Return queued frame count.
46
+
47
+ Returns:
48
+ Number of frames currently queued.
49
+ """
50
+ return len(self._items)
51
+
52
+ def __iter__(self) -> Iterator[CaptureFrame]:
53
+ """Iterate queued frames from oldest to newest.
54
+
55
+ Yields:
56
+ Snapshot of queued frames in delivery order.
57
+ """
58
+ return iter(tuple(self._items))
59
+
60
+ def full(self) -> bool:
61
+ """Return whether no more frames can be enqueued.
62
+
63
+ Returns:
64
+ True when queue length is greater than or equal to capacity.
65
+ """
66
+ return len(self._items) >= self._max_size
67
+
68
+ def put_nowait(self, frame: CaptureFrame) -> None:
69
+ """Append a frame if capacity remains.
70
+
71
+ Args:
72
+ frame: Decoded frame to append.
73
+
74
+ Raises:
75
+ OverflowError: The queue is already full.
76
+ """
77
+ if self.full():
78
+ raise OverflowError
79
+ self._items.append(frame)
80
+
81
+ def put_blocking(self, frame: CaptureFrame) -> None:
82
+ """Append a frame for non-callback contexts.
83
+
84
+ Args:
85
+ frame: Decoded frame to append even when the queue is full.
86
+ """
87
+ self._items.append(frame)
88
+
89
+ def get_nowait(self) -> CaptureFrame:
90
+ """Pop the oldest frame.
91
+
92
+ Returns:
93
+ Oldest queued frame.
94
+
95
+ Raises:
96
+ IndexError: The queue is empty.
97
+ """
98
+ return self._items.popleft()
99
+
100
+ def drop_oldest(self) -> CaptureFrame:
101
+ """Drop and return the oldest frame.
102
+
103
+ Returns:
104
+ The frame removed from the queue.
105
+
106
+ Raises:
107
+ IndexError: The queue is empty.
108
+ """
109
+ return self._items.popleft()
110
+
111
+
112
+ def put_frame_with_policy(
113
+ queue: BoundedFrameQueue,
114
+ frame: CaptureFrame,
115
+ policy: DropPolicy,
116
+ stats: StreamStats,
117
+ *,
118
+ callback_thread: bool = False,
119
+ ) -> bool:
120
+ """Put one decoded frame using a bounded-queue policy.
121
+
122
+ Args:
123
+ queue: Destination queue.
124
+ frame: Decoded frame to enqueue or drop.
125
+ policy: Overflow behavior when the queue is full.
126
+ stats: Mutable counters updated with delivery or drop results.
127
+ callback_thread: Whether the caller is running on a callback thread.
128
+
129
+ Returns:
130
+ True when the frame was retained for delivery.
131
+
132
+ Raises:
133
+ RuntimeError: ``policy`` is ``"block"`` on a callback thread.
134
+ ValueError: ``policy`` is not one of the supported literal values.
135
+ """
136
+ if policy == "block" and callback_thread:
137
+ raise RuntimeError
138
+
139
+ if not queue.full():
140
+ queue.put_nowait(frame)
141
+ stats.delivered += 1
142
+ return True
143
+
144
+ if policy == "drop_newest":
145
+ stats.dropped_decoded += 1
146
+ return False
147
+ if policy == "drop_oldest":
148
+ queue.drop_oldest()
149
+ stats.dropped_decoded += 1
150
+ queue.put_nowait(frame)
151
+ stats.delivered += 1
152
+ return True
153
+ if policy == "block":
154
+ queue.put_blocking(frame)
155
+ stats.delivered += 1
156
+ return True
157
+ raise ValueError
@@ -0,0 +1,254 @@
1
+ """Streaming counters."""
2
+
3
+ from dataclasses import asdict, dataclass, field
4
+ from threading import Lock
5
+ from typing import Literal
6
+
7
+ TIMING_METRIC_NAMES = (
8
+ "backend_queue_wait_ms",
9
+ "read_duration_ms",
10
+ "submit_to_complete_ms",
11
+ "completion_interval_ms",
12
+ "completion_queue_wait_ms",
13
+ "decode_ms",
14
+ "callback_to_resubmit_ms",
15
+ )
16
+
17
+ TimingMetricSummary = dict[str, float | int]
18
+ TimingSummary = dict[str, TimingMetricSummary]
19
+ StreamingBackendKind = Literal["libusb", "d3xx", "d3xx-native"]
20
+
21
+
22
+ @dataclass(slots=True)
23
+ class StreamTimingCollector:
24
+ """Collect opt-in per-transfer timing samples for streaming reports.
25
+
26
+ The collector stores all samples in memory and summarizes them on demand.
27
+ This is intended for bounded smoke runs, not indefinite production
28
+ telemetry.
29
+ """
30
+
31
+ _samples: dict[str, list[float]] = field(
32
+ default_factory=lambda: {name: [] for name in TIMING_METRIC_NAMES}
33
+ )
34
+ _last_completed_ns: int | None = None
35
+ _lock: Lock = field(default_factory=Lock)
36
+
37
+ def record_ns_delta(self, metric: str, delta_ns: int) -> None:
38
+ """Record one non-negative nanosecond delta as milliseconds.
39
+
40
+ Args:
41
+ metric: Metric name from ``TIMING_METRIC_NAMES``.
42
+ delta_ns: Duration in nanoseconds.
43
+ """
44
+ if delta_ns < 0:
45
+ return
46
+ with self._lock:
47
+ self._samples[metric].append(delta_ns / 1_000_000)
48
+
49
+ def record_completion_interval(self, completed_ns: int) -> None:
50
+ """Record interval from the previous backend completion.
51
+
52
+ Args:
53
+ completed_ns: Monotonic timestamp for the current completion.
54
+ """
55
+ with self._lock:
56
+ if self._last_completed_ns is not None:
57
+ delta_ns = completed_ns - self._last_completed_ns
58
+ if delta_ns >= 0:
59
+ self._samples["completion_interval_ms"].append(delta_ns / 1_000_000)
60
+ self._last_completed_ns = completed_ns
61
+
62
+ def summary(self) -> TimingSummary:
63
+ """Return count/min/percentile/max/mean summaries by metric.
64
+
65
+ Returns:
66
+ JSON-serializable timing summary. Metrics without samples are
67
+ omitted.
68
+ """
69
+ with self._lock:
70
+ samples = {name: tuple(values) for name, values in self._samples.items()}
71
+ return {name: _summarize_metric(values) for name, values in samples.items() if values}
72
+
73
+
74
+ @dataclass(slots=True)
75
+ class StreamStats:
76
+ """Mutable streaming counters.
77
+
78
+ Attributes:
79
+ submitted: Raw reads submitted to the backend.
80
+ completed: Backend completions received.
81
+ decoded: Raw completions decoded into frames.
82
+ delivered: Decoded frames retained for consumers.
83
+ dropped_raw: Raw completions dropped before decode.
84
+ dropped_decoded: Decoded frames dropped by queue policy.
85
+ usb_errors: Backend completion errors.
86
+ decode_errors: Decoder failures.
87
+ cancelled: In-flight transfers cancelled during shutdown.
88
+ last_error: Optional class name for the last decode error.
89
+ """
90
+
91
+ submitted: int = 0
92
+ completed: int = 0
93
+ decoded: int = 0
94
+ delivered: int = 0
95
+ dropped_raw: int = 0
96
+ dropped_decoded: int = 0
97
+ usb_errors: int = 0
98
+ decode_errors: int = 0
99
+ cancelled: int = 0
100
+ last_error: str | None = None
101
+
102
+ def snapshot(self) -> "StreamStats":
103
+ """Return a copy suitable for reporting.
104
+
105
+ Returns:
106
+ Independent counter object representing the current values.
107
+ """
108
+ return StreamStats(**asdict(self))
109
+
110
+ def to_dict(self) -> dict[str, int | str | None]:
111
+ """Return JSON-serializable counters.
112
+
113
+ Returns:
114
+ Dictionary form of all stream counters.
115
+ """
116
+ return asdict(self)
117
+
118
+
119
+ @dataclass(frozen=True, slots=True)
120
+ class PerformanceStats:
121
+ """JSON-serializable performance smoke report.
122
+
123
+ Attributes mirror the performance smoke artifact schema. Time values are
124
+ seconds, and ``delivered_fps`` is calculated from delivered frame count and
125
+ requested duration.
126
+ """
127
+
128
+ model: Literal["new_3ds_xl"]
129
+ product_string: str | None
130
+ product_string_status: Literal["accepted", "unreadable"]
131
+ backend_kind: StreamingBackendKind
132
+ driver_service: str | None
133
+ mode_3d: bool
134
+ duration_seconds: float
135
+ raw_slots: int
136
+ output_queue_size: int
137
+ drop_policy: str
138
+ submitted: int
139
+ completed: int
140
+ decoded: int
141
+ delivered: int
142
+ dropped_raw: int
143
+ dropped_decoded: int
144
+ usb_errors: int
145
+ decode_errors: int
146
+ cancelled: int
147
+ last_error: str | None
148
+ shutdown_seconds: float
149
+ delivered_fps: float
150
+ timing: TimingSummary | None = None
151
+
152
+ @classmethod
153
+ def from_stream_stats(
154
+ cls,
155
+ stats: StreamStats,
156
+ *,
157
+ product_string: str | None,
158
+ product_string_status: Literal["accepted", "unreadable"],
159
+ mode_3d: bool,
160
+ duration_seconds: float,
161
+ raw_slots: int,
162
+ output_queue_size: int,
163
+ drop_policy: str,
164
+ shutdown_seconds: float,
165
+ backend_kind: StreamingBackendKind = "libusb",
166
+ driver_service: str | None = None,
167
+ timing: TimingSummary | None = None,
168
+ ) -> "PerformanceStats":
169
+ """Build a performance report from streaming counters.
170
+
171
+ Args:
172
+ stats: Streaming counters collected during the smoke run.
173
+ product_string: USB product string when readable.
174
+ product_string_status: Whether the product string was accepted or
175
+ unreadable.
176
+ mode_3d: Capture mode used by the smoke run.
177
+ duration_seconds: Requested smoke duration in seconds.
178
+ raw_slots: Raw transfer slot count.
179
+ output_queue_size: Decoded frame queue capacity.
180
+ drop_policy: Decoded frame overflow policy.
181
+ shutdown_seconds: Time spent stopping the engine.
182
+ backend_kind: Transport backend used for the run.
183
+ driver_service: Optional Windows driver service observed.
184
+ timing: Optional timing summary collected by ``StreamingEngine``.
185
+
186
+ Returns:
187
+ Frozen JSON-serializable performance report.
188
+ """
189
+ delivered_fps = stats.delivered / duration_seconds if duration_seconds > 0 else 0.0
190
+ timing_copy = (
191
+ {metric: dict(summary) for metric, summary in timing.items()}
192
+ if timing is not None
193
+ else None
194
+ )
195
+ return cls(
196
+ model="new_3ds_xl",
197
+ product_string=product_string,
198
+ product_string_status=product_string_status,
199
+ backend_kind=backend_kind,
200
+ driver_service=driver_service,
201
+ mode_3d=mode_3d,
202
+ duration_seconds=duration_seconds,
203
+ raw_slots=raw_slots,
204
+ output_queue_size=output_queue_size,
205
+ drop_policy=drop_policy,
206
+ submitted=stats.submitted,
207
+ completed=stats.completed,
208
+ decoded=stats.decoded,
209
+ delivered=stats.delivered,
210
+ dropped_raw=stats.dropped_raw,
211
+ dropped_decoded=stats.dropped_decoded,
212
+ usb_errors=stats.usb_errors,
213
+ decode_errors=stats.decode_errors,
214
+ cancelled=stats.cancelled,
215
+ last_error=stats.last_error,
216
+ shutdown_seconds=shutdown_seconds,
217
+ delivered_fps=delivered_fps,
218
+ timing=timing_copy,
219
+ )
220
+
221
+ def to_dict(self) -> dict[str, object]:
222
+ """Return JSON-serializable performance stats.
223
+
224
+ Returns:
225
+ Dictionary form suitable for JSON artifact output.
226
+ """
227
+ payload = asdict(self)
228
+ if self.timing is None:
229
+ payload.pop("timing")
230
+ return payload
231
+
232
+
233
+ def _summarize_metric(values: tuple[float, ...]) -> TimingMetricSummary:
234
+ ordered = tuple(sorted(values))
235
+ count = len(ordered)
236
+ return {
237
+ "count": count,
238
+ "min": ordered[0],
239
+ "p50": _percentile(ordered, 0.50),
240
+ "p95": _percentile(ordered, 0.95),
241
+ "p99": _percentile(ordered, 0.99),
242
+ "max": ordered[-1],
243
+ "mean": sum(ordered) / count,
244
+ }
245
+
246
+
247
+ def _percentile(values: tuple[float, ...], percentile: float) -> float:
248
+ if len(values) == 1:
249
+ return values[0]
250
+ position = (len(values) - 1) * percentile
251
+ lower_index = int(position)
252
+ upper_index = min(lower_index + 1, len(values) - 1)
253
+ fraction = position - lower_index
254
+ return values[lower_index] + (values[upper_index] - values[lower_index]) * fraction
@@ -0,0 +1 @@
1
+ """Command line helpers."""