kaleido_annotation 操作手順書

Flask 製の COCO 1.0 互換 矩形アノテーションツールです。CVAT バックアップとの相互運用、水増し画像の出力、EXIF 回転の自動修正に対応しています。

1. インストールと起動

必要環境

• Python 3.10 以上
• OpenCV が動作する OS（Ubuntu 22.04 / Windows 11 で確認）
• ONNX 自動アノテーションを使う場合は CPU で動作する onnxruntime（または GPU 版）

セットアップ

git clone https://github.com/takashide/kaleido_annotation.git
cd kaleido_annotation
python -m venv .venv

# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1

pip install -r requirements.txt

起動

# 同梱の起動スクリプト
./run_ubuntu.sh         # Linux/macOS
run_windows.bat         # Windows

# または直接
python app.py

ブラウザで http://127.0.0.1:5000 を開きます。

2. ログイン

環境変数 REQUIRE_LOGIN=1 でログインを要求できます。未設定なら匿名アクセスです。

3. プロジェクト管理

プロジェクトはデータ集合の単位です。クラス（カテゴリ）はプロジェクトごとに独立します。

新規プロジェクトの作成

1. トップ / または「プロジェクト一覧」を開く
2. + 新規作成 をクリック
3. プロジェクト名・説明を入力 → 作成

ZIP / バックアップから作成

同じ画面から、既存の COCO ZIP や CVAT タスクバックアップを取り込んで新規プロジェクトを起こせます。詳細は 第10章。

4. データ登録

4.1 画像のアップロード

1. プロジェクト画面の「画像アップロード」セクション
2. 複数ファイル選択可（.jpg .jpeg .png .bmp .webp）
3. 登録ボタン → サムネイル付きで一覧に表示

4.2 動画からフレーム抽出

1. 「動画 → フレーム分割」セクションに動画ファイルを選択
2. 抽出間隔（秒）を入力（例: 1.0 で1秒ごと）
3. 「キューに追加」→ バックグラウンドで JPEG 化されアノテーション対象になる

対応形式: .mp4 .mov .avi .mkv .webm

5. クラス管理

「クラス管理」セクションで追加・削除します。クラスは プロジェクトごとに独立。

追加

1. クラス名を入力
2. カラーピッカーで bbox 描画色を選択
3. 追加ボタン

削除

クラス右の ✕ をクリック。そのクラスのアノテーションが1件でも存在する場合は削除できません。先にアノテーションを別クラスに変えるか削除してください。

6. アノテーション作成

6.1 基本操作

1. サムネイル一覧から画像をクリック → アノテーション画面へ
2. 左のクラスパレットから描きたいクラスを選択
3. 画像上で左クリックドラッグ → 矩形を描画
4. マウスを離すと矩形確定 → サーバ保存

編集

6.2 ショートカット

6.3 ONNX 自動アノテーション

事前学習済み ONNX モデルを使って bbox 候補を自動生成できます。auto_annotate.py が YOLOv5/YOLOv8 系の典型的な出力をデコードします。

モデル登録

1. /models 画面で ONNX モデルファイル（.onnx）と クラス名（カンマ区切り）を登録
2. 登録モデルはプロジェクト共通で使える

1画像で実行

アノテーション画面の「ONNX自動」ボタン → モデル選択 → 信頼度しきい値を指定して実行。

全画像に一括実行

プロジェクト画面の「全画像に自動注釈」セクションで、モデルと信頼度を指定して開始。バックグラウンドジョブで進行します。

7. Train/Val 分割

各画像に train / val / test のラベルを付けて、エクスポート時に分割出力できます。

個別指定

アノテーション画面右の split セレクトボックスで切り替え。

一括指定

1. 「登録データ」セクションでサムネイル左上のチェックボックスを選択
2. 「全選択」も可
3. 「一括 split」セレクトで対象（train/val/test/未割当）を選び「適用」

8. EXIF 回転を修正（重要）

スマホやデジカメで縦撮影した画像は、ファイル実体は横向きのまま EXIF タグで「90度回転して表示せよ」と指示しているものがあります。古い経路で取り込んだデータがこの状態だと bbox が左下にズレて見える 問題が起きます。

仕組み

修正手順

1. プロジェクト画面の CVAT バックアップ欄にある EXIF回転を修正 ボタンを押す
2. 確認ダイアログで「OK」
3. 対象画像が pixel レベルで portrait に焼き込まれ、DB の width/height も更新
4. アノテーション画面で bbox が正しい位置に表示されるようになる

事前ブロック機能

EXIF 回転が残っている状態で COCO JSON / COCO ZIP / CVAT バックアップ のいずれかをエクスポートしようとすると、警告画面が表示されてブロックされます。画面の EXIF回転を修正する から1クリックで修正できます。

9. エクスポート

すべてプロジェクト画面の「エクスポート」セクションにあります。

9.1 COCO JSON / ZIP

ZIP の中身は以下の構造（YOLO / MMDetection 等の COCO ローダーが直接読める）：

coco_pN_xxx_YYYYMMDD_HHMMSS.zip
├── annotations/
│   └── instances_train.json   (または instances_val.json)
└── images/
    ├── img_001.jpg
    └── ...

9.2 水増し画像（オフライン augmentation）

ZIP エクスポートに対してのみ適用されます。チェックボックスで切り替え：

使い方:

1. 「エクスポート」セクション上の水増しチェックボックスを設定
2. 「train ZIP」等の ZIP ボタンを押す
3. output は coco_pN_train_aug_TS.zip として保存

val ZIP では水増しは 強制的に無効化 されます（val を膨らませると AP が不当に上がるため）。

出力量の目安（39枚に対して）

9.3 CVAT バックアップ

CVAT 公式の「Task Backup」ZIP 形式で出力します。CVAT に直接インポート可能。

cvat_backup_pN_YYYYMMDD_HHMMSS.zip
├── task.json          (ラベル定義 + フレーム範囲)
├── annotations.json   (shapes, xyxy points, frame=整数)
└── data/
    ├── original_filename_1.jpg
    └── ...

用途:

• CVAT に編集を戻したい
• 当ツール間のプロジェクト丸ごとコピー
• バックアップ保管

10. インポート / 復元

10.1 COCO ZIP インポート

既存プロジェクトに追記する場合: プロジェクト画面の「COCO ZIP インポート」セクション。新規プロジェクトとして取り込む場合: プロジェクト一覧画面の「ZIP からインポート」ボタン。

受け付け構造:

any_name.zip
├── annotations/
│   ├── instances_default.json  (または instances_train.json / instances_val.json)
└── images/
    └── *.jpg

• JSON のファイル名に train / val / test が含まれていれば自動で split が振られます
• カテゴリは名前で既存に自動マッチ、未登録なら自動追加
• 画像は EXIF 自動正規化

10.2 CVAT バックアップ復元

既存プロジェクトに復元: 「CVAT バックアップ」セクションの このプロジェクトに復元。新規プロジェクトとして作成: プロジェクト一覧の CVATバックアップから復元。

• frame 順は data/ 内のファイル名 lexicographical 順で解決（CVAT 既定挙動と一致）
• クラスは task.json の名前と色を採用、既存と同名なら統合
• xyxy → xywh 変換は自動
• 画像は EXIF 自動正規化

11. 削除

画像の削除

サムネイル右上の「✕」または、まとめて選択して「一括削除」。該当画像のアノテーションも DB から消えます。

動画の削除

動画リストから削除。元動画 + 抽出フレーム + 該当アノテーション をすべて物理削除。

プロジェクトの削除

プロジェクト一覧画面の 削除。復元不能。事前に CVAT バックアップを取得しておくと安全です。

12. 学習データとして使う

当ツールから出力した ZIP は YOLO / MMDetection / Detectron2 など標準的な COCO ローダーで読めます。MultimediaTechLab/YOLO（YOLOv9）への投入手順例:

データセット配置

dataset_root/
├── images/
│   ├── train/   ← train ZIP の images/ 中身
│   └── val/     ← val ZIP の images/ 中身
└── annotations/
    ├── instances_train.json
    └── instances_validation.json

dataset YAML

path: /path/to/dataset_root
train: train
validation: validation
class_num: 3
class_list: ["metron", "esp32", "insta360x5"]
auto_download:

train.yaml の落とし穴

13. トラブルシューティング

Q. アノテーションした bbox が左下にズレて表示される

A. EXIF 回転が残っています。第8章 の「EXIF回転を修正」ボタンを押してください。

Q. エクスポートを押したらオレンジの警告ページが出た

A. EXIF 不整合の事前ブロックです。ページ内のボタンから修正してそのまま再エクスポートしてください。

Q. ONNX 自動アノテーションでエラーが出る

A. ONNX_MODEL_PATH が未設定か、モデルの出力形状が auto_annotate.py の前提と異なります。コンソール出力を確認し、必要なら auto_annotate.py を調整してください。

Q. 学習させても AP/AR が 0 のまま

以下を順に確認:

1. val セットがあるか（5枚以上推奨）
2. class_num と DB のクラス数が一致
3. EXIF 回転を修正済みか
4. pretrained weight 指定済みか
5. equivalent_batch_size が画像数に対して妥当か（少データなら batch_size と同値推奨）
6. warmup epoch 比率が高すぎないか

Q. 動画フレーム抽出が終わらない

A. バックグラウンドジョブで進行します。「動画」セクションに進捗が表示されます。長尺動画は時間がかかります。

Q. CVAT バックアップを CVAT に取り込むと向きが違う

A. 当ツールが EXIF 焼き込みを終えた画像は EXIF タグなしです。CVAT 側で正しく portrait/landscape として扱われるはず。もしずれている場合は、当ツールでアノテーション後に CVAT に渡したものではなく、別経路（手元のスマホ画像を CVAT に直接アップ等）でズレが起きている可能性があります。

© kaleido_annotation. ドキュメントの修正提案は Issues へお願いします。