ponkan-python 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. ponkan_python-0.1.0.dist-info/METADATA +157 -0
  2. ponkan_python-0.1.0.dist-info/RECORD +39 -0
  3. ponkan_python-0.1.0.dist-info/WHEEL +4 -0
  4. ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
  5. ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
  6. ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
  7. py3dscapture/__init__.py +36 -0
  8. py3dscapture/artifacts.py +66 -0
  9. py3dscapture/capture.py +599 -0
  10. py3dscapture/devices/__init__.py +1 -0
  11. py3dscapture/devices/n3dsxl_ftd3.py +238 -0
  12. py3dscapture/errors.py +120 -0
  13. py3dscapture/hardware_gate.py +143 -0
  14. py3dscapture/image/__init__.py +1 -0
  15. py3dscapture/image/frame.py +166 -0
  16. py3dscapture/protocol/__init__.py +1 -0
  17. py3dscapture/protocol/layout_3ds.py +60 -0
  18. py3dscapture/protocol/n3dsxl.py +249 -0
  19. py3dscapture/protocol/sizes.py +128 -0
  20. py3dscapture/py.typed +1 -0
  21. py3dscapture/streaming/__init__.py +1 -0
  22. py3dscapture/streaming/buffers.py +156 -0
  23. py3dscapture/streaming/engine.py +285 -0
  24. py3dscapture/streaming/policies.py +157 -0
  25. py3dscapture/streaming/stats.py +254 -0
  26. py3dscapture/tools/__init__.py +1 -0
  27. py3dscapture/tools/capture_raw.py +44 -0
  28. py3dscapture/tools/list_devices.py +68 -0
  29. py3dscapture/tools/raw_to_png.py +251 -0
  30. py3dscapture/tools/stream_n3dsxl.py +152 -0
  31. py3dscapture/transport/__init__.py +1 -0
  32. py3dscapture/transport/d3xx_backend.py +850 -0
  33. py3dscapture/transport/d3xx_native.py +268 -0
  34. py3dscapture/transport/d3xx_native_streaming.py +306 -0
  35. py3dscapture/transport/d3xx_streaming.py +202 -0
  36. py3dscapture/transport/ftd3_backend.py +275 -0
  37. py3dscapture/transport/ftd3_pipe.py +387 -0
  38. py3dscapture/transport/libusb_async.py +134 -0
  39. py3dscapture/transport/libusb_backend.py +357 -0
@@ -0,0 +1,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,39 @@
1
+ py3dscapture/__init__.py,sha256=1BdGPUhO7y--e5L2hqSnxhiHaRua_5aZ872T6vkEWz0,997
2
+ py3dscapture/artifacts.py,sha256=E5C63HfEnkQBeXH0E-oQ1_NhhzJYcYYNUrw5S-OtUL8,1961
3
+ py3dscapture/capture.py,sha256=L7wfW25safua22VRjDXfvjNduzwOW-jNP7j73LLzxNM,20262
4
+ py3dscapture/errors.py,sha256=S-f6yGSYaQH1y8X2loeRSiANwiDOzCRdnMt6441EQC0,3695
5
+ py3dscapture/hardware_gate.py,sha256=FClF7ckNH9kTXy833YgwDuKuGBkoAGFkDkf5IlBDsms,4834
6
+ py3dscapture/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
7
+ py3dscapture/devices/__init__.py,sha256=uYvgYIgcwciikPR23c_p674XuJDKTamUH0PKV3ECXiE,30
8
+ py3dscapture/devices/n3dsxl_ftd3.py,sha256=md6WyM9W1n-VY5L7uEhZbjWdTO044-oR4onkacJpwrM,8405
9
+ py3dscapture/image/__init__.py,sha256=-23f78dfqU2Q-WOIvYCqstSexYId_K3sP8pBn7tkUQU,38
10
+ py3dscapture/image/frame.py,sha256=yQ4gtMgFXv9DR72kgezi3oOKvaVYfXrNFCgpTc4h8Ok,5800
11
+ py3dscapture/protocol/__init__.py,sha256=lCr27_-ula3CtVd5nzTFbhEARAoiMecGEv8n8Q_xH6I,48
12
+ py3dscapture/protocol/layout_3ds.py,sha256=sqRbBqHe_VSkPp8zso5iVVk8Yc-sEH9CZLyD05ZiBXA,1968
13
+ py3dscapture/protocol/n3dsxl.py,sha256=_fpiWGoHle7qgtMk59o1YdM_HDldHxQZE2mgN_4F-b0,8454
14
+ py3dscapture/protocol/sizes.py,sha256=AlI9Ge-Dk6Rx8UI4eF2VVRpxcZ_pCEuC46TVc-qmJxQ,4129
15
+ py3dscapture/streaming/__init__.py,sha256=30b10h-HyMhyGW0emIJ1Cc_189kolDxuNoYMfft05Hc,35
16
+ py3dscapture/streaming/buffers.py,sha256=03ku6ZWkWwo4b6q9gnYaJmoee7zqur9WEkEUyHe6tI8,4727
17
+ py3dscapture/streaming/engine.py,sha256=wvuiF074n546FuzsQeYi9EYutcYPmNSjzrLoYE_-Yzg,10791
18
+ py3dscapture/streaming/policies.py,sha256=lXsNQJROi7IYZPJkLNvJn1xG8dqfE5-OiKb0RqFjiJE,4320
19
+ py3dscapture/streaming/stats.py,sha256=WT7q16CPtOel95xGn3uG6iXSzA15WOEMjlSWJ3hbzWY,8534
20
+ py3dscapture/tools/__init__.py,sha256=tMgzvLN5Tq0ia16r9UUMA6QOZ8NOHjwJRuS0KSk9LAg,28
21
+ py3dscapture/tools/capture_raw.py,sha256=mDL68bfAGD3nFI4rmAkvJ7QolE7X6ay3MN5u6XmaYuk,1508
22
+ py3dscapture/tools/list_devices.py,sha256=kVD1mHHcU0qtWf9pIwakP_j80b_Ar2tMofksioGEfMA,2325
23
+ py3dscapture/tools/raw_to_png.py,sha256=qnP-To6p4tg7-y4vDke07Oy0zPzv9Yk12fVHhuux-_I,8026
24
+ py3dscapture/tools/stream_n3dsxl.py,sha256=8A9vsiB5nsdLdSsuvmrXw6XPpIzgEex94-tmN5QHe2o,5347
25
+ py3dscapture/transport/__init__.py,sha256=zp3na4DRpaD2_RCvB5rGxdZW7xOahfhmJpdvvpPpBFI,29
26
+ py3dscapture/transport/d3xx_backend.py,sha256=EBg0dtaHxGak929h1JJuFxrOajr-ZgzCo_89qZQtqVs,26946
27
+ py3dscapture/transport/d3xx_native.py,sha256=3Njbl0GwEy_YXrfhAa3y67GZ3OdF87lL3twQNYueUYw,9019
28
+ py3dscapture/transport/d3xx_native_streaming.py,sha256=gwIqHEyX8XM4wj50n0qW6enupOzrBiaz9rhcRmI73w8,10914
29
+ py3dscapture/transport/d3xx_streaming.py,sha256=JvxfnF58Q6sVT9ZlnvRBfnydweeJDHZ_OTkUmbCkKug,6699
30
+ py3dscapture/transport/ftd3_backend.py,sha256=k8wceyVq8OYTILK7E8SYwOghmVd3TQCMt4W-xR5SxqQ,7795
31
+ py3dscapture/transport/ftd3_pipe.py,sha256=M8CCdkHvdIMKD2NePzIWcst9cD4_guf5kZ9T-YwuhTQ,12679
32
+ py3dscapture/transport/libusb_async.py,sha256=OHR1mBIrdCJP7n9RVj1WO8xjwMqC55UaKTdpT3J5BrE,4135
33
+ py3dscapture/transport/libusb_backend.py,sha256=DxUOsGgPPxiJtosf_KUbf1JpPeHAJxBcybRHeW1loBs,11037
34
+ ponkan_python-0.1.0.dist-info/METADATA,sha256=n7aJ3Ui81Kum0U-8e7Qegw9ysft61WkLqd2qFeYl5ZY,5746
35
+ ponkan_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
36
+ ponkan_python-0.1.0.dist-info/entry_points.txt,sha256=fX1my2fuKlmDn6T0PxrWSeXKmO5PsVpTfl7BYEqtYkc,274
37
+ ponkan_python-0.1.0.dist-info/licenses/LICENSE,sha256=ikr_NtR46ZO2hvTX0LtCeb9wbRb19pCcY97Hw_6VA6c,1096
38
+ ponkan_python-0.1.0.dist-info/licenses/NOTICE.md,sha256=KZPWtflkTM1GTH5e5UP7OvP7D8xYJotWUxgiePabylc,445
39
+ ponkan_python-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.30.1
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,5 @@
1
+ [console_scripts]
2
+ py3dscapture-capture-raw = py3dscapture.tools.capture_raw:main
3
+ py3dscapture-list-devices = py3dscapture.tools.list_devices:main
4
+ py3dscapture-raw-to-png = py3dscapture.tools.raw_to_png:main
5
+ py3dscapture-stream-n3dsxl = py3dscapture.tools.stream_n3dsxl:main
@@ -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,36 @@
1
+ """Python helpers for new 3DS XL capture board frame acquisition.
2
+
3
+ The package exposes the constants and size helpers needed to identify supported
4
+ N3DSXL capture boards and to reason about raw USB frame sizes. Higher-level
5
+ capture, decode, transport, and streaming APIs live in their dedicated
6
+ submodules.
7
+ """
8
+
9
+ from importlib.metadata import PackageNotFoundError, version
10
+
11
+ from py3dscapture.capture import CaptureConfig, CaptureOutput, CaptureReader, open_capture
12
+ from py3dscapture.protocol.sizes import (
13
+ ACCEPTED_N3DSXL_PRODUCT_IDS,
14
+ ACCEPTED_N3DSXL_PRODUCT_STRINGS,
15
+ N3DSXL_VENDOR_ID,
16
+ CaptureSizes,
17
+ capture_sizes,
18
+ )
19
+
20
+ try:
21
+ __version__ = version("ponkan-python")
22
+ except PackageNotFoundError:
23
+ __version__ = "0.0.0"
24
+
25
+ __all__ = [
26
+ "ACCEPTED_N3DSXL_PRODUCT_IDS",
27
+ "ACCEPTED_N3DSXL_PRODUCT_STRINGS",
28
+ "N3DSXL_VENDOR_ID",
29
+ "CaptureConfig",
30
+ "CaptureOutput",
31
+ "CaptureReader",
32
+ "CaptureSizes",
33
+ "__version__",
34
+ "capture_sizes",
35
+ "open_capture",
36
+ ]
@@ -0,0 +1,66 @@
1
+ """Artifact helpers for hardware-gated capture evidence."""
2
+
3
+ import json
4
+ from collections.abc import Mapping
5
+ from pathlib import Path
6
+
7
+
8
+ class ArtifactPathError(ValueError):
9
+ """Raised when an artifact run id escapes the N3DSXL artifact root.
10
+
11
+ This prevents absolute paths and parent-directory traversal from being used
12
+ as hardware evidence run IDs.
13
+ """
14
+
15
+ def __init__(self) -> None:
16
+ """Create an artifact path error with a stable user-facing message.
17
+
18
+ The message is intentionally short because path details can come from
19
+ user-controlled run IDs.
20
+ """
21
+ super().__init__("invalid artifact run_id")
22
+
23
+
24
+ def n3dsxl_artifact_dir(run_id: str, *, root: Path = Path("artifacts")) -> Path:
25
+ """Return the artifact directory for one N3DSXL run.
26
+
27
+ Args:
28
+ run_id: Relative run identifier used below ``root / "n3dsxl"``.
29
+ root: Artifact root directory.
30
+
31
+ Returns:
32
+ Path where N3DSXL evidence for the run should be written.
33
+
34
+ Raises:
35
+ ArtifactPathError: ``run_id`` is absolute or contains ``..``.
36
+ """
37
+ run_path = Path(run_id)
38
+ if run_path.is_absolute() or ".." in run_path.parts:
39
+ raise ArtifactPathError
40
+ return root / "n3dsxl" / run_path
41
+
42
+
43
+ def write_json_artifact(
44
+ path: Path,
45
+ data: Mapping[str, object],
46
+ *,
47
+ force: bool = False,
48
+ ) -> Path:
49
+ """Write a JSON artifact, refusing overwrite unless force is set.
50
+
51
+ Args:
52
+ path: Destination JSON artifact path.
53
+ data: JSON-serializable mapping to write.
54
+ force: Overwrite an existing file when true.
55
+
56
+ Returns:
57
+ The path written by this call.
58
+
59
+ Raises:
60
+ FileExistsError: The artifact already exists and ``force`` is false.
61
+ """
62
+ if path.exists() and not force:
63
+ raise FileExistsError(path)
64
+ path.parent.mkdir(parents=True, exist_ok=True)
65
+ path.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")
66
+ return path