単一画像からアニメキャラクターをリアルタイムでアニメーション化するWebアプリケーション
このシステムは、Talking Head(?) Anime from a Single Image 3: Now the Body Too プロジェクトをベースとした、Linuxサーバー環境で動作する高度なアニメーション生成システムです。
📘 THA3オリジナルドキュメント: THA3_ORIGINAL_README.md をご覧ください
- 🎥 仮想カメラサポート: Google Meet等のビデオ会議で使用可能
- YUYVフォーマット対応（ブラウザ互換性向上）
- v4l2loopback統合
- FFmpegパイプライン最適化
- 📊 FPS表示機能: リアルタイムフレームレート監視
- 🎨 動的背景色: 画像読み込み時の自動背景色変更
- 📐 画像アスペクト比保持: 正方形パディング処理
- 📱 OpenCVリアルタイム表示: チェックボックスで切り替え可能な即座プレビュー
- 表情制御: 眉毛、目、口の詳細な表情操作（45パラメータ）
- 頭部・身体回転: 3D空間での自然な動き
- 呼吸アニメーション: 胸部の拡張・収縮
- リアルタイム処理: Webカメラからの顔認識連動
- AI画像アップスケール: Real-ESRGANによる高解像度化
- 背景除去: ISNetモデルによる自動背景削除
- OS: Linux (Ubuntu 20.04以降推奨)
- Python: 3.8以上
- GPU: CUDA対応GPU（NVIDIA GTX 1060以上推奨）
- メモリ: 8GB以上（16GB推奨）
- ストレージ: 約2GB（モデルファイル含む）
詳細は INSTALLATION_GUIDE.md をご覧ください
# リポジトリをクローン
git clone https://github.com/animede/tkh_avatar.git
cd tkh_avatar
# 仮想環境を作成（推奨）
python3 -m venv ~/tkh
source ~/tkh/bin/activate
# 依存パッケージをインストール
pip install -r requirements.txt
# THA3モデルファイルをダウンロード（必須）
# data/models/README.md の手順に従ってくださいTHA3の学習済みモデル（約800MB）が必要です:
cd data/models
# 以下のファイルをダウンロードして解凍
# - separable_float.zip
# - separable_half.zip
# - standard_float.zip
# - standard_half.zip
# 詳細: data/models/README.mdrealESRGAN,Animesegmentation,AnimeFaceDitectionのモデル
HuggingFace https://huggingface.co/UZUKI/Scalable-tkh からダウンロード weightsフォルダーに以下のファイルを置く
- isnetis.ckpt
- realesr-animevideov3.pth
- ssd_best8.pth
cd ~/tkh_avatar
source ~/tkh/bin/activate
python3 tkh_avatar.pyブラウザで http://127.0.0.1:3001/ または http://localhost:3001/ にアクセス
# 仮想カメラをリセット（初回またはトラブル時）
./scripts/reset_virtual_camera.sh
# フォーマット確認
v4l2-ctl -d /dev/video20 --list-formats
# 出力: [0]: 'YUYV' (YUYV 4:2:2)
# ポートクリーンアップ（エラー時）
./scripts/cleanup_ports.shGoogle Meetでの使用手順:
- TKH Avatarで仮想カメラを有効化
- Google Meet設定で「TKH Avatar Cam」を選択
- カメラテスト: https://webcamtests.com
詳細は docs/VIRTUAL_CAMERA_GUIDE.md をご覧ください
- 📖 仮想カメラガイド - 基本設定
- 🛠️ 仮想カメラトラブルシューティング - 問題解決
- 📖 ドキュメント索引 - 全ドキュメント一覧
- 📖 THA3オリジナルREADME - 元プロジェクトドキュメント
tkh_avatar/ # プロジェクトルート
├── 📄 README.md # このファイル
├── 📄 THA3_ORIGINAL_README.md # THA3オリジナルドキュメント
├── 📄 INSTALLATION_GUIDE.md # インストール手順
├── 📄 CHANGELOG.md # 更新履歴
├── 🚀 tkh_avatar.py # メインアプリケーション
├── 📦 requirements.txt # Python依存関係
│
├── 📂 src/ # ソースコード
│ ├── core/ # コアライブラリ
│ ├── servers/ # 独立サーバープロセス
│ ├── utils/ # ユーティリティ
│ ├── models/ # 学習・データセット関連
│ └── test/ # テストファイル
│
├── 📂 static/ # Webインターフェース
│ ├── index_new.html # メインUI
│ ├── camera_test.html # カメラテストUI
│ └── styles.css # スタイルシート
│
├── 📂 data/ # データファイル
│ └── models/ # THA3モデルファイル（要ダウンロード）
│
├── 📂 weights/ # AIモデル重み
│ ├── ssd_best8.pth # 顔検出モデル
│ ├── realesr-animevideov3.pth # アップスケールモデル
│ └── isnetis.ckpt # 背景除去モデル
│
├── 📂 scripts/ # ユーティリティスクリプト
│ ├── setup_virtual_camera.sh # 仮想カメラセットアップ
│ ├── reset_virtual_camera.sh # 仮想カメラリセット
│ └── cleanup_ports.sh # ポートクリーンアップ
│
├── 📂 docs/ # ドキュメント
│ └── ... # 各種ガイド・仕様書
│
└── 📂 tha3/ # THA3コア実装
└── ... # 元プロジェクトコード
詳細は docs/PROJECT_STRUCTURE.md をご覧ください
- Webインターフェース提供
- 画像アップロード・ダウンロード処理
- WebSocketによるリアルタイム通信
- 仮想カメラ制御
-
TKH処理サーバー (
src/servers/poser_api_v1_3SC_server.py)- THA3ニューラルネットワーク推論
- 表情・姿勢パラメータ処理
-
顔追跡サーバー (
src/servers/sample_holistic_server.py)- MediaPipe Holisticによる顔検出
- 顔ランドマーク抽出
-
アップスケールサーバー (
src/servers/realesr_api_server2.py)- Real-ESRGANによる高解像度化
- 画像アップロード: キャラクター画像をドラッグ&ドロップまたは選択
- 表情調整: スライダーで眉毛、目、口を調整
- 頭部回転: X/Y/Z軸スライダーで角度変更
- Webカメラ連動: カメラボタンで自動顔追跡開始
- 仮想カメラ出力: ビデオ会議アプリで使用
詳細は docs/USER_MANUAL.md をご覧ください
# ポート設定
HTTP_PORT=3001
WEBSOCKET_PORT=8765
TKH_SERVER_PORT=3012
FACE_TRACKING_PORT=3011
# モデル設定
THA3_MODEL=standard_float # または separable_float, standard_half, separable_half
# 仮想カメラ
VIRTUAL_CAMERA_DEVICE=/dev/video20
VIRTUAL_CAMERA_FORMAT=YUYV # v3.0.1以降# v4l2loopbackを再読み込み
sudo modprobe -r v4l2loopback
sudo modprobe v4l2loopback devices=1 video_nr=20 exclusive_caps=0 card_label="TKH Avatar Cam"
# フォーマット確認
v4l2-ctl -d /dev/video20 --list-formats./scripts/cleanup_ports.sh# CUDAバージョン確認
nvidia-smi
nvcc --version
# PyTorchのCUDA対応確認
python3 -c "import torch; print(torch.cuda.is_available())"詳細は docs/VIRTUAL_CAMERA_TROUBLESHOOTING.md をご覧ください
このプロジェクトの追加実装部分（FastAPIサーバー、Webインターフェース、仮想カメラ統合等）は、オリジナルのTHA3プロジェクトと同じライセンスに従います。
詳細は THA3_ORIGINAL_README.md をご覧ください
このプロジェクトは、Pramook Khungurn 氏による Talking Head Anime 3 プロジェクトをベースにしています。
学術研究で本システムを使用する場合は、元プロジェクトを引用してください:
Pramook Khungurn. Talking Head(?) Anime from a Single Image 3: Now the Body Too. http://pkhungurn.github.io/talking-head-anime-3/, 2022. Accessed: YYYY-MM-DD.
@misc{Khungurn:2022,
author = {Pramook Khungurn},
title = {Talking Head(?) Anime from a Single Image 3: Now the Body Too},
howpublished = {\url{http://pkhungurn.github.io/talking-head-anime-3/}},
year = 2022,
note = {Accessed: YYYY-MM-DD},
}- 🌐 元プロジェクト: https://pkhungurn.github.io/talking-head-anime-3/
- 📦 GitHubリポジトリ: https://github.com/animede/tkh_avatar
- 📖 THA3オリジナルコード: https://github.com/pkhungurn/talking-head-anime-3-demo
Note: このシステムは個人・研究用途で開発されました。商用利用の際は、THA3のライセンス条項を確認してください。