ponkan-python 0.1.0__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 (78) hide show
  1. ponkan_python-0.1.0/.gitignore +21 -0
  2. ponkan_python-0.1.0/LICENSE +22 -0
  3. ponkan_python-0.1.0/NOTICE.md +14 -0
  4. ponkan_python-0.1.0/PKG-INFO +157 -0
  5. ponkan_python-0.1.0/README.md +123 -0
  6. ponkan_python-0.1.0/docs/api.md +232 -0
  7. ponkan_python-0.1.0/docs/publishing.md +84 -0
  8. ponkan_python-0.1.0/pyproject.toml +166 -0
  9. ponkan_python-0.1.0/src/py3dscapture/__init__.py +36 -0
  10. ponkan_python-0.1.0/src/py3dscapture/artifacts.py +66 -0
  11. ponkan_python-0.1.0/src/py3dscapture/capture.py +599 -0
  12. ponkan_python-0.1.0/src/py3dscapture/devices/__init__.py +1 -0
  13. ponkan_python-0.1.0/src/py3dscapture/devices/n3dsxl_ftd3.py +238 -0
  14. ponkan_python-0.1.0/src/py3dscapture/errors.py +120 -0
  15. ponkan_python-0.1.0/src/py3dscapture/hardware_gate.py +143 -0
  16. ponkan_python-0.1.0/src/py3dscapture/image/__init__.py +1 -0
  17. ponkan_python-0.1.0/src/py3dscapture/image/frame.py +166 -0
  18. ponkan_python-0.1.0/src/py3dscapture/protocol/__init__.py +1 -0
  19. ponkan_python-0.1.0/src/py3dscapture/protocol/layout_3ds.py +60 -0
  20. ponkan_python-0.1.0/src/py3dscapture/protocol/n3dsxl.py +249 -0
  21. ponkan_python-0.1.0/src/py3dscapture/protocol/sizes.py +128 -0
  22. ponkan_python-0.1.0/src/py3dscapture/py.typed +1 -0
  23. ponkan_python-0.1.0/src/py3dscapture/streaming/__init__.py +1 -0
  24. ponkan_python-0.1.0/src/py3dscapture/streaming/buffers.py +156 -0
  25. ponkan_python-0.1.0/src/py3dscapture/streaming/engine.py +285 -0
  26. ponkan_python-0.1.0/src/py3dscapture/streaming/policies.py +157 -0
  27. ponkan_python-0.1.0/src/py3dscapture/streaming/stats.py +254 -0
  28. ponkan_python-0.1.0/src/py3dscapture/tools/__init__.py +1 -0
  29. ponkan_python-0.1.0/src/py3dscapture/tools/capture_raw.py +44 -0
  30. ponkan_python-0.1.0/src/py3dscapture/tools/list_devices.py +68 -0
  31. ponkan_python-0.1.0/src/py3dscapture/tools/raw_to_png.py +251 -0
  32. ponkan_python-0.1.0/src/py3dscapture/tools/stream_n3dsxl.py +152 -0
  33. ponkan_python-0.1.0/src/py3dscapture/transport/__init__.py +1 -0
  34. ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_backend.py +850 -0
  35. ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_native.py +268 -0
  36. ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_native_streaming.py +306 -0
  37. ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_streaming.py +202 -0
  38. ponkan_python-0.1.0/src/py3dscapture/transport/ftd3_backend.py +275 -0
  39. ponkan_python-0.1.0/src/py3dscapture/transport/ftd3_pipe.py +387 -0
  40. ponkan_python-0.1.0/src/py3dscapture/transport/libusb_async.py +134 -0
  41. ponkan_python-0.1.0/src/py3dscapture/transport/libusb_backend.py +357 -0
  42. ponkan_python-0.1.0/tests/conftest.py +33 -0
  43. ponkan_python-0.1.0/tests/e2e/README.md +6 -0
  44. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_connect.py +30 -0
  45. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_d3xx_backend.py +120 -0
  46. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_d3xx_native_streaming.py +79 -0
  47. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_ftd3_pipe.py +26 -0
  48. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_high_level_capture_read_api.py +44 -0
  49. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_open_close.py +22 -0
  50. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_raw_capture.py +37 -0
  51. ponkan_python-0.1.0/tests/e2e/test_n3dsxl_streaming.py +72 -0
  52. ponkan_python-0.1.0/tests/manual/test_n3dsxl_decoder_visual.py +94 -0
  53. ponkan_python-0.1.0/tests/performance/README.md +6 -0
  54. ponkan_python-0.1.0/tests/performance/test_n3dsxl_d3xx_native_streaming_smoke.py +82 -0
  55. ponkan_python-0.1.0/tests/performance/test_n3dsxl_streaming_smoke.py +75 -0
  56. ponkan_python-0.1.0/tests/unit/test_d3xx_backend.py +235 -0
  57. ponkan_python-0.1.0/tests/unit/test_d3xx_native_api.py +77 -0
  58. ponkan_python-0.1.0/tests/unit/test_d3xx_native_streaming_backend.py +237 -0
  59. ponkan_python-0.1.0/tests/unit/test_d3xx_streaming_backend.py +129 -0
  60. ponkan_python-0.1.0/tests/unit/test_ftd3_backend_selector.py +132 -0
  61. ponkan_python-0.1.0/tests/unit/test_ftd3_pipe_payloads.py +147 -0
  62. ponkan_python-0.1.0/tests/unit/test_hardware_gate.py +88 -0
  63. ponkan_python-0.1.0/tests/unit/test_high_level_capture_read_api.py +288 -0
  64. ponkan_python-0.1.0/tests/unit/test_layout_3ds_decoder.py +273 -0
  65. ponkan_python-0.1.0/tests/unit/test_libusb_backend.py +101 -0
  66. ponkan_python-0.1.0/tests/unit/test_n3dsxl_artifacts.py +32 -0
  67. ponkan_python-0.1.0/tests/unit/test_n3dsxl_connect_sequence.py +273 -0
  68. ponkan_python-0.1.0/tests/unit/test_n3dsxl_device_filter.py +56 -0
  69. ponkan_python-0.1.0/tests/unit/test_n3dsxl_list_devices_cli.py +65 -0
  70. ponkan_python-0.1.0/tests/unit/test_n3dsxl_session.py +136 -0
  71. ponkan_python-0.1.0/tests/unit/test_n3dsxl_sizes.py +49 -0
  72. ponkan_python-0.1.0/tests/unit/test_package.py +36 -0
  73. ponkan_python-0.1.0/tests/unit/test_raw_capture_metadata.py +76 -0
  74. ponkan_python-0.1.0/tests/unit/test_stream_n3dsxl_cli.py +132 -0
  75. ponkan_python-0.1.0/tests/unit/test_streaming_buffers.py +34 -0
  76. ponkan_python-0.1.0/tests/unit/test_streaming_engine_fake_async.py +290 -0
  77. ponkan_python-0.1.0/tests/unit/test_streaming_performance_stats.py +130 -0
  78. ponkan_python-0.1.0/tests/unit/test_streaming_policies.py +52 -0
@@ -0,0 +1,21 @@
1
+ # Python-generated files
2
+ __pycache__/
3
+ *.py[oc]
4
+ build/
5
+ dist/
6
+ wheels/
7
+ *.egg-info
8
+ .coverage
9
+ htmlcov/
10
+ .pytest_cache/
11
+ .ruff_cache/
12
+ .ty/
13
+ .uv-cache/
14
+
15
+ # Virtual environments
16
+ .venv
17
+
18
+ # Local capture outputs
19
+ artifacts/
20
+ captures/
21
+ *.log
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 niart120
4
+ Copyright (c) 2024 Lorenzooone
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
@@ -0,0 +1,14 @@
1
+ # Notices
2
+
3
+ `ponkan-python` is licensed under the MIT License.
4
+
5
+ This project references protocol behavior, constants, and implementation
6
+ structure from `cc3dsfs`:
7
+
8
+ - Project: https://github.com/Lorenzooone/cc3dsfs
9
+ - Author: Lorenzooone
10
+ - License: MIT License
11
+ - Copyright: Copyright (c) 2024 Lorenzooone
12
+
13
+ `ponkan-python` is a focused Python library for new 3DS XL capture board frame
14
+ acquisition. It is not a full compatibility port of `cc3dsfs`.
@@ -0,0 +1,157 @@
1
+ Metadata-Version: 2.4
2
+ Name: ponkan-python
3
+ Version: 0.1.0
4
+ Summary: A Python capture library focused on new 3DS XL capture board frame acquisition.
5
+ Project-URL: Documentation, https://github.com/niart120/ponkan-python/blob/master/docs/api.md
6
+ Project-URL: Homepage, https://github.com/niart120/ponkan-python
7
+ Project-URL: Issues, https://github.com/niart120/ponkan-python/issues
8
+ Project-URL: Repository, https://github.com/niart120/ponkan-python.git
9
+ Author-email: niart120 <38847256+niart120@users.noreply.github.com>
10
+ Maintainer-email: niart120 <38847256+niart120@users.noreply.github.com>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ License-File: NOTICE.md
14
+ Keywords: 3ds,capture-card,n3dsxl,new-3ds-xl,usb,video-capture
15
+ Classifier: Development Status :: 2 - Pre-Alpha
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Operating System :: Microsoft :: Windows
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Multimedia :: Video :: Capture
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: <3.14,>=3.12
25
+ Requires-Dist: libusb1>=3.3.1
26
+ Requires-Dist: numpy>=2.0
27
+ Provides-Extra: d3xx
28
+ Requires-Dist: pyd3xx>=1.1.4; extra == 'd3xx'
29
+ Provides-Extra: image
30
+ Requires-Dist: pillow>=10.0; extra == 'image'
31
+ Provides-Extra: opencv
32
+ Requires-Dist: opencv-python>=4.10; extra == 'opencv'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # ponkan-python
36
+
37
+ `ponkan-python` は、new 3DS XL capture board から USB 経由で映像フレームを取得するための Python ライブラリです。
38
+
39
+ このプロジェクトは [`cc3dsfs`](https://github.com/Lorenzooone/cc3dsfs) を参照しながら、個人用途で必要な N3DSXL 映像取得機能に絞って Python で再構成するものです。`cc3dsfs` 全体の代替や互換 API を提供することは目的にしていません。継続的なメンテナンスや対応 device の拡張は未定です。
40
+
41
+ ## Current Scope
42
+
43
+ - new 3DS XL capture board の device 認識
44
+ - raw frame 取得
45
+ - raw frame の保存と metadata 記録
46
+ - RGB8 `numpy.ndarray` への変換
47
+ - Pillow 互換出力
48
+ - libusb async transfer による streaming MVP
49
+
50
+ 詳細は次の仕様書を参照してください。
51
+
52
+ - `spec/initial/cc3dsfs_python_rebuild_spec.md`
53
+ - `spec/initial/cc3dsfs_python_n3dsxl_implementation_workflow.md`
54
+
55
+ ## Installation
56
+
57
+ Python 3.12 / 3.13 を対象にしています。
58
+
59
+ ```console
60
+ pip install ponkan-python
61
+ ```
62
+
63
+ PNG 変換には Pillow extra、FTDI D3XX backend には D3XX extra を追加します。
64
+
65
+ ```console
66
+ pip install "ponkan-python[image]"
67
+ pip install "ponkan-python[d3xx]"
68
+ ```
69
+
70
+ ## Usage
71
+
72
+ 高レベル API では、new 3DS XL capture board を開いて `read()` で RGB8 `numpy.ndarray` を取得できます。
73
+
74
+ ```python
75
+ from py3dscapture import CaptureOutput, open_capture
76
+
77
+ with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
78
+ image = cap.read()
79
+ if image is not None:
80
+ print(image.shape)
81
+ ```
82
+
83
+ 上画面だけを読む場合は `CaptureOutput.TOP` を指定します。OpenCV へ渡す場合は `colorspace="BGR"` を指定できます。
84
+
85
+ ```python
86
+ from py3dscapture import CaptureOutput, open_capture
87
+
88
+ with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
89
+ top_bgr = cap.read()
90
+ ```
91
+
92
+ 3DS 固有の上画面・下画面・sequence などが必要な場合は `read_frame()` を使います。
93
+
94
+ ```python
95
+ from py3dscapture import open_capture
96
+
97
+ with open_capture() as cap:
98
+ frame = cap.read_frame()
99
+ if frame is not None:
100
+ top = frame.top
101
+ bottom = frame.bottom
102
+ ```
103
+
104
+ API の詳細は [API Reference](https://github.com/niart120/ponkan-python/blob/master/docs/api.md) を参照してください。
105
+
106
+ ## Command Line Tools
107
+
108
+ インストール後は次の console scripts を利用できます。
109
+
110
+ ```console
111
+ py3dscapture-list-devices
112
+ py3dscapture-capture-raw --out captures/n3dsxl/raw_2d_001.bin
113
+ py3dscapture-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_2d_001.json --out captures/n3dsxl/png
114
+ py3dscapture-stream-n3dsxl --duration 10 --stats
115
+ ```
116
+
117
+ 実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
118
+
119
+ ## Development
120
+
121
+ Python 実行と依存管理は `uv` を使います。
122
+
123
+ ```console
124
+ uv sync --dev
125
+ scripts/install-git-hooks.ps1
126
+ uv run ruff format --check .
127
+ uv run ruff check .
128
+ uv run ty check --no-progress
129
+ uv run pytest tests/unit
130
+ ```
131
+
132
+ 実機 new 3DS XL capture board を使うテストは通常 CI では実行しません。
133
+
134
+ ```console
135
+ $env:PONKAN_RUN_N3DSXL = "1"
136
+ uv run pytest -m requires_n3dsxl tests/e2e
137
+ ```
138
+
139
+ ## Safety
140
+
141
+ N3DSXL command は、VID/PID と product string が仕様で許可された device にだけ送ります。未知の FTDI device を N3DSXL として扱わないでください。
142
+
143
+ Git hooks は `.githooks/` に配置しています。clone 後に `scripts/install-git-hooks.ps1` または `sh scripts/install-git-hooks.sh` を実行すると、`core.hooksPath` が `.githooks` に設定されます。
144
+
145
+ Codex project-local policy は `.codex/` に配置しています。Codex で有効にするには、この project layer を trust し、`/hooks` で hook を review/trust してください。
146
+
147
+ ## License and Attribution
148
+
149
+ This project is licensed under the MIT License.
150
+
151
+ This project references `cc3dsfs` by Lorenzooone, which is also licensed under
152
+ the MIT License. The upstream copyright notice is preserved in `LICENSE` and
153
+ `NOTICE.md`.
154
+
155
+ - https://github.com/Lorenzooone/cc3dsfs
156
+
157
+ Release and publishing notes are kept in [Publishing](https://github.com/niart120/ponkan-python/blob/master/docs/publishing.md).
@@ -0,0 +1,123 @@
1
+ # ponkan-python
2
+
3
+ `ponkan-python` は、new 3DS XL capture board から USB 経由で映像フレームを取得するための Python ライブラリです。
4
+
5
+ このプロジェクトは [`cc3dsfs`](https://github.com/Lorenzooone/cc3dsfs) を参照しながら、個人用途で必要な N3DSXL 映像取得機能に絞って Python で再構成するものです。`cc3dsfs` 全体の代替や互換 API を提供することは目的にしていません。継続的なメンテナンスや対応 device の拡張は未定です。
6
+
7
+ ## Current Scope
8
+
9
+ - new 3DS XL capture board の device 認識
10
+ - raw frame 取得
11
+ - raw frame の保存と metadata 記録
12
+ - RGB8 `numpy.ndarray` への変換
13
+ - Pillow 互換出力
14
+ - libusb async transfer による streaming MVP
15
+
16
+ 詳細は次の仕様書を参照してください。
17
+
18
+ - `spec/initial/cc3dsfs_python_rebuild_spec.md`
19
+ - `spec/initial/cc3dsfs_python_n3dsxl_implementation_workflow.md`
20
+
21
+ ## Installation
22
+
23
+ Python 3.12 / 3.13 を対象にしています。
24
+
25
+ ```console
26
+ pip install ponkan-python
27
+ ```
28
+
29
+ PNG 変換には Pillow extra、FTDI D3XX backend には D3XX extra を追加します。
30
+
31
+ ```console
32
+ pip install "ponkan-python[image]"
33
+ pip install "ponkan-python[d3xx]"
34
+ ```
35
+
36
+ ## Usage
37
+
38
+ 高レベル API では、new 3DS XL capture board を開いて `read()` で RGB8 `numpy.ndarray` を取得できます。
39
+
40
+ ```python
41
+ from py3dscapture import CaptureOutput, open_capture
42
+
43
+ with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
44
+ image = cap.read()
45
+ if image is not None:
46
+ print(image.shape)
47
+ ```
48
+
49
+ 上画面だけを読む場合は `CaptureOutput.TOP` を指定します。OpenCV へ渡す場合は `colorspace="BGR"` を指定できます。
50
+
51
+ ```python
52
+ from py3dscapture import CaptureOutput, open_capture
53
+
54
+ with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
55
+ top_bgr = cap.read()
56
+ ```
57
+
58
+ 3DS 固有の上画面・下画面・sequence などが必要な場合は `read_frame()` を使います。
59
+
60
+ ```python
61
+ from py3dscapture import open_capture
62
+
63
+ with open_capture() as cap:
64
+ frame = cap.read_frame()
65
+ if frame is not None:
66
+ top = frame.top
67
+ bottom = frame.bottom
68
+ ```
69
+
70
+ API の詳細は [API Reference](https://github.com/niart120/ponkan-python/blob/master/docs/api.md) を参照してください。
71
+
72
+ ## Command Line Tools
73
+
74
+ インストール後は次の console scripts を利用できます。
75
+
76
+ ```console
77
+ py3dscapture-list-devices
78
+ py3dscapture-capture-raw --out captures/n3dsxl/raw_2d_001.bin
79
+ py3dscapture-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_2d_001.json --out captures/n3dsxl/png
80
+ py3dscapture-stream-n3dsxl --duration 10 --stats
81
+ ```
82
+
83
+ 実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
84
+
85
+ ## Development
86
+
87
+ Python 実行と依存管理は `uv` を使います。
88
+
89
+ ```console
90
+ uv sync --dev
91
+ scripts/install-git-hooks.ps1
92
+ uv run ruff format --check .
93
+ uv run ruff check .
94
+ uv run ty check --no-progress
95
+ uv run pytest tests/unit
96
+ ```
97
+
98
+ 実機 new 3DS XL capture board を使うテストは通常 CI では実行しません。
99
+
100
+ ```console
101
+ $env:PONKAN_RUN_N3DSXL = "1"
102
+ uv run pytest -m requires_n3dsxl tests/e2e
103
+ ```
104
+
105
+ ## Safety
106
+
107
+ N3DSXL command は、VID/PID と product string が仕様で許可された device にだけ送ります。未知の FTDI device を N3DSXL として扱わないでください。
108
+
109
+ Git hooks は `.githooks/` に配置しています。clone 後に `scripts/install-git-hooks.ps1` または `sh scripts/install-git-hooks.sh` を実行すると、`core.hooksPath` が `.githooks` に設定されます。
110
+
111
+ Codex project-local policy は `.codex/` に配置しています。Codex で有効にするには、この project layer を trust し、`/hooks` で hook を review/trust してください。
112
+
113
+ ## License and Attribution
114
+
115
+ This project is licensed under the MIT License.
116
+
117
+ This project references `cc3dsfs` by Lorenzooone, which is also licensed under
118
+ the MIT License. The upstream copyright notice is preserved in `LICENSE` and
119
+ `NOTICE.md`.
120
+
121
+ - https://github.com/Lorenzooone/cc3dsfs
122
+
123
+ Release and publishing notes are kept in [Publishing](https://github.com/niart120/ponkan-python/blob/master/docs/publishing.md).
@@ -0,0 +1,232 @@
1
+ # API Reference
2
+
3
+ `py3dscapture` 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 Extras
9
+
10
+ ```console
11
+ pip install ponkan-python
12
+ pip install "ponkan-python[image]"
13
+ pip install "ponkan-python[d3xx]"
14
+ ```
15
+
16
+ Use the `image` extra when calling `CaptureFrame.to_pillow()` or the
17
+ `py3dscapture-raw-to-png` command. Use the `d3xx` extra when selecting the D3XX
18
+ backend.
19
+
20
+ ## Top-Level Imports
21
+
22
+ The package root exports the high-level reader and size helpers:
23
+
24
+ ```python
25
+ from py3dscapture import (
26
+ ACCEPTED_N3DSXL_PRODUCT_IDS,
27
+ ACCEPTED_N3DSXL_PRODUCT_STRINGS,
28
+ N3DSXL_VENDOR_ID,
29
+ CaptureConfig,
30
+ CaptureOutput,
31
+ CaptureReader,
32
+ CaptureSizes,
33
+ capture_sizes,
34
+ open_capture,
35
+ )
36
+ ```
37
+
38
+ `__version__` is read from installed package metadata. In an editable source
39
+ tree without installed metadata it falls back to `"0.0.0"`.
40
+
41
+ ## High-Level Capture
42
+
43
+ ### `open_capture(...) -> CaptureReader`
44
+
45
+ Open a high-level streaming reader for an accepted new 3DS XL capture board.
46
+
47
+ ```python
48
+ from py3dscapture import CaptureOutput, open_capture
49
+
50
+ with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
51
+ image = cap.read()
52
+ ```
53
+
54
+ Arguments:
55
+
56
+ | Argument | Type | Default | Notes |
57
+ | --- | --- | --- | --- |
58
+ | `source` | `int` or `str` | `0` | `0` and `"new_3ds_xl"` are accepted. |
59
+ | `config` | `CaptureConfig` or `None` | `None` | Base configuration. Explicit keyword overrides win. |
60
+ | `backend` | one of `auto`, `libusb`, `d3xx`, `d3xx-native` | `None` | Backend preference. `auto` currently resolves to D3XX. |
61
+ | `output` | `CaptureOutput`, `str`, or `None` | `None` | Default layout returned by `read()`. |
62
+ | `colorspace` | `RGB`, `BGR`, or `None` | `None` | Default channel order returned by `read()`. |
63
+ | `read_timeout` | `float` or `None` | unchanged | Default timeout in seconds. |
64
+
65
+ Raises:
66
+
67
+ | Exception | Meaning |
68
+ | --- | --- |
69
+ | `DeviceNotFound` | No accepted N3DSXL device is visible to the selected backend. |
70
+ | `UnsupportedOperation` | The requested source, model, mode, or backend path is outside current scope. |
71
+ | `ValueError` | A config field such as backend, colorspace, queue size, or timeout is invalid. |
72
+ | `Ftd3CommandError` | Hardware command or bulk transfer setup failed. |
73
+
74
+ The reader owns the streaming engine and backend handle. Prefer `with
75
+ open_capture(...) as cap:` so `close()` is called even when reads fail.
76
+
77
+ ### `CaptureConfig`
78
+
79
+ `CaptureConfig` groups the high-level reader settings.
80
+
81
+ | Field | Default | Notes |
82
+ | --- | --- | --- |
83
+ | `source` | `0` | Source selector. |
84
+ | `model` | `"new_3ds_xl"` | Only new 3DS XL is supported. |
85
+ | `backend` | `"auto"` | `"d3xx"` and `"d3xx-native"` require the `d3xx` extra. |
86
+ | `mode_3d` | `False` | `True` is rejected in the current MVP. |
87
+ | `output` | `CaptureOutput.BOTH_VERTICAL` | Default layout for `read()`. |
88
+ | `colorspace` | `"RGB"` | `"BGR"` is useful for OpenCV. |
89
+ | `raw_slots` | `2` | Number of backend raw read slots. |
90
+ | `output_queue_size` | `2` | Decoded frame queue capacity. |
91
+ | `drop_policy` | `"drop_oldest"` | One of `"drop_oldest"`, `"drop_newest"`, or `"block"`. |
92
+ | `poll_interval` | `0.004` | Poll sleep in seconds while waiting for frames. |
93
+ | `read_timeout` | `1.0` | `None` waits indefinitely. |
94
+ | `collect_timing` | `False` | Enables timing samples in streaming stats. |
95
+
96
+ ### `CaptureReader`
97
+
98
+ `CaptureReader.read()` returns a copied `numpy.ndarray` or `None` on timeout.
99
+
100
+ ```python
101
+ top_bgr = cap.read(output=CaptureOutput.TOP, colorspace="BGR")
102
+ ```
103
+
104
+ `CaptureReader.read_frame()` returns a `CaptureFrame` with separate top and
105
+ bottom screens:
106
+
107
+ ```python
108
+ frame = cap.read_frame(timeout=0.5)
109
+ if frame is not None:
110
+ top = frame.top
111
+ bottom = frame.bottom
112
+ ```
113
+
114
+ `CaptureReader.stats()` returns a `StreamStats` snapshot from the underlying
115
+ streaming engine. `CaptureReader.close()` is idempotent and stops acquisition.
116
+
117
+ ## Frames
118
+
119
+ ### `CaptureFrame`
120
+
121
+ `CaptureFrame` stores decoded RGB8 arrays:
122
+
123
+ | Attribute | Shape | Notes |
124
+ | --- | --- | --- |
125
+ | `top` | `(240, 400, 3)` | Top screen RGB8 image. |
126
+ | `bottom` | `(240, 320, 3)` | Bottom screen RGB8 image. |
127
+ | `top_right` | `None` or `(240, 400, 3)` | Right-eye top screen for 3D captures. Currently `None` for MVP reads. |
128
+
129
+ Methods:
130
+
131
+ | Method | Purpose |
132
+ | --- | --- |
133
+ | `to_ndarray(screen="top", colorspace="RGB")` | Return a copied RGB or BGR array for one screen. |
134
+ | `to_pillow(screen="top")` | Return a Pillow RGB image. Requires `ponkan-python[image]`. |
135
+ | `to_mosaic(gap=0)` | Return top and centered bottom screens in one RGB array. |
136
+
137
+ `DecodeError` is raised for unavailable screens, invalid shapes, invalid dtypes,
138
+ or unsupported color-space conversion.
139
+
140
+ ## Raw Capture Artifacts
141
+
142
+ ### `RawCapture`
143
+
144
+ `RawCapture` represents one raw transfer plus metadata. The `video_region()`
145
+ method returns the leading RGB8 video bytes and excludes audio, unused, and
146
+ error-buffer regions. `to_metadata()` returns JSON-serializable sidecar data.
147
+
148
+ ### `save_raw_capture(capture, out_path, force=False)`
149
+
150
+ Write a raw payload and metadata sidecar using the same stem:
151
+
152
+ ```python
153
+ from pathlib import Path
154
+ from py3dscapture.capture import save_raw_capture
155
+
156
+ bin_path, metadata_path = save_raw_capture(capture, Path("captures/raw_2d_001.bin"))
157
+ ```
158
+
159
+ The function returns `(bin_path, metadata_path)` and raises `FileExistsError`
160
+ unless `force=True` is provided.
161
+
162
+ ## Device Discovery
163
+
164
+ ```python
165
+ from py3dscapture.devices.n3dsxl_ftd3 import list_n3dsxl_devices
166
+ from py3dscapture.transport.libusb_backend import Usb1Backend
167
+
168
+ listing = list_n3dsxl_devices(Usb1Backend())
169
+ ```
170
+
171
+ The discovery layer does not send N3DSXL commands. It only classifies USB
172
+ descriptors:
173
+
174
+ | Type | Meaning |
175
+ | --- | --- |
176
+ | `DeviceCandidate` | Accepted VID/PID and accepted or unreadable product string. |
177
+ | `RejectedDevice` | FTDI-family device rejected before commands may be sent. |
178
+ | `DeviceListing` | Tuple groups of candidates and rejected devices. |
179
+
180
+ Accepted device identity is constrained by `N3DSXL_VENDOR_ID`,
181
+ `ACCEPTED_N3DSXL_PRODUCT_IDS`, and `ACCEPTED_N3DSXL_PRODUCT_STRINGS`.
182
+
183
+ ## Size Helpers
184
+
185
+ ```python
186
+ from py3dscapture import capture_sizes
187
+
188
+ sizes = capture_sizes(mode_3d=False)
189
+ print(sizes.video_size, sizes.capture_size)
190
+ ```
191
+
192
+ `CaptureSizes` exposes the video payload size, audio buffer size, pre-alignment
193
+ structure size, aligned capture size, and maximum non-error transfer length.
194
+ These helpers are the public source for raw frame size calculations.
195
+
196
+ ## Streaming Stats
197
+
198
+ `StreamStats` contains mutable counters for submitted, completed, decoded,
199
+ delivered, dropped, cancelled, USB error, and decode error counts. Use
200
+ `snapshot()` before reporting shared counters, and `to_dict()` for JSON output.
201
+
202
+ `PerformanceStats.from_stream_stats(...)` builds JSON-serializable smoke-test
203
+ reports, including optional timing summaries when `collect_timing=True`.
204
+
205
+ ## Command Line Tools
206
+
207
+ Installed console scripts:
208
+
209
+ | Command | Purpose |
210
+ | --- | --- |
211
+ | `py3dscapture-list-devices` | Print accepted and rejected FTDI-family devices without sending N3DSXL commands. |
212
+ | `py3dscapture-capture-raw --out <path>` | Capture one raw frame and metadata sidecar. |
213
+ | `py3dscapture-raw-to-png <raw> --metadata <json> --out <dir>` | Decode raw video to top and bottom PNG files. |
214
+ | `py3dscapture-stream-n3dsxl --duration 10 --stats` | Run a bounded streaming smoke loop and print counters. |
215
+
216
+ Hardware commands should only be run after confirming the device identity and
217
+ the project hardware safety policy.
218
+
219
+ ## Error Types
220
+
221
+ All package-level failures inherit from `CaptureError`.
222
+
223
+ | Error | Typical cause |
224
+ | --- | --- |
225
+ | `UnsupportedDevice` | Device identity did not pass the N3DSXL safety boundary. |
226
+ | `DeviceNotFound` | No accepted device is visible. |
227
+ | `DeviceOpenError` | USB open, configuration, interface claim, release, or close failed. |
228
+ | `Ftd3CommandError` | Pipe command, read, or write failed. |
229
+ | `UnsupportedOperation` | Requested behavior is outside current MVP scope. |
230
+ | `TransferOverflow` | Transfer length exceeds the accepted capture size. |
231
+ | `DecodeError` | Raw bytes or decoded frame data cannot be interpreted. |
232
+ | `OptionalDependencyError` | Optional dependency such as Pillow or PyD3XX is missing. |
@@ -0,0 +1,84 @@
1
+ # Publishing
2
+
3
+ This project is prepared for PyPI publication with local builds and GitHub
4
+ Actions Trusted Publishing. No PyPI API token is required when the PyPI project
5
+ has a matching trusted publisher.
6
+
7
+ ## Package Metadata
8
+
9
+ - Distribution name: `ponkan-python`
10
+ - Import package: `py3dscapture`
11
+ - Python support: `>=3.12, <3.14`
12
+ - License expression: `MIT`
13
+ - License files: `LICENSE`, `NOTICE.md`
14
+ - Repository: `https://github.com/niart120/ponkan-python`
15
+ - Publish workflow: `.github/workflows/publish.yml`
16
+
17
+ ## Local Release Check
18
+
19
+ Run these checks before creating a release tag:
20
+
21
+ ```console
22
+ uv sync --dev
23
+ uv run ruff format --check .
24
+ uv run ruff check .
25
+ uv run ty check --no-progress
26
+ uv run pytest tests/unit
27
+ uv build
28
+ ```
29
+
30
+ The build should create both an sdist and wheel under `dist/`.
31
+
32
+ ## TestPyPI
33
+
34
+ Create a Trusted Publisher for TestPyPI with:
35
+
36
+ | Field | Value |
37
+ | --- | --- |
38
+ | Project name | `ponkan-python` |
39
+ | Owner | `niart120` |
40
+ | Repository name | `ponkan-python` |
41
+ | Workflow filename | `publish.yml` |
42
+ | Environment name | `testpypi` |
43
+
44
+ Then run the `Publish` workflow manually from GitHub Actions. The manual
45
+ workflow path publishes only to TestPyPI.
46
+
47
+ ## PyPI
48
+
49
+ Create or configure the PyPI project and Trusted Publisher with:
50
+
51
+ | Field | Value |
52
+ | --- | --- |
53
+ | Project name | `ponkan-python` |
54
+ | Owner | `niart120` |
55
+ | Repository name | `ponkan-python` |
56
+ | Workflow filename | `publish.yml` |
57
+ | Environment name | `pypi` |
58
+
59
+ The `pypi` GitHub environment should require manual approval before deployment.
60
+ After the project and trusted publisher are ready, pushing a version tag starts
61
+ the PyPI publish job:
62
+
63
+ ```console
64
+ git tag v0.1.0
65
+ git push origin v0.1.0
66
+ ```
67
+
68
+ The workflow builds the distribution once, stores it as a workflow artifact, and
69
+ publishes the same artifact to the selected package index.
70
+
71
+ ## Post-Publish Smoke Check
72
+
73
+ After upload, verify installation in a clean environment:
74
+
75
+ ```console
76
+ uvx --from ponkan-python py3dscapture-list-devices
77
+ ```
78
+
79
+ For optional features:
80
+
81
+ ```console
82
+ uvx --from "ponkan-python[image]" py3dscapture-raw-to-png --help
83
+ uvx --from "ponkan-python[d3xx]" py3dscapture-list-devices
84
+ ```