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.
- ponkan_python-0.1.0/.gitignore +21 -0
- ponkan_python-0.1.0/LICENSE +22 -0
- ponkan_python-0.1.0/NOTICE.md +14 -0
- ponkan_python-0.1.0/PKG-INFO +157 -0
- ponkan_python-0.1.0/README.md +123 -0
- ponkan_python-0.1.0/docs/api.md +232 -0
- ponkan_python-0.1.0/docs/publishing.md +84 -0
- ponkan_python-0.1.0/pyproject.toml +166 -0
- ponkan_python-0.1.0/src/py3dscapture/__init__.py +36 -0
- ponkan_python-0.1.0/src/py3dscapture/artifacts.py +66 -0
- ponkan_python-0.1.0/src/py3dscapture/capture.py +599 -0
- ponkan_python-0.1.0/src/py3dscapture/devices/__init__.py +1 -0
- ponkan_python-0.1.0/src/py3dscapture/devices/n3dsxl_ftd3.py +238 -0
- ponkan_python-0.1.0/src/py3dscapture/errors.py +120 -0
- ponkan_python-0.1.0/src/py3dscapture/hardware_gate.py +143 -0
- ponkan_python-0.1.0/src/py3dscapture/image/__init__.py +1 -0
- ponkan_python-0.1.0/src/py3dscapture/image/frame.py +166 -0
- ponkan_python-0.1.0/src/py3dscapture/protocol/__init__.py +1 -0
- ponkan_python-0.1.0/src/py3dscapture/protocol/layout_3ds.py +60 -0
- ponkan_python-0.1.0/src/py3dscapture/protocol/n3dsxl.py +249 -0
- ponkan_python-0.1.0/src/py3dscapture/protocol/sizes.py +128 -0
- ponkan_python-0.1.0/src/py3dscapture/py.typed +1 -0
- ponkan_python-0.1.0/src/py3dscapture/streaming/__init__.py +1 -0
- ponkan_python-0.1.0/src/py3dscapture/streaming/buffers.py +156 -0
- ponkan_python-0.1.0/src/py3dscapture/streaming/engine.py +285 -0
- ponkan_python-0.1.0/src/py3dscapture/streaming/policies.py +157 -0
- ponkan_python-0.1.0/src/py3dscapture/streaming/stats.py +254 -0
- ponkan_python-0.1.0/src/py3dscapture/tools/__init__.py +1 -0
- ponkan_python-0.1.0/src/py3dscapture/tools/capture_raw.py +44 -0
- ponkan_python-0.1.0/src/py3dscapture/tools/list_devices.py +68 -0
- ponkan_python-0.1.0/src/py3dscapture/tools/raw_to_png.py +251 -0
- ponkan_python-0.1.0/src/py3dscapture/tools/stream_n3dsxl.py +152 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/__init__.py +1 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_backend.py +850 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_native.py +268 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_native_streaming.py +306 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/d3xx_streaming.py +202 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/ftd3_backend.py +275 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/ftd3_pipe.py +387 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/libusb_async.py +134 -0
- ponkan_python-0.1.0/src/py3dscapture/transport/libusb_backend.py +357 -0
- ponkan_python-0.1.0/tests/conftest.py +33 -0
- ponkan_python-0.1.0/tests/e2e/README.md +6 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_connect.py +30 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_d3xx_backend.py +120 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_d3xx_native_streaming.py +79 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_ftd3_pipe.py +26 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_high_level_capture_read_api.py +44 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_open_close.py +22 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_raw_capture.py +37 -0
- ponkan_python-0.1.0/tests/e2e/test_n3dsxl_streaming.py +72 -0
- ponkan_python-0.1.0/tests/manual/test_n3dsxl_decoder_visual.py +94 -0
- ponkan_python-0.1.0/tests/performance/README.md +6 -0
- ponkan_python-0.1.0/tests/performance/test_n3dsxl_d3xx_native_streaming_smoke.py +82 -0
- ponkan_python-0.1.0/tests/performance/test_n3dsxl_streaming_smoke.py +75 -0
- ponkan_python-0.1.0/tests/unit/test_d3xx_backend.py +235 -0
- ponkan_python-0.1.0/tests/unit/test_d3xx_native_api.py +77 -0
- ponkan_python-0.1.0/tests/unit/test_d3xx_native_streaming_backend.py +237 -0
- ponkan_python-0.1.0/tests/unit/test_d3xx_streaming_backend.py +129 -0
- ponkan_python-0.1.0/tests/unit/test_ftd3_backend_selector.py +132 -0
- ponkan_python-0.1.0/tests/unit/test_ftd3_pipe_payloads.py +147 -0
- ponkan_python-0.1.0/tests/unit/test_hardware_gate.py +88 -0
- ponkan_python-0.1.0/tests/unit/test_high_level_capture_read_api.py +288 -0
- ponkan_python-0.1.0/tests/unit/test_layout_3ds_decoder.py +273 -0
- ponkan_python-0.1.0/tests/unit/test_libusb_backend.py +101 -0
- ponkan_python-0.1.0/tests/unit/test_n3dsxl_artifacts.py +32 -0
- ponkan_python-0.1.0/tests/unit/test_n3dsxl_connect_sequence.py +273 -0
- ponkan_python-0.1.0/tests/unit/test_n3dsxl_device_filter.py +56 -0
- ponkan_python-0.1.0/tests/unit/test_n3dsxl_list_devices_cli.py +65 -0
- ponkan_python-0.1.0/tests/unit/test_n3dsxl_session.py +136 -0
- ponkan_python-0.1.0/tests/unit/test_n3dsxl_sizes.py +49 -0
- ponkan_python-0.1.0/tests/unit/test_package.py +36 -0
- ponkan_python-0.1.0/tests/unit/test_raw_capture_metadata.py +76 -0
- ponkan_python-0.1.0/tests/unit/test_stream_n3dsxl_cli.py +132 -0
- ponkan_python-0.1.0/tests/unit/test_streaming_buffers.py +34 -0
- ponkan_python-0.1.0/tests/unit/test_streaming_engine_fake_async.py +290 -0
- ponkan_python-0.1.0/tests/unit/test_streaming_performance_stats.py +130 -0
- 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
|
+
```
|