ponkan-python 0.1.2__tar.gz → 0.2.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 (89) hide show
  1. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/.gitignore +3 -0
  2. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/PKG-INFO +8 -5
  3. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/README.md +6 -3
  4. ponkan_python-0.2.1/docs/api.md +440 -0
  5. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/docs/publishing.md +8 -4
  6. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/pyproject.toml +1 -1
  7. ponkan_python-0.2.1/src/ponkan/__init__.py +68 -0
  8. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/capture.py +24 -9
  9. ponkan_python-0.2.1/src/ponkan/devices/discovery.py +397 -0
  10. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/devices/n3dsxl_ftd3.py +1 -1
  11. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/errors.py +101 -4
  12. ponkan_python-0.2.1/src/ponkan/layouts.py +170 -0
  13. ponkan_python-0.2.1/src/ponkan/profiles.py +95 -0
  14. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/protocol/n3dsxl.py +3 -3
  15. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/streaming/engine.py +14 -8
  16. ponkan_python-0.2.1/src/ponkan/tools/list_devices.py +69 -0
  17. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/d3xx_backend.py +12 -4
  18. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/ftd3_pipe.py +1 -1
  19. ponkan_python-0.2.1/tests/unit/test_capture_device_discovery.py +145 -0
  20. ponkan_python-0.2.1/tests/unit/test_capture_layout_metadata.py +87 -0
  21. ponkan_python-0.2.1/tests/unit/test_capture_profiles.py +124 -0
  22. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_high_level_capture_read_api.py +46 -2
  23. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_n3dsxl_list_devices_cli.py +8 -2
  24. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_package.py +27 -0
  25. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_streaming_engine_fake_async.py +16 -0
  26. ponkan_python-0.2.1/tests/unit/test_structured_capture_errors.py +181 -0
  27. ponkan_python-0.1.2/docs/api.md +0 -232
  28. ponkan_python-0.1.2/src/ponkan/__init__.py +0 -36
  29. ponkan_python-0.1.2/src/ponkan/tools/list_devices.py +0 -68
  30. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/LICENSE +0 -0
  31. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/NOTICE.md +0 -0
  32. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/artifacts.py +0 -0
  33. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/devices/__init__.py +0 -0
  34. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/hardware_gate.py +0 -0
  35. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/image/__init__.py +0 -0
  36. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/image/frame.py +0 -0
  37. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/protocol/__init__.py +0 -0
  38. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/protocol/layout_3ds.py +0 -0
  39. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/protocol/sizes.py +0 -0
  40. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/py.typed +0 -0
  41. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/streaming/__init__.py +0 -0
  42. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/streaming/buffers.py +0 -0
  43. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/streaming/policies.py +0 -0
  44. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/streaming/stats.py +0 -0
  45. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/tools/__init__.py +0 -0
  46. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/tools/capture_raw.py +0 -0
  47. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/tools/raw_to_png.py +0 -0
  48. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/tools/stream_n3dsxl.py +0 -0
  49. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/__init__.py +0 -0
  50. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/d3xx_native.py +0 -0
  51. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/d3xx_native_streaming.py +0 -0
  52. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/d3xx_streaming.py +0 -0
  53. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/ftd3_backend.py +0 -0
  54. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/libusb_async.py +0 -0
  55. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/src/ponkan/transport/libusb_backend.py +0 -0
  56. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/conftest.py +0 -0
  57. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/README.md +0 -0
  58. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_connect.py +0 -0
  59. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_d3xx_backend.py +0 -0
  60. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_d3xx_native_streaming.py +0 -0
  61. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_ftd3_pipe.py +0 -0
  62. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_high_level_capture_read_api.py +0 -0
  63. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_open_close.py +0 -0
  64. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_raw_capture.py +0 -0
  65. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/e2e/test_n3dsxl_streaming.py +0 -0
  66. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/manual/test_n3dsxl_decoder_visual.py +0 -0
  67. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/performance/README.md +0 -0
  68. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/performance/test_n3dsxl_d3xx_native_streaming_smoke.py +0 -0
  69. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/performance/test_n3dsxl_streaming_smoke.py +0 -0
  70. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_codex_pre_tool_use_policy.py +0 -0
  71. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_d3xx_backend.py +0 -0
  72. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_d3xx_native_api.py +0 -0
  73. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_d3xx_native_streaming_backend.py +0 -0
  74. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_d3xx_streaming_backend.py +0 -0
  75. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_ftd3_backend_selector.py +0 -0
  76. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_ftd3_pipe_payloads.py +0 -0
  77. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_hardware_gate.py +0 -0
  78. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_layout_3ds_decoder.py +0 -0
  79. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_libusb_backend.py +0 -0
  80. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_n3dsxl_artifacts.py +0 -0
  81. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_n3dsxl_connect_sequence.py +0 -0
  82. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_n3dsxl_device_filter.py +0 -0
  83. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_n3dsxl_session.py +0 -0
  84. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_n3dsxl_sizes.py +0 -0
  85. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_raw_capture_metadata.py +0 -0
  86. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_stream_n3dsxl_cli.py +0 -0
  87. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_streaming_buffers.py +0 -0
  88. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_streaming_performance_stats.py +0 -0
  89. {ponkan_python-0.1.2 → ponkan_python-0.2.1}/tests/unit/test_streaming_policies.py +0 -0
@@ -19,3 +19,6 @@ htmlcov/
19
19
  artifacts/
20
20
  captures/
21
21
  *.log
22
+
23
+ # Local scratch notes
24
+ tmp/
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: ponkan-python
3
- Version: 0.1.2
3
+ Version: 0.2.1
4
4
  Summary: A Python capture library focused on new 3DS XL capture board frame acquisition.
5
5
  Project-URL: Documentation, https://github.com/niart120/ponkan-python/blob/master/docs/api.md
6
6
  Project-URL: Homepage, https://github.com/niart120/ponkan-python
@@ -44,7 +44,8 @@ Description-Content-Type: text/markdown
44
44
  - raw frame の保存と metadata 記録
45
45
  - RGB8 `numpy.ndarray` への変換
46
46
  - Pillow 互換出力
47
- - libusb async transfer による streaming MVP
47
+ - profile / layout / device discovery metadata の提供
48
+ - D3XX / D3XX native backend による streaming MVP
48
49
 
49
50
  詳細は次の仕様書を参照してください。
50
51
 
@@ -59,7 +60,7 @@ Python 3.12 以上を対象にしています。現在の検証基準は Python
59
60
  pip install ponkan-python
60
61
  ```
61
62
 
62
- Windows の FTDI D3XX backend では、通常依存として PyD3XX を利用します。PNG 変換には Pillow extra を追加します。
63
+ Windows の FTDI D3XX backend では、通常依存として PyD3XX を利用します。D3XX 用の optional extra はありません。PNG 変換には Pillow extra を追加します。
63
64
 
64
65
  ```console
65
66
  pip install "ponkan-python[image]"
@@ -87,6 +88,8 @@ with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
87
88
  top_bgr = cap.read()
88
89
  ```
89
90
 
91
+ `backend="auto"` は Windows では `d3xx-native` に解決されます。従来の sequential D3XX path を使う場合は `backend="d3xx"` を明示します。`libusb` は discovery / lower-level path では使われますが、high-level `open_capture()` では現在未対応です。
92
+
90
93
  3DS 固有の上画面・下画面・sequence などが必要な場合は `read_frame()` を使います。
91
94
 
92
95
  ```python
@@ -112,7 +115,7 @@ ponkan-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_
112
115
  ponkan-stream-n3dsxl --duration 10 --stats
113
116
  ```
114
117
 
115
- 実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
118
+ `ponkan-list-devices` は libusb descriptor path で FTDI-family device を分類し、N3DSXL command は送信しません。実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
116
119
 
117
120
  ## Development
118
121
 
@@ -11,7 +11,8 @@
11
11
  - raw frame の保存と metadata 記録
12
12
  - RGB8 `numpy.ndarray` への変換
13
13
  - Pillow 互換出力
14
- - libusb async transfer による streaming MVP
14
+ - profile / layout / device discovery metadata の提供
15
+ - D3XX / D3XX native backend による streaming MVP
15
16
 
16
17
  詳細は次の仕様書を参照してください。
17
18
 
@@ -26,7 +27,7 @@ Python 3.12 以上を対象にしています。現在の検証基準は Python
26
27
  pip install ponkan-python
27
28
  ```
28
29
 
29
- Windows の FTDI D3XX backend では、通常依存として PyD3XX を利用します。PNG 変換には Pillow extra を追加します。
30
+ Windows の FTDI D3XX backend では、通常依存として PyD3XX を利用します。D3XX 用の optional extra はありません。PNG 変換には Pillow extra を追加します。
30
31
 
31
32
  ```console
32
33
  pip install "ponkan-python[image]"
@@ -54,6 +55,8 @@ with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
54
55
  top_bgr = cap.read()
55
56
  ```
56
57
 
58
+ `backend="auto"` は Windows では `d3xx-native` に解決されます。従来の sequential D3XX path を使う場合は `backend="d3xx"` を明示します。`libusb` は discovery / lower-level path では使われますが、high-level `open_capture()` では現在未対応です。
59
+
57
60
  3DS 固有の上画面・下画面・sequence などが必要な場合は `read_frame()` を使います。
58
61
 
59
62
  ```python
@@ -79,7 +82,7 @@ ponkan-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_
79
82
  ponkan-stream-n3dsxl --duration 10 --stats
80
83
  ```
81
84
 
82
- 実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
85
+ `ponkan-list-devices` は libusb descriptor path で FTDI-family device を分類し、N3DSXL command は送信しません。実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
83
86
 
84
87
  ## Development
85
88
 
@@ -0,0 +1,440 @@
1
+ # API Reference
2
+
3
+ `ponkan` exposes a small public API for new 3DS XL capture board frame
4
+ acquisition. The current package is focused on 2D N3DSXL video capture and does
5
+ not provide GUI, audio playback, recording, old DS, Optimize, Nisetro, or IS
6
+ device support.
7
+
8
+ ## Installation
9
+
10
+ ```console
11
+ pip install ponkan-python
12
+ pip install "ponkan-python[image]"
13
+ ```
14
+
15
+ Use the `image` extra when calling `CaptureFrame.to_pillow()` or the
16
+ `ponkan-raw-to-png` command. On Windows, the D3XX backend uses PyD3XX as a
17
+ normal platform-gated dependency.
18
+
19
+ ## Top-Level Imports
20
+
21
+ The package root exports the high-level reader, profile/layout/discovery
22
+ metadata, and size helpers:
23
+
24
+ ```python
25
+ from ponkan import (
26
+ ACCEPTED_N3DSXL_PRODUCT_IDS,
27
+ ACCEPTED_N3DSXL_PRODUCT_STRINGS,
28
+ N3DSXL_VENDOR_ID,
29
+ CaptureConfig,
30
+ CaptureDeviceDiscovery,
31
+ CaptureDeviceInfo,
32
+ CaptureLayout,
33
+ CaptureOutput,
34
+ CaptureProfile,
35
+ CaptureReader,
36
+ CaptureSizes,
37
+ CompositeOutputInfo,
38
+ ScreenInfo,
39
+ UnknownCaptureLayout,
40
+ UnknownCaptureProfile,
41
+ capture_sizes,
42
+ get_capture_layout,
43
+ get_capture_profile,
44
+ list_capture_devices,
45
+ list_capture_layouts,
46
+ list_capture_profiles,
47
+ open_capture,
48
+ )
49
+ ```
50
+
51
+ `__version__` is read from installed package metadata. In an editable source
52
+ tree without installed metadata it falls back to `"0.0.0"`.
53
+
54
+ ## Capture Profiles
55
+
56
+ The profile registry describes implemented capture targets without enumerating,
57
+ opening, or sending commands to USB devices.
58
+
59
+ ```python
60
+ from ponkan import get_capture_profile, list_capture_profiles
61
+
62
+ profiles = list_capture_profiles()
63
+ n3dsxl = get_capture_profile("n3dsxl")
64
+ same_profile = get_capture_profile("new_3ds_xl")
65
+ ```
66
+
67
+ `list_capture_profiles()` returns an immutable tuple of `CaptureProfile`
68
+ metadata. The initial runtime registry contains only `n3dsxl`; future devices
69
+ such as old 3DS, classic DS, Optimize, Nisetro, and IS-family devices are not
70
+ returned before their source audit and implementation gates are complete.
71
+
72
+ `CaptureProfile` fields are stable metadata for UI and adapter selection:
73
+
74
+ | Field | N3DSXL value | Notes |
75
+ | --- | --- | --- |
76
+ | `id` | `"n3dsxl"` | Stable profile id for settings. |
77
+ | `display_name` | `"new 3DS XL"` | Human-readable label for UI. |
78
+ | `model` | `"new_3ds_xl"` | Model string accepted by `CaptureConfig`. |
79
+ | `aliases` | `("new_3ds_xl",)` | Compatibility with the existing model name. |
80
+ | `family` | `"3ds"` | Device family grouping. |
81
+ | `provider` | `"ponkan-python"` | Implementation provider for the profile. |
82
+ | `support_status` | `"stable"` | Runtime profiles are `"stable"` or `"experimental"`. |
83
+ | `default_output` | `"both_vertical"` | Matches `CaptureConfig.output`. |
84
+ | `default_colorspace` | `"RGB"` | Package default channel order. |
85
+ | `supported_colorspaces` | `("RGB", "BGR")` | Use `"BGR"` explicitly for OpenCV consumers. |
86
+ | `native_fps` | `59.8` | Initial observed N3DSXL streaming rate. |
87
+ | `screen_layout` | `"3ds_dual_screen"` | Layout metadata id for later lookup. |
88
+ | `supported_outputs` | `("top", "bottom", "both_vertical")` | Matches current `CaptureOutput` values. |
89
+ | `supports_3d` | `False` | 3D capture is outside the current MVP. |
90
+ | `supports_audio` | `False` | Audio playback/capture is outside the current MVP. |
91
+ | `supports_recording` | `False` | Recording is outside the current MVP. |
92
+
93
+ `get_capture_profile()` accepts the stable id or alias and raises
94
+ `UnknownCaptureProfile`, a `CaptureError` subclass, for unknown profile ids.
95
+
96
+ ## Future Profile Roadmap
97
+
98
+ The runtime profile registry intentionally returns only implemented profiles.
99
+ The default list is `("n3dsxl",)`; future or unsupported device families are
100
+ not exposed to normal UI selection before their source audit and implementation
101
+ gates are complete.
102
+
103
+ | target / family | roadmap state | runtime registry |
104
+ | --- | --- | --- |
105
+ | `n3dsxl` / `new_3ds_xl` | implemented | Returned by `list_capture_profiles()`. |
106
+ | `old3ds` / `o3ds` | audit required | Not returned before source audit, spec, tests, and hardware gate planning. |
107
+ | `classic_ds` | audit required | Not returned before protocol, identity, command, and layout audit. |
108
+ | `optimize` | out of scope | Not returned. |
109
+ | `nisetro` | out of scope | Not returned. |
110
+ | `is_nitro` / `is_twl` / `partner_ctr` | out of scope | Not returned. |
111
+
112
+ Source audit for a future runtime profile must record VID/PID, product string
113
+ policy, command request values, endpoints/interfaces, raw capture structure,
114
+ screen layout, safe listing behavior, and the first hardware gate plan. The
115
+ audit record belongs in a dedicated source-audit Work Unit before runtime code
116
+ or public profile metadata is added.
117
+
118
+ runtime profile promotion:
119
+
120
+ ```text
121
+ audit required -> audited:
122
+ identity / command / layout facts are recorded from cc3dsfs sources.
123
+
124
+ audited -> experimental:
125
+ implementation exists and unit / characterization tests pass.
126
+
127
+ experimental -> stable:
128
+ hardware E2E, performance / shutdown gates, docs, and public API tests pass.
129
+ ```
130
+
131
+ ## Layout Metadata
132
+
133
+ Layout metadata describes the screens and output shapes exposed by profile APIs.
134
+ It does not allocate image buffers, open devices, or decode frames.
135
+
136
+ ```python
137
+ from ponkan import get_capture_layout, get_capture_profile
138
+
139
+ profile = get_capture_profile("n3dsxl")
140
+ layout = get_capture_layout(profile.screen_layout)
141
+ both_vertical = next(output for output in layout.outputs if output.id == "both_vertical")
142
+ preview_shape = both_vertical.ndarray_shape
143
+ ```
144
+
145
+ `list_capture_layouts()` returns the implemented runtime layouts. The initial
146
+ registry contains only `3ds_dual_screen`:
147
+
148
+ | Field | N3DSXL value | Notes |
149
+ | --- | --- | --- |
150
+ | `id` | `"3ds_dual_screen"` | Stable layout id referenced by `CaptureProfile.screen_layout`. |
151
+ | `screens` | `top`, `bottom` | `top_right` is not exposed while 3D capture is unsupported. |
152
+ | `outputs` | `top`, `bottom`, `both_vertical` | Matches current `CaptureOutput` values. |
153
+ | `aspect_hints["bottom_horizontal_offset"]` | `40` | Bottom screen is centered under the top screen. |
154
+
155
+ `ScreenInfo.ndarray_shape` and `CompositeOutputInfo.ndarray_shape` expose the
156
+ public `numpy.ndarray` shape as `(height, width, channels)`.
157
+
158
+ `ScreenInfo` fields are `id`, `display_name`, `width`, `height`, `channels`,
159
+ `colorspace`, `coordinate_space`, and `role`. `CompositeOutputInfo` fields are
160
+ `id`, `display_name`, `width`, `height`, `channels`, `screens`, `placement`,
161
+ and `default`. `CaptureLayout.aspect_hints` is a read-only mapping for
162
+ display/preview hints such as bottom-screen centering.
163
+
164
+ | Output | Shape | Placement |
165
+ | --- | --- | --- |
166
+ | `top` | `(240, 400, 3)` | Single top screen. |
167
+ | `bottom` | `(240, 320, 3)` | Single bottom screen. |
168
+ | `both_vertical` | `(480, 400, 3)` | Top screen above centered bottom screen. |
169
+
170
+ `get_capture_layout()` raises `UnknownCaptureLayout`, a `CaptureError`
171
+ subclass with `code="unsupported_layout"`, for unknown layout ids.
172
+
173
+ ## High-Level Capture
174
+
175
+ ### `open_capture(...) -> CaptureReader`
176
+
177
+ Open a high-level streaming reader for an accepted new 3DS XL capture board.
178
+
179
+ ```python
180
+ from ponkan import CaptureOutput, open_capture
181
+
182
+ with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
183
+ image = cap.read()
184
+ ```
185
+
186
+ Arguments:
187
+
188
+ | Argument | Type | Default | Notes |
189
+ | --- | --- | --- | --- |
190
+ | `source` | `int` or `str` | `0` | `0` and `"new_3ds_xl"` are accepted. |
191
+ | `config` | `CaptureConfig` or `None` | `None` | Base configuration. Explicit keyword overrides win. |
192
+ | `backend` | one of `auto`, `libusb`, `d3xx`, `d3xx-native` | `None` | Backend preference. On Windows, `auto` resolves to `d3xx-native`. |
193
+ | `output` | `CaptureOutput`, `str`, or `None` | `None` | Default layout returned by `read()`. |
194
+ | `colorspace` | `RGB`, `BGR`, or `None` | `None` | Default channel order returned by `read()`. |
195
+ | `read_timeout` | `float` or `None` | unchanged | Default timeout in seconds. |
196
+
197
+ Raises:
198
+
199
+ | Exception | Meaning |
200
+ | --- | --- |
201
+ | `DeviceNotFound` | No accepted N3DSXL device is visible to the selected backend. |
202
+ | `UnsupportedOperation` | The requested source, model, mode, or backend path is outside current scope. |
203
+ | `ValueError` | A config field such as backend, colorspace, queue size, or timeout is invalid. |
204
+ | `Ftd3CommandError` | Hardware command or bulk transfer setup failed. |
205
+
206
+ The reader owns the streaming engine and backend handle. Prefer `with
207
+ open_capture(...) as cap:` so `close()` is called even when reads fail.
208
+
209
+ ### `CaptureConfig`
210
+
211
+ `CaptureConfig` groups the high-level reader settings.
212
+
213
+ | Field | Default | Notes |
214
+ | --- | --- | --- |
215
+ | `source` | `0` | Source selector. |
216
+ | `model` | `"new_3ds_xl"` | Only new 3DS XL is supported. |
217
+ | `backend` | `"auto"` | On Windows this resolves to `"d3xx-native"`. PyD3XX is a normal Windows platform dependency, not an optional extra. |
218
+ | `mode_3d` | `False` | `True` is rejected in the current MVP. |
219
+ | `output` | `CaptureOutput.BOTH_VERTICAL` | Default layout for `read()`. |
220
+ | `colorspace` | `"RGB"` | `"BGR"` is useful for OpenCV. |
221
+ | `raw_slots` | `2` | Number of backend raw read slots. |
222
+ | `output_queue_size` | `2` | Decoded frame queue capacity. |
223
+ | `drop_policy` | `"drop_oldest"` | One of `"drop_oldest"`, `"drop_newest"`, or `"block"`. |
224
+ | `poll_interval` | `0.004` | Poll sleep in seconds while waiting for frames. |
225
+ | `read_timeout` | `1.0` | `None` waits indefinitely. |
226
+ | `collect_timing` | `False` | Enables timing samples in streaming stats. |
227
+
228
+ ### `CaptureReader`
229
+
230
+ `CaptureReader.read()` returns a copied `numpy.ndarray` or `None` on timeout.
231
+
232
+ ```python
233
+ top_bgr = cap.read(output=CaptureOutput.TOP, colorspace="BGR")
234
+ ```
235
+
236
+ `CaptureReader.read_frame()` returns a `CaptureFrame` with separate top and
237
+ bottom screens:
238
+
239
+ ```python
240
+ frame = cap.read_frame(timeout=0.5)
241
+ if frame is not None:
242
+ top = frame.top
243
+ bottom = frame.bottom
244
+ ```
245
+
246
+ `CaptureReader.stats()` returns a `StreamStats` snapshot from the underlying
247
+ streaming engine. `CaptureReader.close()` is idempotent and releases the backend even before the first read.
248
+
249
+ Backend selection note: starting with the current unreleased changes,
250
+ `backend="auto"` shares the discovery resolver and uses `"d3xx-native"` on
251
+ Windows. The sequential D3XX path remains available only through
252
+ `backend="d3xx"`. The `"libusb"` literal is accepted as a config value for
253
+ discovery parity, but the high-level opener currently rejects it with
254
+ `UnsupportedOperation`.
255
+
256
+ ## Frames
257
+
258
+ ### `CaptureFrame`
259
+
260
+ `CaptureFrame` stores decoded RGB8 arrays:
261
+
262
+ | Attribute | Shape | Notes |
263
+ | --- | --- | --- |
264
+ | `top` | `(240, 400, 3)` | Top screen RGB8 image. |
265
+ | `bottom` | `(240, 320, 3)` | Bottom screen RGB8 image. |
266
+ | `top_right` | `None` or `(240, 400, 3)` | Right-eye top screen for 3D captures. Currently `None` for MVP reads. |
267
+
268
+ Methods:
269
+
270
+ | Method | Purpose |
271
+ | --- | --- |
272
+ | `to_ndarray(screen="top", colorspace="RGB")` | Return a copied RGB or BGR array for one screen. |
273
+ | `to_pillow(screen="top")` | Return a Pillow RGB image. Requires `ponkan-python[image]`. |
274
+ | `to_mosaic(gap=0)` | Return top and centered bottom screens in one RGB array. |
275
+
276
+ `DecodeError` is raised for unavailable screens, invalid shapes, invalid dtypes,
277
+ or unsupported color-space conversion.
278
+
279
+ ## Raw Capture Artifacts
280
+
281
+ ### `RawCapture`
282
+
283
+ `RawCapture` represents one raw transfer plus metadata. The `video_region()`
284
+ method returns the leading RGB8 video bytes and excludes audio, unused, and
285
+ error-buffer regions. `to_metadata()` returns JSON-serializable sidecar data.
286
+
287
+ ### `save_raw_capture(capture, out_path, force=False)`
288
+
289
+ Write a raw payload and metadata sidecar using the same stem:
290
+
291
+ ```python
292
+ from pathlib import Path
293
+ from ponkan.capture import save_raw_capture
294
+
295
+ bin_path, metadata_path = save_raw_capture(capture, Path("captures/raw_2d_001.bin"))
296
+ ```
297
+
298
+ The function returns `(bin_path, metadata_path)` and raises `FileExistsError`
299
+ unless `force=True` is provided.
300
+
301
+ ## Device Discovery
302
+
303
+ ```python
304
+ from ponkan import list_capture_devices
305
+
306
+ discovery = list_capture_devices(profile="n3dsxl", backend="auto")
307
+ ```
308
+
309
+ The discovery layer does not send N3DSXL commands. It only classifies
310
+ descriptors and reports backend availability:
311
+
312
+ | Field | Meaning |
313
+ | --- | --- |
314
+ | `profile_id` | Resolved profile id such as `"n3dsxl"`. |
315
+ | `backend_preference` | Caller preference such as `"auto"` or `"libusb"`. |
316
+ | `resolved_backend` | Concrete backend used for enumeration. Windows `"auto"` resolves to `"d3xx-native"`. |
317
+ | `backend_status` | `"available"`, `"unavailable"`, or `"unsupported"`. |
318
+ | `reason` | Shared `CaptureReason` such as `"available"`, `"device_not_found"`, or `"missing_package"`. |
319
+ | `remediation` | Optional backend-level recovery guidance. |
320
+ | `devices` | Tuple of `CaptureDeviceInfo` descriptors. |
321
+
322
+ `include_rejected=True` includes FTDI-family devices rejected by the N3DSXL
323
+ safety boundary. Rejected devices are useful for diagnostics but should not be
324
+ offered as normal capture targets.
325
+
326
+ `CaptureDeviceInfo` fields:
327
+
328
+ | Field | Meaning |
329
+ | --- | --- |
330
+ | `id` | Backend-prefixed stable-or-best-effort identifier. |
331
+ | `display_name` | Product string or fallback human-readable label. |
332
+ | `profile_id` | Profile this descriptor was classified for. |
333
+ | `model` | Resolved capture model, or `"unknown"` for rejected devices. |
334
+ | `backend` | Concrete backend that enumerated the descriptor. |
335
+ | `backend_preference` | Original caller preference. |
336
+ | `vendor_id` / `product_id` | USB identity fields when visible. |
337
+ | `serial_number` | Serial number when visible. |
338
+ | `product_string` | Product string when readable. |
339
+ | `product_string_status` | `"accepted"`, `"unreadable"`, `"rejected"`, or `"unknown"`. |
340
+ | `connection_status` | `"available"`, `"rejected"`, `"unsupported"`, or `"unknown"`. |
341
+ | `id_stability` | `"stable"` for serial ids, `"session"` for bus/address ids, or `"unknown"`. |
342
+ | `reason` | Device-level `CaptureReason`. |
343
+ | `remediation` | Optional diagnostic detail such as a rejected product-string reason. |
344
+
345
+ Dependency absence, such as missing PyD3XX, is returned as
346
+ `backend_status="unavailable"`. Native backend API failures while enumerating
347
+ descriptors may still propagate as `CaptureError` subclasses such as
348
+ `D3xxBackendError`; those failures expose backend-specific `function`,
349
+ `status`, and `field_name` attributes.
350
+
351
+ Accepted device identity is constrained by `N3DSXL_VENDOR_ID`,
352
+ `ACCEPTED_N3DSXL_PRODUCT_IDS`, and `ACCEPTED_N3DSXL_PRODUCT_STRINGS`.
353
+
354
+ ## Size Helpers
355
+
356
+ ```python
357
+ from ponkan import capture_sizes
358
+
359
+ sizes = capture_sizes(mode_3d=False)
360
+ print(sizes.video_size, sizes.capture_size)
361
+ ```
362
+
363
+ `CaptureSizes` exposes the video payload size, audio buffer size, pre-alignment
364
+ structure size, aligned capture size, and maximum non-error transfer length.
365
+ These helpers are the public source for raw frame size calculations.
366
+
367
+ ## Streaming Stats
368
+
369
+ `StreamStats` contains mutable counters for submitted, completed, decoded,
370
+ delivered, dropped, cancelled, USB error, and decode error counts. Use
371
+ `snapshot()` before reporting shared counters, and `to_dict()` for JSON output.
372
+
373
+ `PerformanceStats.from_stream_stats(...)` builds JSON-serializable smoke-test
374
+ reports, including optional timing summaries when `collect_timing=True`.
375
+
376
+ ## Command Line Tools
377
+
378
+ Installed console scripts:
379
+
380
+ | Command | Purpose |
381
+ | --- | --- |
382
+ | `ponkan-list-devices` | Print accepted and rejected FTDI-family devices through the libusb descriptor path without sending N3DSXL commands. |
383
+ | `ponkan-capture-raw --out <path>` | Capture one raw frame and metadata sidecar. |
384
+ | `ponkan-raw-to-png <raw> --metadata <json> --out <dir>` | Decode raw video to top and bottom PNG files. |
385
+ | `ponkan-stream-n3dsxl --duration 10 --stats` | Run a bounded streaming smoke loop and print counters. |
386
+
387
+ Hardware commands should only be run after confirming the device identity and
388
+ the project hardware safety policy.
389
+
390
+ ## Error Types
391
+
392
+ All package-level failures inherit from `CaptureError`.
393
+
394
+ Every `CaptureError` exposes common structured fields while preserving the
395
+ existing exception class hierarchy and `str(error)` message:
396
+
397
+ | Field | Meaning |
398
+ | --- | --- |
399
+ | `code` | Stable error category such as `"device_not_found"` or `"decode_failed"`. |
400
+ | `profile` | Capture profile context when known, such as `"n3dsxl"`. |
401
+ | `backend` | Backend context when known, such as `"d3xx"` or `"d3xx-native"`. |
402
+ | `reason` | Shared discovery/error reason such as `"missing_package"` or `"open_failed"`. |
403
+ | `recoverable` | Whether reconnect, install, driver, or settings changes may recover. |
404
+ | `remediation` | Short user-facing recovery guidance when available. |
405
+
406
+ ```python
407
+ from ponkan.errors import CaptureError
408
+ from ponkan.transport.d3xx_backend import D3xxBackendError
409
+
410
+ try:
411
+ ...
412
+ except CaptureError as exc:
413
+ technical_log = exc.to_dict()
414
+ status_code = exc.code
415
+ ```
416
+
417
+ | Error | Typical cause |
418
+ | --- | --- |
419
+ | `UnsupportedDevice` | Device identity did not pass the N3DSXL safety boundary. |
420
+ | `DeviceNotFound` | No accepted device is visible. |
421
+ | `DeviceOpenError` | USB open, configuration, interface claim, release, or close failed. |
422
+ | `Ftd3CommandError` | Pipe command, read, or write failed. |
423
+ | `UnsupportedOperation` | Requested behavior is outside current MVP scope. |
424
+ | `TransferOverflow` | Transfer length exceeds the accepted capture size. |
425
+ | `DecodeError` | Raw bytes or decoded frame data cannot be interpreted. |
426
+ | `DependencyUnavailableError` | A runtime dependency required by the selected backend is unavailable. |
427
+ | `OptionalDependencyError` | Optional dependency such as Pillow is missing. |
428
+ | `UnknownCaptureProfile` | A profile id or alias is not in the runtime profile registry. |
429
+ | `UnknownCaptureLayout` | A layout id is not in the runtime layout registry. |
430
+ | `D3xxBackendError` | Native D3XX binding call or descriptor parsing failed. |
431
+
432
+ `D3xxBackendError` is transport-specific and is imported from
433
+ `ponkan.transport.d3xx_backend`, not from the package root. It preserves the
434
+ existing message format and exposes common structured fields:
435
+ `code="d3xx_backend_failed"`, `backend="d3xx"`, `recoverable=True`, and
436
+ `reason="open_failed"` for native API/open-path failures. Descriptor parsing
437
+ failures such as missing or invalid detail fields use `reason="read_failed"`.
438
+
439
+ For technical logs, `D3xxBackendError` also carries backend-specific context
440
+ through `function`, `status`, and `field_name`.
@@ -65,16 +65,20 @@ uv run ruff format --check .
65
65
  uv run ruff check .
66
66
  uv run ty check --no-progress
67
67
  uv run pytest tests/unit
68
+ Remove-Item -ErrorAction SilentlyContinue dist\ponkan_python-*.whl, dist\ponkan_python-*.tar.gz
68
69
  uv build
69
- uvx --from twine twine check dist\*
70
+ uvx --from twine twine check dist\ponkan_python-X.Y.Z-py3-none-any.whl dist\ponkan_python-X.Y.Z.tar.gz
70
71
  git diff --check
71
72
  ```
72
73
 
73
- The build should create both an sdist and a wheel under `dist/`. Check the wheel
74
- contains the import package and typing marker:
74
+ The cleanup keeps `dist/.gitignore` and removes stale wheel / sdist artifacts
75
+ from earlier releases. The build should create both an sdist and a wheel for the
76
+ candidate version under `dist/`. Check the candidate wheel by exact path; do not
77
+ use `next(Path("dist").glob("*.whl"))`, because stale artifacts can make that
78
+ select an older release.
75
79
 
76
80
  ```console
77
- uv run python -c "import pathlib, zipfile; wheel=next(pathlib.Path('dist').glob('*.whl')); names=set(zipfile.ZipFile(wheel).namelist()); assert 'ponkan/__init__.py' in names; assert 'ponkan/py.typed' in names"
81
+ uv run python -c "import pathlib, zipfile; wheel=pathlib.Path('dist/ponkan_python-X.Y.Z-py3-none-any.whl'); assert wheel.exists(); names=set(zipfile.ZipFile(wheel).namelist()); assert 'ponkan/__init__.py' in names; assert 'ponkan/py.typed' in names; assert not any(name.startswith('py3dscapture/') for name in names)"
78
82
  ```
79
83
 
80
84
  ## TestPyPI
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ponkan-python"
3
- version = "0.1.2"
3
+ version = "0.2.1"
4
4
  description = "A Python capture library focused on new 3DS XL capture board frame acquisition."
5
5
  readme = { file = "README.md", content-type = "text/markdown" }
6
6
  authors = [
@@ -0,0 +1,68 @@
1
+ """Python helpers for new 3DS XL capture board frame acquisition.
2
+
3
+ The package root exposes the high-level reader, supported profile/layout
4
+ metadata, safe device discovery helpers, and size constants needed by typical
5
+ callers. Lower-level decode, transport, and streaming APIs live in their
6
+ dedicated submodules.
7
+ """
8
+
9
+ from importlib.metadata import PackageNotFoundError, version
10
+
11
+ from ponkan.capture import CaptureConfig, CaptureOutput, CaptureReader, open_capture
12
+ from ponkan.devices.discovery import (
13
+ CaptureDeviceDiscovery,
14
+ CaptureDeviceInfo,
15
+ list_capture_devices,
16
+ )
17
+ from ponkan.layouts import (
18
+ CaptureLayout,
19
+ CompositeOutputInfo,
20
+ ScreenInfo,
21
+ UnknownCaptureLayout,
22
+ get_capture_layout,
23
+ list_capture_layouts,
24
+ )
25
+ from ponkan.profiles import (
26
+ CaptureProfile,
27
+ UnknownCaptureProfile,
28
+ get_capture_profile,
29
+ list_capture_profiles,
30
+ )
31
+ from ponkan.protocol.sizes import (
32
+ ACCEPTED_N3DSXL_PRODUCT_IDS,
33
+ ACCEPTED_N3DSXL_PRODUCT_STRINGS,
34
+ N3DSXL_VENDOR_ID,
35
+ CaptureSizes,
36
+ capture_sizes,
37
+ )
38
+
39
+ try:
40
+ __version__ = version("ponkan-python")
41
+ except PackageNotFoundError:
42
+ __version__ = "0.0.0"
43
+
44
+ __all__ = [
45
+ "ACCEPTED_N3DSXL_PRODUCT_IDS",
46
+ "ACCEPTED_N3DSXL_PRODUCT_STRINGS",
47
+ "N3DSXL_VENDOR_ID",
48
+ "CaptureConfig",
49
+ "CaptureDeviceDiscovery",
50
+ "CaptureDeviceInfo",
51
+ "CaptureLayout",
52
+ "CaptureOutput",
53
+ "CaptureProfile",
54
+ "CaptureReader",
55
+ "CaptureSizes",
56
+ "CompositeOutputInfo",
57
+ "ScreenInfo",
58
+ "UnknownCaptureLayout",
59
+ "UnknownCaptureProfile",
60
+ "__version__",
61
+ "capture_sizes",
62
+ "get_capture_layout",
63
+ "get_capture_profile",
64
+ "list_capture_devices",
65
+ "list_capture_layouts",
66
+ "list_capture_profiles",
67
+ "open_capture",
68
+ ]