vrc-autopilot 1.0.0__tar.gz

vrc_autopilot-1.0.0/.gitattributes

@@ -0,0 +1,19 @@
+# Normalize all text files to LF line endings on checkin/checkout,
+# regardless of the OS or editor used to create/edit them.
+* text=auto eol=lf
+
+# Explicit text types
+*.py     text eol=lf
+*.md     text eol=lf
+*.toml   text eol=lf
+*.json   text eol=lf
+*.csv    text eol=lf
+*.shader text eol=lf
+*.lock   text eol=lf
+*.gitignore text eol=lf
+*.gitattributes text eol=lf
+
+# Binary types — do not touch line endings
+*.png  binary
+*.npz  binary
+*.pyc  binary

vrc_autopilot-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Publish
+
+# Tag push (v*) -> build and publish to PyPI via Trusted Publishing (OIDC, no API token).
+# Manual run (workflow_dispatch) -> publish to TestPyPI for a dry run.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, so full history is required.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Show built version
+        run: ls -l dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/vrc-autopilot/
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/vrc-autopilot/
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

vrc_autopilot-1.0.0/.gitignore

@@ -0,0 +1,226 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+maps/
+logs/
+
+# hatch-vcs generated version file
+src/vrc_autopilot/_version.py

vrc_autopilot-1.0.0/.python-version

@@ -0,0 +1 @@
+3.14

vrc_autopilot-1.0.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, njm2360
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vrc_autopilot-1.0.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: vrc-autopilot
+Version: 1.0.0
+Summary: VRChat AutoPilot
+Project-URL: Homepage, https://github.com/njm2360/vrc-autopilot
+Project-URL: Repository, https://github.com/njm2360/vrc-autopilot
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: matplotlib>=3.11
+Requires-Dist: mss>=10.2
+Requires-Dist: numpy>=2.5
+Requires-Dist: pydirectinput>=1.0.4
+Requires-Dist: python-osc>=1.10
+Requires-Dist: scipy>=1.18
+Description-Content-Type: text/markdown
+
+# vrc-autopilot
+
+[VRCPositionHUD](https://github.com/njm2360/vrc-position-hud)を利用してOSCで移動・視点を操作する自動化ツール
+
+> [!WARNING]
+> 本ツールの使用によって生じたいかなる結果についても、作者は一切の責任を負いません。自己責任で使用してください。
+> 使用にあたっては各ワールド・コミュニティのルールに従ってください。自動化を歓迎しない場所では使わないこと。
+
+- 全体像とモジュール対応: [docs/architecture.md](docs/architecture.md)
+- プラント特性の測定手順: [docs/system-identification.md](docs/system-identification.md)
+- 制御ゲインの根拠と調整手順: [docs/gain-tuning.md](docs/gain-tuning.md)
+- オフライン検証の組み方: [docs/verification.md](docs/verification.md)
+- 各コマンドの使用方法: [docs/usage.md](docs/usage.md)
+
+## 動作環境
+
+- Python 3.14
+- [uv](https://docs.astral.sh/uv/)
+
+## サンプルコード
+
+移動・照準・押下は `Pilot` API で記述する。マップ・プラント・ボタン座標を渡して巡回ルートを組む。
+
+- [でかプ 軽量化スイッチ自動化](examples/dekapu/main.py)
+    ※マップデータ同梱
+
+## CLI
+
+`uv run <コマンド>` で実行する。フラグ詳細は各 `--help` で確認可能
+
+| コマンド          | 用途                                                                         |
+| ----------------- | ---------------------------------------------------------------------------- |
+| `decode-demo`     | HUD を読み取り 6DoF を表示(動作確認とキャリブレーション)                     |
+| `map-room`        | 壁沿いに歩いて部屋マップを記録                                               |
+| `find-button`     | 複数地点からボタンを三角測量                                                 |
+| `probe-axes`      | 入力軸の応答特性を測って `plant.json` に同定(制御ゲインの前提)               |
+| `calibrate-world` | ワールドごとに変わる移動速度を測り、ゲインの倍率を補正                       |
+| `bode-margins`    | 同定プラント上で全制御ループの安定余裕(ωc/PM/GM)とボード線図を出す(実機不要) |
+| `log-video`       | 制御ログCSVを一人称3D+2D地図の動画(mp4)に再生                                |

vrc_autopilot-1.0.0/README.md

@@ -0,0 +1,39 @@
+# vrc-autopilot
+
+[VRCPositionHUD](https://github.com/njm2360/vrc-position-hud)を利用してOSCで移動・視点を操作する自動化ツール
+
+> [!WARNING]
+> 本ツールの使用によって生じたいかなる結果についても、作者は一切の責任を負いません。自己責任で使用してください。
+> 使用にあたっては各ワールド・コミュニティのルールに従ってください。自動化を歓迎しない場所では使わないこと。
+
+- 全体像とモジュール対応: [docs/architecture.md](docs/architecture.md)
+- プラント特性の測定手順: [docs/system-identification.md](docs/system-identification.md)
+- 制御ゲインの根拠と調整手順: [docs/gain-tuning.md](docs/gain-tuning.md)
+- オフライン検証の組み方: [docs/verification.md](docs/verification.md)
+- 各コマンドの使用方法: [docs/usage.md](docs/usage.md)
+
+## 動作環境
+
+- Python 3.14
+- [uv](https://docs.astral.sh/uv/)
+
+## サンプルコード
+
+移動・照準・押下は `Pilot` API で記述する。マップ・プラント・ボタン座標を渡して巡回ルートを組む。
+
+- [でかプ 軽量化スイッチ自動化](examples/dekapu/main.py)
+    ※マップデータ同梱
+
+## CLI
+
+`uv run <コマンド>` で実行する。フラグ詳細は各 `--help` で確認可能
+
+| コマンド          | 用途                                                                         |
+| ----------------- | ---------------------------------------------------------------------------- |
+| `decode-demo`     | HUD を読み取り 6DoF を表示(動作確認とキャリブレーション)                     |
+| `map-room`        | 壁沿いに歩いて部屋マップを記録                                               |
+| `find-button`     | 複数地点からボタンを三角測量                                                 |
+| `probe-axes`      | 入力軸の応答特性を測って `plant.json` に同定(制御ゲインの前提)               |
+| `calibrate-world` | ワールドごとに変わる移動速度を測り、ゲインの倍率を補正                       |
+| `bode-margins`    | 同定プラント上で全制御ループの安定余裕(ωc/PM/GM)とボード線図を出す(実機不要) |
+| `log-video`       | 制御ログCSVを一人称3D+2D地図の動画(mp4)に再生                                |

vrc_autopilot-1.0.0/docs/architecture.md

@@ -0,0 +1,93 @@
+# アーキテクチャ概要
+
+## パイプライン
+
+```txt
+VRChat 画面(HUDビットグリッド)
+    │  スクリーンキャプチャ(ネイティブ解像度・クライアント左上の小領域)
+    ▼
+[capture]  WindowsVRChatCapture ──► フレーム(numpy)
+    │
+    ▼
+[decode]   decode_frame ──► DecodeResult(Pose + 検証結果)
+    │
+    ▼
+[reader]   PoseReader(スレッドで読み続ける・統計・コールバック/ジェネレータ)
+    │
+    ├─► [mapping]     RoomMapper ──► 部屋の地図(占有グリッド/間取り図)
+    ├─► [triangulate] Sighting/triangulate ──► ボタンのワールド座標(最小二乗交点)
+    └─► [navigation]  NavGrid + plan_path ──► 壁を避けた経路
+                          │
+                          ▼
+                     [pilot / maneuvers] goto / aim / activate(フェーズ連結と制御ループ)
+                          │  [guidance] で誤差を計算し、[controller] AxisController(PID) が指令[-1,1] に変換
+                          ▼
+                     [actuator]  LookActuator / MoveActuator
+                          ├─ OSC:         VRChatOSC ──► /input/* を注入
+                          └─ DirectInput: MouseLookActuator ──► 相対マウス(視点のみ)
+```
+
+## モジュール(`src/vrc_autopilot/`)
+
+### `core/` — 全層が参照する中核型
+
+| モジュール     | 役割                    |
+| -------------- | ----------------------- |
+| `core/pose.py` | `Pose`(6DoF ドメイン型) |
+
+### `perception/` — VRChat 画面 → Pose
+
+| モジュール              | 役割                                                            |
+| ----------------------- | --------------------------------------------------------------- |
+| `perception/spec.py`    | グリッド/プロトコルの確定定数(モジュール定数。シェーダーと一致) |
+| `perception/capture.py` | Windows/VRChat ウィンドウキャプチャ(DPI対応、`FrameSource`)     |
+| `perception/decode.py`  | numpy ベクトル化デコード + 検証(`decode_frame` / `decode_pose`) |
+| `perception/encode.py`  | 合成エンコーダ(`render_pose`)。テスト用                         |
+| `perception/reader.py`  | `PoseReader`(スレッドで読み続ける・統計・ジェネレータ)          |
+
+### `mapping/` — 部屋地図
+
+| モジュール          | 役割                                                                   |
+| ------------------- | ---------------------------------------------------------------------- |
+| `mapping/mapper.py` | `RoomMapper`。軌跡→寸法・占有グリッド・外周/内壁ポリゴン・保存/読込    |
+| `mapping/draw.py`   | 地図の描画・PNG 保存(バックエンド非依存の `draw_map` / `save_map_png`) |
+| `mapping/live.py`   | 録画中のライブ地図表示(matplotlib インタラクティブ)                    |
+
+### `spatial/` — 空間推定・経路計画
+
+| モジュール               | 役割                                               |
+| ------------------------ | -------------------------------------------------- |
+| `spatial/triangulate.py` | 視線レイの最小二乗交点でボタン座標を推定           |
+| `spatial/navigation.py`  | 歩行可能グリッド生成(壁回避)+ A\* + 経由点の直線化 |
+
+### `control/` — 閉ループ制御 + VRChat 出力
+
+| モジュール                 | 役割                                                                                   |
+| -------------------------- | -------------------------------------------------------------------------------------- |
+| `control/guidance.py`      | フレーム単位の照準幾何(`wrap180` / `heading_error` / `pitch_error` / `forward_factor`) |
+| `control/pid.py`           | 汎用 PID(離散・積分の溜まりすぎ防止・不感帯補償)                                       |
+| `control/controller.py`    | `AxisController`(PID+tolゲート)/ `ControlTuning` / 制御器ビルダー                      |
+| `control/loop_analysis.py` | ループ整形解析(安定余裕・ボード線図。`analyze_loops` / `save_bode_png`)                |
+| `control/actuator.py`      | `LookActuator`/`MoveActuator` IF + `MouseLookActuator`(DirectInput)                    |
+| `control/osc.py`           | VRChat への OSC 送信(look/move/stop で両 actuator IF を満たす)                         |
+| `control/recording.py`     | `Recorder` IF(`ControlLog`=CSV / `ListRecorder`)+ `AxisMetrics`(応答指標)              |
+| `control/maneuvers.py`     | 制御ループの部品(`follow_path`(carrot追従)/ `aim_at` / `strafe_align` / `turn_to`)     |
+| `control/pilot.py`         | `Pilot` ファサード(経路計画+ループ連結。実機 I/O は `connect()` に集約)                |
+
+### `sysid/` — システム同定・シミュレーション
+
+| モジュール           | 役割                                                                                   |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `sysid/identify.py`  | システム同定(プローブ注入・静特性/むだ時間/dt 抽出・`PlantModel` JSON)                 |
+| `sysid/sim_plant.py` | `SimulatedVRChat`(同定モデルを積分。PoseSource+両 Actuator を満たし制御ループに注入可) |
+
+## CLI
+
+| コマンド       | スクリプト            | 用途                                                              |
+| -------------- | --------------------- | ----------------------------------------------------------------- |
+| `decode-demo`  | `cli/decode_demo.py`  | HUD を読み取り 6DoF を表示(動作確認)                              |
+| `map-room`     | `cli/map_room.py`     | 壁沿いに歩いて部屋マップを記録(SPACE一時停止・日時フォルダ出力)   |
+| `find-button`  | `cli/find_button.py`  | 複数地点からボタンを三角測量(SPACE/r/q)                           |
+| `probe-axes`   | `cli/probe_axes.py`   | 入力軸の応答特性を測定し `plant.json` に同定(--from-log で再同定) |
+| `bode-margins` | `cli/bode_margins.py` | 同定プラント上で全ループの安定余裕とボード線図を出す(実機不要)    |
+| `log-video`    | `cli/log_video.py`    | 制御ログCSVを一人称3D+2D地図の動画に再生(目視確認用)              |