🔄 created local 'docs/ai' from remote 'docs'

docs/ai/ball_possession.md

@@ -0,0 +1,82 @@
+# ボールの所持判定アルゴリズム
+
+<https://github.com/ibis-ssl/crane/pull/303>
+
+## 1. イベント検出
+
+ボールへの外力発生イベントを検出する。  
+イベントは以下の評価値が閾値を超えたときに発生するものとする。  
+
+```text
+評価値 = abs((前フレームの速度ベクトル) - (現在フレームの速度ベクトル)) / (前フレームの速度) + 0.1)
+```
+
+これによって、ボールの速度ベクトルに変化があった場合にイベントが発生する。  
+前フレームの速度で割っているのは、ボールの速度が速い場合には些細な地面の凹凸でボールの動きが変わりやすかったり、単純にVisionのブレが大きいのを吸収することを防ぐ正規化である。  
+また、分母に0.1を足しているのは、ボール速度が0に近づくにつれて評価値が不当に大きくなるのを防ぐためである。
+
+この評価値を用いて、ロボットによるボールへのキックや衝突、またボールの壁への衝突などのイベントを検出する。
+
+## 2. ボール所持判定
+
+ボールの状態を以下の3つに分類する。
+
+- 敵所持
+- 味方所持
+- どちらでもない
+
+この状態を計算するためにまず、「敵所持フラグ」「味方所持フラグ」の2つのフラグを計算する
+
+### 2.1. 敵所持フラグ
+
+以下の条件を満たすとき、「敵所持フラグ」は真となる。
+
+1. ボールへの外力発生イベントが発生した
+2. ボールに一番近い敵ロボットの距離がボールに十分近い（プルリクエストでは0.3mがしきい値）
+3. ボールがキッカーに接触した（判定方法は2.1.1参照）
+
+3は単にロボットがボールにぶつかっただけで所有権が移るのを防ぐための条件である。
+
+#### 2.1.1. キッカーへの接触判定
+
+ロボット中心から見たボールの方向と、ロボットのキッカーの方向の差が一定角度以下のとき、ボールはキッカーに接触したと判定する。  
+プルリクエストでは0.4rad、つまりキッカーの左右に23度ずつの範囲を接触範囲としている。  
+
+### 2.2. 味方所持フラグ
+
+「味方所持フラグ」は真となる条件は2通りある。
+
+#### 2.2.1. 条件1
+
+敵所持フラグと同様の条件を味方ロボットが満たしたとき、「味方所持フラグ」は真となる。
+
+#### 2.2.2. 条件2
+
+以下の条件を満たすとき、「味方所持フラグ」は真となる。
+
+- ロボットのボールセンサが反応した
+
+### 2.3. フラグとボール状態の遷移
+
+遷移テーブルで「-」は遷移無しを表す。
+
+#### 2.3.1. 現在状態が「どちらでもない」のときの遷移テーブル
+
+|            | 敵所持フラグ（真） | 敵所持フラグ（偽） |
+|------------|-----------|-----------|
+| 味方所持フラグ（真） | -         | 味方所持      |
+| 味方所持フラグ（偽） | 敵所持       | -         |
+
+#### 2.3.2. 現在状態が「敵所持」のとき
+
+|            | 敵所持フラグ（真） | 敵所持フラグ（偽） |
+|------------|-----------|-----------|
+| 味方所持フラグ（真） | どちらでもない   | 味方所持      |
+| 味方所持フラグ（偽） | -         | どちらでもない   |
+
+#### 2.3.3. 現在状態が「味方所持」のとき
+
+|            | 敵所持フラグ（真） | 敵所持フラグ（偽） |
+|------------|-----------|-----------|
+| 味方所持フラグ（真） | どちらでもない   | -         |
+| 味方所持フラグ（偽） | 敵所持       | どちらでもない   |

docs/ai/coordinates.md

@@ -0,0 +1,10 @@
+# 座標系に関して
+
+## フィールド座標系
+
+Visionから来る座標系
+長辺方向X，短辺方向Y
+
+## ロボット座標系
+
+前X，左Y，上Z

docs/ai/diagram.md

@@ -0,0 +1,86 @@
+# ノードダイアグラム
+
+```mermaid
+graph TD
+    LP[Local Planner]
+    PS[Play Switcher]
+    GA[Game Analyzer]
+
+    subgraph interface
+        VC[Vision Component]
+        GrC[GrSim Component]
+        GCC[Game Controller Component]
+        Receiver[Robot Receiver]
+    end
+
+    SC[Session Controller]
+    SS[Sim Sender]
+
+    VT[Vision Tracker]
+    WP[World Model Publisher]
+
+    subgraph software
+        GrSim[GrSim]
+        GC[Game Controller]
+    end
+
+    WP -- /world_model -->  SC
+    WP -- /world_model -->  GA
+    GA -- /game_analysis -->  SC
+
+
+    GrC -. UDP .->  GrSim
+
+    GrSim -. UDP .->  GrC
+    GrC -- /geometry -->  WP
+
+    GrSim -. UDP .->  VC
+
+
+    VC -- /detection -->  VT
+    VT -- /detection_tracked -->  WP
+
+    GC -. UDP .->  GCC
+    GCC -- /referee -->  PS
+    PS -- /play_situation --> SC
+    SC -- /control_targets --> LP
+    LP -- /robot_commands -->  SS
+    SS -- /commands -->  GrC
+
+    Receiver -- /feedback -->  WP
+```
+
+## テスト用のノードダイアグラム
+
+```mermaid
+graph TD
+    subgraph interface
+        VisionNode[Vision Component]
+        Sender[Real Sender]
+        Receiver[Robot Receiver]
+    end
+
+    VT[Vision Tracker]
+    WP[World Model Publisher]
+    Main[Simple AI]
+    LP[Local Planner]
+
+    subgraph RealWorld
+        Robot[Actual Robot CM4]
+        SSLVision[SSL Vision]
+    end
+
+    SSLVision -. UDP .->  VisionNode
+    VisionNode -- /detection -->  VT
+    VT -- /detection_tracked -->  WP
+    VisionNode -- /geometry -->  WP
+
+    WP -- /world_model -->  Main
+    Main -- /control_targets --> LP
+    LP -- /robot_commands -->  Sender
+
+    Sender -. UDP .->  Robot
+
+    Robot -. UDP .->  Receiver
+    Receiver -- /feedback -->  WP
+```

docs/ai/docker.md

@@ -0,0 +1,34 @@
+# docker立ち上げ
+
+## 準備
+
+docker compose v2のインストール
+
+```bash
+sudo mkdir -p /usr/local/lib/docker/cli-plugins
+sudo curl -SL https://github.com/docker/compose/releases/download/v2.5.0/docker-compose-linux-x86_64 -o /usr/local/lib/docker/cli-plugins/docker-compose
+sudo chmod a+x /usr/local/lib/docker/cli-plugins/docker-compose
+```
+
+※docker-compose v1系はv1.2.5以降だとエラーが出て起動できないはず
+
+## 起動
+
+### ツール群
+
+```bash
+cd path/to/crane/docker
+docker compose up
+```
+
+### grSim
+
+起動
+
+## 閲覧
+
+- [game-controller](http://localhost:8081)
+- [vision client](http://localhost:8082)
+- [status board](http://localhost:8083)
+- [YELLOW remote control](http://localhost:8084)
+- [BLUE remote control](http://localhost:8085)

docs/ai/grSim.md

@@ -0,0 +1,9 @@
+# grSim
+
+<https://github.com/ibis-ssl/grSim>
+
+オリジナルから以下の変更を加えた
+
+- ドリブルするときにボールに一定の力がかかるとボールを離すようにした
+- ペナルティエリアの大きさに関するフィールド（オプショナル）を出力するようにした
+  - これは公式Visionでは出力されるが，grSimでは出力されていなかった

docs/ai/index.md

@@ -0,0 +1,3 @@
+# crane Documentation
+
+AI components for RoboCup Small Size League.

docs/ai/logs/2023-04-16.md

@@ -0,0 +1,42 @@
+# 2023-04-16
+
+## 色と位置について
+
+色と位置の関係についてはルールには明記されていない．  
+しかし，grSimでは，xがマイナスの方が青，プラスの方が黄色となっている．
+
+### 欲しい物とやるべきこと
+
+「味方の〇〇 => 座標」を解決したい
+
+ある情報は以下の通り
+
+- 味方チームの色情報
+- 各色チームのランドマーク位置情報
+
+やるべきこと：`WorldModel`クラスで解決済みの情報を提供するAPIを追加する
+
+## Defense Area
+
+キーパーしか入ってはいけないあのエリア，GoalAreaと表記してしまっていた部分があったが実はDefenseAreaであった．
+
+<https://robocup-ssl.github.io/ssl-rules/sslrules.html#_defense_area>
+
+修正した
+
+## 更新周期について
+
+前回調べたら，メインループが300Hzもの超高速で回っていることが判明したので修正していく
+原因はおそらく，WorldModelの更新がVisionの一部でも更新されたらPublishされており，
+それをトリガーにしてメインループが全て駆動していることが原因だと思われる
+
+⇒ WorldModelの更新周期を60Hzに固定しよう！
+
+⇒　そもそもWorldModelの更新周期は100Hzだった　まぁ早すぎるので60Hzにした
+
+local_plannerは`/control_targets`駆動.  
+それを出しているプランナー群は`world_model`駆動...
+
+あれ，world_model駆動だおかしいな...
+
+もしかして，前回測定時には`world_model_publisher`が3つ同時起動していた可能性がある？！？！

docs/ai/logs/2023-05-03.md

@@ -0,0 +1,101 @@
+# 2023-05-03
+
+## インプレイ判定のチェック(ルール5.4)
+
+- 以下のコマンド送信後にボールが少なくとも0.05m動く
+  - キックオフ
+  - フリーキック
+  - ペナルティーキック
+- キックオフから10秒経過
+- FORCE_STARTコマンド送信後
+
+## 開発環境整備
+
+- pre-commit導入
+- include文の呼び分け
+- boostの警告文抑制
+
+## GUIへの現状の表示
+
+- `play_switcher.launch`へのGUI追加
+
+## 動作がおかしい？
+
+ログ
+
+```text
+[crane_play_switcher]: last 4, THEIR_KICKOFF_PREPARATION : 2.025060
+[crane_play_switcher]: last 4, THEIR_KICKOFF_PREPARATION : 2.049855
+[crane_play_switcher]: コマンド変化！
+[crane_play_switcher]: THEIR_KICKOFF_START
+[crane_play_switcher]: inplay cmd : 22
+[crane_play_switcher]: CMD : 2
+[crane_play_switcher]: last 2, THEIR_KICKOFF_START : 0.000022
+[crane_play_switcher]: コマンド変化！
+[crane_play_switcher]:
+[crane_play_switcher]: inplay cmd : 0
+[crane_play_switcher]: CMD : 2
+[crane_play_switcher]: last 2,  : 0.000019
+[crane_play_switcher]: last 2,  : 0.024619
+```
+
+`COMMAND_PREPARE_KICKOFF_YELLOW`が来て2秒後に `NORMAL_START`が来ている  
+その後，
+
+参考情報
+
+- COMMAND_NORMAL_START = 2
+- COMMAND_PREPARE_KICKOFF_YELLOW = 4
+- inplay/halt = 0
+- inplay/their_kickoff_start = 22
+
+RAWコマンドの移り変わりとその解釈
+
+1. 2：NORMAL_START，前回のコマンドが残っている？
+2. 0：HALT，試合開始
+3. 1：STOP，RESUMEを押した
+4. 4：PREPARE_KICKOFF_YELLOW，KICKOFFした
+5. 2：NORMAL_START, 2秒経って勝手に始まる
+6. 2：NORMAL_START, 10秒たってINPLAYに入った
+
+## 結局直った気がする
+
+⇒色々あって結局デバッグしやすいLOGを整えたら直った気がする
+こんな感じ
+
+```text
+[crane_play_switcher]: ---
+[crane_play_switcher]: RAW_CMD      : COMMAND_STOP
+[crane_play_switcher]: INPLAY_CMD   : STOP
+[crane_play_switcher]: REASON       : RAWコマンド変化：コマンド転送
+[crane_play_switcher]: PREV_CMD_TIME: 12.505770
+[crane_play_switcher]: ---
+[crane_play_switcher]: RAW_CMD      : COMMAND_PREPARE_KICKOFF_YELLOW
+[crane_play_switcher]: INPLAY_CMD   : THEIR_KICKOFF_PREPARATION
+[crane_play_switcher]: REASON       : RAWコマンド変化：コマンド転送
+[crane_play_switcher]: PREV_CMD_TIME: 15.174960
+[crane_play_switcher]: ---
+[crane_play_switcher]: RAW_CMD      : COMMAND_NORMAL_START
+[crane_play_switcher]: INPLAY_CMD   :
+[crane_play_switcher]: REASON       : RAWコマンド変化＆NORMAL_START：KICKOFF/PENALTYはPREPARATIONからSTARTに移行
+[crane_play_switcher]: PREV_CMD_TIME: 19.425025
+[crane_play_switcher]: ---
+[crane_play_switcher]: RAW_CMD      : COMMAND_NORMAL_START
+[crane_play_switcher]: INPLAY_CMD   : INPLAY
+[crane_play_switcher]: REASON       : INPLAY判定：キックオフから10秒経過
+[crane_play_switcher]: PREV_CMD_TIME: 10.024822
+```
+
+## コマンド更新通知
+
+`PlaySituation.msg`に`command_updated`を追加した．
+
+INPLAYのコマンド更新時に`command_updated`を`true`にする処理を実装した
+
+## 次回
+
+PlaySituationを受け取って行う処理の実装
+
+- `session_controller`の実装
+  - 主に，コマンドを受け取ってセッションを組む部分の実装（ここも泥臭そう...）
+- `session_controller`で使う上で足りないプランナのリストアップ