iw3-gui

iw3-guiは実写のあらゆる画像・動画を3D画像・3D動画に変換するソフトウェアです。 VRで本当に見たかった画像・動画をVRデバイスで3Dメディアとして見れるようになります。

インストールについてはnunif windows packageを参照してください。

このソフトウェアはよい設定値が入力に依存していて調節が難しいソフトウェアです。前半に各項目の説明を記述して、後半に応用的な説明を記述します。

処理の概要は以下です。

入力画像（動画フレーム）から深度(各ピクセルの奥行き)を推定します
入力画像と推定した深度からステレオ画像(左右それぞれの目に映す画像)を生成します

入力

処理対象のファイルまたはフォルダを選択します。最初のボタンがファイル選択で、次のボタンがフォルダ選択です。ファイルひとつの場合はドラッグアンドドップもできます。

フォルダを選択した場合はフォルダ直下の画像ファイルと動画ファイルが対象になります。

処理を再開にチェックをつけるとすでに出力が存在するファイルをスキップします。

すべてのサブフォルダを処理にチェックをつけると指定フォルダより下の階層にあるすべてのファイルが対象になります。ただし出力フォルダ内は除外されます。指定したフォルダによっては非常に多くのファイルが対象になるので注意してください。

再生ボタンをクリックすると選択したファイルまたはフォルダが表示されます。

出力

出力フォルダを選択します。

入力がファイルの場合は出力ファイル名を直接入力することもできます。画像の場合は.jpg, .png, webp、動画の場合は.mp4の拡張子を使用してください。またVRで3Dメディアとして認識させるためにファイル名ルールも必要です。

同じフォルダを設定ボタンでは、入力と同じフォルダの下にiw3フォルダを作ってそこに出力します。

再生ボタンをクリックすると出力結果があればそれを表示します。なければ出力フォルダを表示します。

ステレオ生成

3D化の設定です。

3Dの強さ

奥行きの強さ(深さ)です。

(--divergenceがこの設定値です)

基本は2.0です。

このパラメータは、スクリーン位置の適切な距離を変えます。

低い値では、スクリーン位置の適切な距離は遠くなります。高い値では、スクリーン位置の適切な距離は近くなります。近くで見たい場合は高い値が適切ですが、高い値ではゴーストアーティファクトが発生しやすくなります。ゴーストアーティファクトは、深度の差が大きいところに発生するノイズのようなものです。人物と背景の境界が2重に見えて焦点が合わせづらくなります。

スクリーン位置はVR動画プレイヤー上のズームイン/ズームアウトで調節できます。

収束平面

スクリーンに対する3Dの奥行きが出る位置・方向です。

(--convergenceがこの設定値です)

0では、スクリーン位置から前に向かって表示されます。おそらくもっとも一般的な設定です。ただし、スクリーンの端のほうで左右の目で見える範囲が変わるので焦点が合わせづらくなります。

1では、スクリーン位置から奥に向かって表示されます。おそらくもっとも問題の発生しない設定です。曲面スクリーンにも適しています。ただし、表示位置が遠くみえます。

0.5は、0と1の中間です。デフォルト値です。

自分の大きさ

スクリーンに対する自分の大きさです。

(--ipd-offsetがこの設定値です)

人物を等身大で見たい等の理由で細かく調節するモチベーションがある場合に調節してください。

VR Player側で設定できる場合もあります。通常は0を選択してください。

メソッド

深度からステレオ画像（左右の画像）を生成する手法です。

Short Name
`row_flow_v3`	逆方向ワーピング(`grid_sample`)のパラメータを機械学習モデルで算出します。`0.0 <= divergence <= 5.0`の範囲で`forward_fill`で生成した合成データで学習されています。デフォルトメソッド。
`row_flow_v2`	以前のデフォルトメソッド。`0.0 <= divergence <= 2.5`の範囲でstable-diffusion-webui-depthmap-scriptで生成した合成データで学習されています。
`forward_fill`	深度順の順方向ワーピング（ソース側からのサンプリングは行わず穴は隣接ピクセルで埋める+重なった領域は深度的に前にあるほうで上書き）。非機械学習の率直なメソッド。
`row_flow_v3_sym`	`row_flow_v3`の左右対称制約版。左と右のワープパラメータは完全に左右対称になります。`row_flow_v3`より2倍速い。実験用。
`forward`	穴を埋めない`forward_fill`。実験用。
`grid_sample`,`backward`	素朴な逆方向ワーピング。ひどいゴーストアーティファクトが発生します。実験用。

ステレオ処理幅

ステレオ生成を実行する深度画像の解像度(画像の横幅)を指定します。

これはExport/Import時に使用する高度な設定です。通常は、Defaultを選択してください。

Defaultが指定されている場合は、何もしません。 Default以外が指定されている場合は、指定サイズに深度画像をリサイズしてから処理します。

Exportした深度画像を別のソフトウェアで処理するときにフレーム画像と画像サイズを合わせることがあり、その場合に深度画像が4Kや8Kになることがあります。iw3のステレオ生成モデルは、深度画像の最大横幅=1920pxで学習されているので、巨大な深度画像をImportすると出力が壊れます。その場合に指定サイズにダウンスケーリングしてから処理するための機能です。（この制限は深度画像の解像度についてであり、フレーム画像の解像度に制限はありません）

深度推定モデル

深度を推定する学習済みモデルを指定します。

深度推定にはZoeDepthまたはDepth-Anything、Depth-Anything-V2を使用しています。

Short Name
`ZoeD_N`	ZoeDepth model NYUv2(屋内シーンのデータ)
`ZoeD_K`	ZoeDepth model KITTI(屋外シーンのデータ)
`ZoeD_NK`	ZoeDepth model NYUv2 and KITTI
`ZoeD_Any_N`	Depth-Anything metric depth model NYUv2
`ZoeD_Any_K`	Depth-Anything metric depth model KITTI
`Any_S`	Depth-Anything model small. 一番速い
`Any_B`	Depth-Anything model base.
`Any_L`	Depth-Anything model large. 精度が高いが重い
`Any_V2_S`	Depth-Anything-V2 model small. 一番速いV2
`Any_V2_B`	Depth-Anything-V2 model base. (cc-by-nc-4.0)
`Any_V2_L`	Depth-Anything-V2 model large. (cc-by-nc-4.0) 深度の精度は一番高い
`Any_V2_N_S`	Depth-Anything-V2 Metric Depth model Hypersim small. Tuned for indoor scenes.
`Any_V2_N_B`	Depth-Anything-V2 Metric Depth model Hypersim base. Tuned for indoor scenes
`Any_V2_N_L`	Depth-Anything-V2 Metric Depth model Hypersim large. Tuned for indoor scenes. (cc-by-nc-4.0)
`Any_V2_K_S`	Depth-Anything-V2 Metric Depth model VKITTI small. Tuned for outdoor scenes (dashboard camera view).
`Any_V2_K_B`	Depth-Anything-V2 Metric Depth model VKITTI base. Tuned for outdoor scenes (dashboard camera view).
`Any_V2_K_L`	Depth-Anything-V2 Metric Depth model VKITTI large. Tuned for outdoor scenes (dashboard camera view). (cc-by-nc-4.0)

通常はZoeD_NかAny_B,またはZoeD_Any_Nを選択してください。

ZoeD_Nは屋内シーンのデータで調節されたモデルです。ZoeD_Kは、屋外シーンのデータで調節されたモデルですが、屋外シーンというのがドライブレコーダーの映像です（これが向いているケースはないと思います）。

Any_BはDepthAnythingの基本モデルです。Any_Sが速くて精度が低い、Any_Lが遅くて精度が高いバランスのモデルです。

ZoeD_Any_Nは、ZoeD_NのバックボーンをAny_Lにして学習されたモデルです。3Dシーンの生成結果は最もよいと思います。

DepthAnythingのほうが精度が高いですが、ステレオ生成の結果はZoeDepthのほうがよいことが多いです。DepthAnythingのほうが使用VRAMが少なく速いです。

イラスト/アニメには、ZoeDepthよりもDepthAnythingのほうがよいです。Any_V2_Lがよいですが、デフォルトでは利用できないので自分で配置する必要があります。

またZoeDepthとDepthAnythingは出力する深度の種類が違います。ZeoDepthはメートル単位の距離を出力していて、DepthAnythingはDisparity(視差)を出力しています。近い結果に見えるように変換式を調節していますが、モデルを変更すると深度の精度だけではなく他の設定の見え方も全体的に変わることに注意してください。

たくさんありますが、個人的には、ZoeD_N, Any_B, ZoeD_Any_Nのどれかをオススメします。

`Any_V2_B` ,`Any_V2_L`, `Any_V2_N_L`, `Any_V2_K_L` について

これらのモデルはcc-by-nc-4.0(非商用)の下で配布されています。nunifのMITライセンスと衝突するためデフォルトでは利用できません。

使用したい場合は、それらのライセンスに同意して自分でファイルを配置してください。

Short Name	ファイル
`Any_V2_B`	`iw3/pretrained_models/hub/checkpoints/depth_anything_v2_vitb.pth`
`Any_V2_L`	`iw3/pretrained_models/hub/checkpoints/depth_anything_v2_vitl.pth`
`Any_V2_N_L`	`iw3/pretrained_models/hub/checkpoints/depth_anything_v2_metric_hypersim_vitl.pth`
`Any_V2_K_L`	`iw3/pretrained_models/hub/checkpoints/depth_anything_v2_metric_vkitti_vitl.pth`

これらのファイルは https://huggingface.co/depth-anything のModelsセクションからダウンロードできます。開いたページのFiles and versionsタブにあります。ファイルが存在する場合のみGUI上に表示されます。

深度解像度

深度推定時の解像度を上げることができます。解像度が高いほど処理時間がかかります。

ZoeDepthモデルでは、モデル自体が高解像度に対応していないため、結果がよくなるかは分かりません。縦長の画像はデフォルトで大きめの解像度で計算されているので効果はありません。

DepthAnythingモデルでは512(518)で適切な解像度になり深度の精度が上がります。

前景拡大

正の値で、遠くほど立体感をなくしてその分の立体感を近い方に割り当てます。(背景の厚みを縮小して前景の厚みを拡大します)

屋外写真で前景(人物)の奥行きが圧縮されて平面に見える場合は3を試してみてください。動画では0をオススメします。

負の値では、逆の効果になります。背景が激しく揺れ動くことがあるので動画ではオススメはしません。

境界修正

この設定はDepthAnythingモデルでのみ有効になります。チェックをつけるとZoeD_Any_Nでも使用できます。

DepthAnythingの出力は精度が高いですが、ステレオ生成においては前景と背景の境界に歪みやアーティファクトが発生しやすくなります。このアプローチでは、前景側のセグメントを膨張させることでその問題を軽減します（歪む領域が前景から背景に移動します）。

0では無効になります。2がデフォルトです。4はもっとも目に優しい結果になりますが深度の解像度が落ちます。

フォーマット

出力形式を指定します。またVR動画プレイヤーにメディアの形式を認識させるためにファイル名にそれぞれ識別子を追加します。ファイル名ルール

Full SBSは、フル解像度のサイド・バイ・サイドです。

Half SBSは、ハーフ解像度のサイド・バイ・サイドです。画像の横幅が半分に圧縮されます。古いVR機器ではこのフォーマットしかサポートしていないことがあります。

Full TB,Half TBはトップ・ボトムです。3DTV(Polarized/Passive 3D system)では、トップ・ボトムのほうがサイド・バイ・サイドよりも高い解像度で再生できることがあります。

VR90は、正面90°のみを描画したVR180フォーマット(Equirectangular)です。再生時の操作が制限されるので通常はオススメしません。使用しているVR機器や投稿サイト等の都合で使いたい場合に指定してください。

Anaglyph *は、Red-Cyan Anaglyph 3D formatです。

ExportとExport Disparityは、深度画像とフレーム画像を画像シーケンスとして出力/再入力する機能です。詳しくは #97 (comment) を見てください。

ちらつきを軽減

フレーム間での深度のちらつきを減らします。個人的には、違いが分からないのと副作用もあるのででオススメしませんが、目がよくて深度のちらつきが気になることがあれば試してみてください。動画のみに影響します。

背景除去

背景を除去した画像から深度を推定します。

屋外シーン等で人物が平面に見える場合に使用すると修正できる場合があります。写真に対して細かく設定を調節するモチベーションがあるときに使用してみてください。

動画圧縮

動画出力時の設定です。主にlibx264の設定です。より詳しい情報は https://trac.ffmpeg.org/wiki/Encode/H.264 を参照してください。

最大フレームレート

動画のフレームレート(一秒間のフレーム数)が最大フレームレートを超えているときは最大フレームレートに制限します。超えていないときはオリジナルの（平均）フレームレートで出力します。

デフォルトで30FPSに制限されていることに注意してください。

60FPS動画の処理には30FPS制限の2倍の処理時間がかかることにも注意してください。

ピクセルフォーマット

出力動画のピクセルフォーマットを指定します。通常はyuv420pを指定してください。詳しい人は他の設定も使えます。色空間とも関連しています。

動画形式

コンテナ形式を指定します。

mp4は互換性の高い形式です。

mkvは変換中に視聴できます。変換速度が30FPSを超えていればリアルタイムで視聴できます（シークは変換済み範囲しかできません）。

aviはロスレス動画用に用意しています。自分で再エンコードする場合などに指定します。

動画コーデック

libx264はH.264用です。互換性の高い形式です。4Kなどの大きい動画ではファイルサイズ/ビットレートが大きくなり、再生に問題が起こることがあります。

libx265はH.265用です。通常はH.264よりもファイルサイズが小さくなります。ただし古い機器では対応していないことがあります。

utvideoはロスレス動画コーデックです。再生にはUt Video Codec Suiteのインストールが必要かもしれません。

ffmpegが対応しているコーデックを直接指定することもできますが、追加のオプションが指定できないのでうまく使えないかもしれません。

色空間

出力動画のYUVカラースペースとダイナミックレンジを指定します。

詳細は色空間についてを参照してください。

CRF

品質設定です。小さい値ほど品質が高くファイルサイズが大きくなります。0など選択より小さい値を直接入力することもできます。

レベル

H.264/H.265のレベルを指定できます。通常はautoをオススメします。

libx264では単にメタデータを設定するだけだと思います。

libx265ではより厳密でレベルの範囲外のサイズの動画に対して誤ったレベルを指定するとエラーになります。

関連するプロファイルに関しては、現在使っているライブラリの関係で指定する方法がありません。ただ、libx264では、preset=ultrafastのときにConstrained Baselineになり、preset=ultrafast以外ではHighになるようです。

プリセット

処理速度と圧縮率のバランスを決めるオプションです。遅い設定のほうが圧縮率が高くファイルサイズが小さくなります。

高解像度の動画にslower,veryslow,placeboを使用するとハードウェアデコーダーで正常に再生できない（ひどいアーティファクトが発生する）動画が生成されることがあるようです。 slowより遅い設定は使わないのが安全です。mediumをオススメします。

チューニング

入力にあった設定のセットを使用できます。

animation: アニメ
film: 映画実写
stillimage: スライドショー
grain: アナログフィルム (粒子状ノイズの維持）
fastdecode: いくつかのフィルタを無効にすることで再生時の負荷を減らします
zerolatency: シークが速くなります。

よくわからない場合は選択しません。

ビデオフィルタ

動画の追加処理です。

開始時間, 終了時間

入力動画内の処理する時間範囲を指定します。指定された時間範囲のみ出力します。チェックを付けなければすべて処理されます。

デインターレース

入力ストリームに対してデインターレースフィルタを適用します。インターレース方式の動画に使用します。（動画に細かい横線が点滅するやつを消します）

現在は、yadifが選択できます。他のフィルタやより高度なオプションを使いたい場合は、下記のvfオプションを使用してください。

vf

入力動画ストリームに対してffmpegのビデオフィルター(-vfオプション)を適用します。この処理は深度推定よりも前に適用されます。

ブランチを含む複雑な式は動作しません。フィルタ名1,フィルタ名2=パラメータ1:パラメータ2,...形式の直列な式のみ対応しています。パラメータ内の,は\,にエスケープしてください。式の解析が独自実装なのでうまくいかない式があるかもしれません。

回転

入力フレームを90°回転させます。スマホで撮影した動画など横向きになっている動画を処理前に修正する機能です。

パディング

出力フレーム内に黒の余白を追加します。通常はオススメしません。人物サイズやスクリーンの表示位置など細かく調節したい場合に使用してください。

出力サイズ制限

出力サイズを指定解像度内に制限します。スマホを使ったCardboard(安価なVRメガネ)で、解像度の大きい動画が再生できない場合に使用してください。

アスペクト比を維持にチェックがない場合は、指定されたサイズにフィットするようにリサイズします。VRプレイヤー側でアスペクト比を修正できる場合にチェックを外します。

プロセッサ

計算に関連する設定です。

デバイス

計算に使用するGPUまたはCPUを指定します。

GPUにはCUDAに対応しているグラフィックボードが表示されます。事実上NVIDIA製になります。

CPUでも動作はしますが、信じがたい遅さになります。

深度バッチサイズ

深度推定を同時に処理するフレーム数です。主に動画用です。画像は1フレームなので基本的には1で処理されます（TTAを使ったときは最大で2になります）。

一般的には、大きい値ほど多くのVRAM(グラフィックボードのメモリ)を使用して処理が速くなります。環境によっては小さい値のほうが速いこともあります。

VRAMが少ないGPUでは小さい値にしないとメモリ不足エラーになります。

ワーカースレッド

0以外で深度推定とステレオ生成をスレッドプール上で行います。

一般的には、デフォルトの0よりも2が速いです。ただし0以外にするとVRAM使用量が増えます。その分、深度バッチサイズを小さくする必要があるかもしれません。

Windowsや遅いディスクの環境では、小さいバッチサイズに大きいワーカースレッド数が速いことがあります。

低ビデオメモリ

すべての条件下で深度バッチサイズを1に制限にします。どうやってもVRAMのメモリ不足になる場合に試してみてください。

TTA

深度推定を左右反転してた2パターンの画像に対して行い結果を平均して品質を改善します。ただし処理時間が2倍になります。

FP16

計算に半精度浮動小数点(16bit float)を使用します。 Turing(RTX20シリーズ)以降のGPUでは有効にすることで処理が速くなりVRAMの使用量が減ります。

古いGPUでは遅くなったりエラーになったりするかもしれません。その場合はOFFにできます。

開始・キャンセル

開始ボタンで処理を開始します。キャンセルボタンで実行中の処理をキャンセルします。

応用

VR動画プレイヤー

Meta Quest 2上の以下の2つのソフトウェアで動作確認しています。

Pigasus VR Media Player

Pigasusは、3D動画、3D画像、SMB(共有ドライブ)すべてで完璧に動作します。ただし、個人的にはUIや操作があまり好きではありません。

もしソフトがひとつしか選べないならこれをオススメします。

SKYBOX VR Video Player

最近の更新(v1.1.5以降)でFull SBSの大体の機能は動作するようになりました。まだ以下の機能はありません。

画像の送りがコントローラーでできません
画面の高さが調節できません

ファイル名ルール

VR動画プレイヤーはファイル名によってメディアの形式を認識しています。

ファイル名の末尾に以下の識別子をつけると正しいフォーマットで認識されます。

_LRF_Full_SBS: Full SBS
_LR: Half SBS
_180x180_LR: VR180 (VR90)

出力にフォルダを指定した場合、上記の識別子が自動で追加されます。ファイル名を直接指定する場合は、手動で追加してください。

参考:

Pigasusでは LRF が必要 https://hanginghatstudios.com/pigasus-faq/#acc-tb_obg1300-0
SKYBOXでは Full_SBS が必要, https://forum.skybox.xyz/d/2161-skybox-vr-quest-v116-added-multi-language-keyboard-and-casting
DeoVRでは SBS か LR(LRF は動作しない)が必要, https://deovr.com/app/doc#naming

_LRF_Full_SBSは上記のソフト全てで動作します。

SKYBOXは何か別の条件(ファイル名が長すぎる?)で認識しないことがあります。その場合はメニューから3D Full-SBS Matchingを有効にできます。

トラブルシューティング

前景(人物)が平面になる

屋外シーンの写真で発生しやすいです。

この問題と戦ういくつかの方法があります。

前景拡大を3にする
背景除去を有効にする
それらの組み合わせ

この問題の原因のひとつは、iw3ではあらゆるシーンを同じ厚さ内に表示していることです。壁まで2メートルのシーンと空が宇宙まで続いているシーンでは、人物の厚みに使える範囲が大きく変わります。 iw3では、遠くほど厚みを無くしてその分を近くに割り当てることでこの問題を軽減していますが、汎用的な設定では限界があります。

前景拡大の値を上げるほど、遠くほど厚みをなくしてその分を近くに割り当てます。

背景除去を行うと背景の距離が無くなるのでうまくいけば距離の問題が完全に解決します。ただし背景除去の精度の問題があり、複雑なシーンでは人物の切り抜きがうまくいきません。何が前景で何が背景なのかという問題もあります。

動画エンコード・デコードエラー

フォーマットをissueに投稿してもらえれば解決できるかもしれません。単純にファイルが壊れている場合は、他の方法で修正してください。

巨人!!

これはSBS 3D動画では原寸大を表現できないという根本的な問題です。

写真やシーンが動かない動画では、手動でサイズ感を調節できます。

VR動画プレイヤーの設定で調節
自分の大きさで調節
パディングで調節
組み合わせ

SKYBOX Playerでは、3D Effectを-0.3などマイナス側に動かすと対象が小さく見えます。

Pigasusでは、設定 > 高度な設定 > IPDのスライダーを大きくすると対象が小さく見えます。またトリガーボタンをダブルクリックすると画像内の一部を拡大・移動できます。

自分の大きさ設定では、それらよりも更に小さくできます。ただし、小さくするほど厚みがなくなります。この場合、3Dの強さを大きくできますが、大きくしぎるとゴーストアーティファクトが発生します。

また曲面スクリーンを使っているとサイズが大きく見えるので注意してください。

また収束平面が0と1では大きさの見え方も変わるので注意してください。1のほうが大きく見えます。

CUDA Out of Memory

GPUのメモリ不足です。深度バッチサイズを小さくするか低VRAMを有効にしてみてください。

また一度のこのエラーになると再度発生しやすくなるかもしれません。一度プログラムを終了してみてください。

作者はこのソフトウェアをRTX 3070 Ti(8GB VRAM, Linux)とGTX 1050 Ti(4GB VRAM, ノートPC, Windows)で動作確認していますが、どちらもデフォルトの設定で動作しています。

ちなみに上記の環境では、RTX 3070 TiのマシンがGTX 1050 Tiのマシンの10倍速いので、もしこのソフトウェアを気に入って古いGPUを使っている場合はRTX 3070 Ti以上の購入をオススメします。10時間かかる動画変換処理が1時間で終わるかもしれません。（OSや本体の違いもあるので言い切ることはできません）

Files

gui_ja.md

Latest commit

History