🐟 Marine Copy-Paste Augmentation

背景画像上にカゴと魚を2段階で合成し、物体検出・セグメンテーション用の学習データセットを自動生成するツールです。

概要

漁獲現場の画像データを増幅するため、魚画像をカゴテンプレートに配置し、さらにそのカゴを背景画像上にランダム配置する Copy-Paste Augmentation を実装しています。

魚画像 ──→ カゴに配置（Stage 1） ──→ カゴを背景に配置（Stage 2） ──→ 合成画像 + COCOアノテーション

処理フロー

flowchart LR
    A["🐟 魚画像<br>(種ごとのフォルダ)"] --> B["🧺 Stage 1<br>カゴに魚を配置"]
    C["🧺 カゴテンプレート"] --> B
    B --> D["📦 Stage 2<br>カゴを背景に配置"]
    E["🖼️ 背景画像"] --> D
    D --> F["✅ 合成画像<br>+ COCO JSON"]

Loading

出力例

合成画像にはBBox（赤枠）とセグメンテーションマスク（赤色領域）が自動付与されます。

セットアップ

一発構築

git clone https://github.com/ohnuma0529/20260218_MarineCopyAug.git
cd 20260218_MarineCopyAug
bash setup.sh
source .venv/bin/activate

setup.sh は以下を自動実行します:

1. Python仮想環境（.venv）の作成
2. pipのアップグレード
3. PyTorchのインストール（CUDA自動判定、なければCPU版）
4. requirements.txt の依存パッケージインストール

手動セットアップ

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

# GPU環境の場合（CUDA 12.1）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# CPU環境の場合
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

pip install -r requirements.txt

データの準備

以下の3種類のデータを用意してください:

データ	説明	config キー
背景画像	魚のない背景画像群（.jpg / .png）	paths.backgrounds_dir
カゴテンプレート	透過PNG形式のカゴ画像	paths.basket_template
魚画像	種ごとのサブフォルダに格納された透過PNG	paths.fish_images_dir

魚画像のディレクトリ構造

fish_images/
├── akamutsu/    # アカムツ
│   ├── 001.png
│   └── 002.png
├── buri/        # ブリ
│   ├── 001.png
│   └── ...
├── madai/       # マダイ
│   └── ...
└── ...          # 他の種

Note: 魚画像は透過PNG（アルファチャンネル付き）が推奨です。アルファチャンネルからセグメンテーションマスクを自動生成します。

使い方

基本実行

python generate.py --config config.yaml

CLIオプション

引数	説明	デフォルト
--config	設定ファイルパス	config.yaml
--images	生成枚数（configをオーバーライド）	config値
--seed	乱数シード（configをオーバーライド）	config値
--output-dir	出力先ディレクトリ（configをオーバーライド）	config値

実行例

# テスト生成（10枚）
python generate.py --config config.yaml --images 10 --output-dir test_output

# 本番生成（200枚、config.yaml のデフォルト設定）
python generate.py --config config.yaml

# 500枚生成、シード変更
python generate.py --config config.yaml --images 500 --seed 42

設定ファイル (config.yaml)

# --- 入出力パス ---
paths:
  backgrounds_dir: "back"                    # 背景画像ディレクトリ
  basket_template: "double_sync/basket.png"  # カゴテンプレート画像
  fish_images_dir: "onlyfish_crops"          # 魚画像ディレクトリ
  output_dir: "output"                       # 出力先

# --- 生成全般 ---
generation:
  num_images: 200    # 生成枚数
  seed: 0            # 乱数シード

# --- カゴ配置 ---
basket:
  min_count: 1       # 1画像あたりの最小カゴ数
  max_count: 5       # 1画像あたりの最大カゴ数
  scale_min: 1.0     # スケール下限
  scale_max: 2.0     # スケール上限
  max_overlap_iou: 0.05  # カゴ間の最大IoU

# --- 魚配置 ---
fish:
  min_per_basket: 5        # カゴあたりの最小魚数
  max_per_basket: 10       # カゴあたりの最大魚数
  max_overlap_iou: 0.3     # 魚間の最大IoU
  min_center_dist_factor: 0.12  # 中心距離最小係数
  rotation_range: [-30, 30]     # 回転角度範囲（度）

パラメータ詳細

カゴ配置パラメータ

• min_count / max_count: 1画像に配置するカゴの数の範囲。この範囲内でランダムに決定されます。
• scale_min / scale_max: カゴのスケール倍率。さらに0〜360度のランダム回転が適用されます。
• max_overlap_iou: カゴ同士のバウンディングボックスIoU上限。これを超える配置は却下されます。

魚配置パラメータ

• min_per_basket / max_per_basket: 各カゴに配置する魚の数の範囲。
• max_overlap_iou: 魚同士のピクセルレベルIoU上限。
• min_center_dist_factor: 魚の中心間の最小距離（カゴ短辺に対する割合）。密集防止に使用。
• rotation_range: 魚画像の回転角度範囲（度）。スケールはカゴサイズに合わせ自動調整。

出力

output/
├── images/                  # 合成画像（PNG）
├── masks/                   # インスタンスごとのバイナリマスク（PNG）
├── visuals/                 # BBox + セグメンテーション可視化画像
└── annotations_coco.json    # COCO形式アノテーション

COCOアノテーション形式

{
  "images": [
    {"id": 1, "file_name": "synthetic_000000.png", "width": 3840, "height": 2160}
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "segmentation": [[x1, y1, x2, y2, ...]],
      "area": 23103,
      "bbox": [x, y, width, height],
      "iscrowd": 0
    }
  ],
  "categories": [
    {"id": 1, "name": "akamutsu"},
    {"id": 2, "name": "buri"}
  ]
}

プロジェクト構成

├── generate.py              # エントリポイント（CLIから実行）
├── config.yaml              # 合成パラメータ設定
├── setup.sh                 # 環境構築スクリプト
├── requirements.txt         # Python依存パッケージ
├── .gitignore
├── README.md
└── copy_augment/            # メインパッケージ
    ├── __init__.py
    ├── config.py              # 設定読み込み・バリデーション
    ├── fish_placer.py         # Stage 1: カゴ内に魚を配置
    ├── basket_composer.py     # Stage 2: カゴを背景に配置
    ├── image_transform.py     # ランダム変換（スケール・回転）
    ├── mask_utils.py          # マスク・IoU計算ユーティリティ
    ├── annotation_writer.py   # COCOアノテーション出力
    └── visualizer.py          # 可視化描画

モジュール説明

モジュール	主な責務
config.py	YAML設定ファイルの読み込み、dataclassへのマッピング、バリデーション
fish_placer.py	カゴテンプレート上への魚画像の配置。IoU・中心距離ベースの重なり制御
basket_composer.py	魚入りカゴを背景画像上にランダムスケール・回転で配置
image_transform.py	魚画像のカゴサイズに応じたスケーリングとランダム回転
mask_utils.py	アルファチャンネルからのマスク生成、IoU計算、ポリゴン変換、RGBA合成
annotation_writer.py	COCOフォーマットのJSON構築・書き出し
visualizer.py	BBoxとセグメンテーションマスクのオーバーレイ描画

動作環境

• Python 3.8+
• PyTorch（CUDA対応推奨、CPU版でも動作可）
• OpenCV, Pillow, NumPy, PyYAML