メディアとオブジェクトをログする

Weights & Biases Python SDK でメディアをログすると、モデルの入力と出力を確認したり、run、モデル、データセット間で結果を比較したりできます。サポートされるタイプは、画像、オーディオ、動画、ヒストグラム、3D ポイントクラウド、分子、HTML です。 API の詳細については、データタイプリファレンスを参照してください。例については、モデル予測の report を参照するか、動画の手順ガイドをご覧ください。

前提条件

一部のメディアタイプでは、追加の依存関係が必要です。メディア用の依存関係を含めて Weights & Biases SDK をインストールするには、次のコマンドを実行します。

pip install wandb[media]

画像

wandb.Image を使用すると、NumPy 配列、PIL 画像、ローカルファイルから画像をログできます。画像をログすると、入力、出力、フィルターの重み、活性化を確認できます。

トレーニングのパフォーマンスと画像の読み込み時間への影響を抑えるため、CoreWeave では 1 ステップあたりにログする画像を 50 枚未満にすることを推奨しています。

以下のタブでは、入力タイプごとに画像をログする方法を説明します。

配列
PIL 画像
画像ファイル

torchvision の make_grid などを使って画像を手動で構築する場合は、配列を直接渡します。

Weights & Biases は Pillow を使用して配列を PNG 画像に変換します。

import wandb
import numpy as np

with wandb.init(project="image-log-example") as run:
    images = wandb.Image(image_array, caption="Top: Output, Bottom: Input")
    run.log({"examples": images})

NumPy 配列の形状は (height, width, channels) にします。Weights & Biases は、チャンネル数が 1、3、4 の場合、それぞれグレースケール、RGB、RGBA と判断します。画像はデフォルトで PNG ファイルとして保存されます。値が 0～255 の範囲外にある場合、またはすべての値が 0～1 の範囲内にある場合、ピクセル値は 0～255 の範囲に正規化されます。正規化を無効にするには、normalize=False を渡します。配列の変換をより細かく制御したい場合は、PIL 画像 タブに示すように PIL 画像を作成してください。

PIL.Image を作成し、wandb.Image に渡します。

from PIL import Image

image_array = np.random.randint(0, 256, (128, 128, 3), dtype=np.uint8)

with wandb.init(project="pil-image-example") as run:
    # NumPy 配列から PIL 画像を作成する
    image = Image.fromarray(image_array)

    # 必要に応じて RGB に変換する
    if image.mode != "RGB":
        image = image.convert("RGB")

    # 画像をログする
    run.log({"example": wandb.Image(image, caption="My Image")})

既存の画像ファイルをログするには、そのパスを wandb.Image に渡します。

with wandb.init(project="media-log-example") as run:
    run.log({"example": wandb.Image("myimage.jpg")})

トレーニングステップ間で画像を比較するには、Weights & Biases アプリの UI で画像パネルを展開し、step スライダーを使用します。画像を選択すると全画面ビューで開き、マウスまたはキーボードショートカットでズームやパンを行えます。複数の run、ステップ、インデックスにわたる画像や動画を 1 つのビューで比較するには、Compare モードを使用します。

画像オーバーレイ

セマンティックセグメンテーションマスクをログすると、Weights & Biases アプリの UI で不透明度を調整したり、ステップごとの変化を確認したりできます。

セグメンテーションマスク
バウンディングボックス

セグメンテーションマスクまたはバウンディングボックス付きの画像をログすると、Weights & Biases のアプリの UI でモデルの予測と正解データを確認できます。

wandb.Image の masks 引数に辞書を渡します。各キーには predictions や ground_truth などのマスク名を指定します。各値は、次のフィールドを持つ辞書です。

フィールド	説明
`mask_data`	ピクセルごとの整数クラスラベルを格納した 2D NumPy 配列。`mask_data` と `path` のどちらか一方を指定します。
`path`	保存済みのマスク画像へのパス。`path` と `mask_data` のどちらか一方を指定します。
`class_labels`	整数クラスラベルを人が読める名前に対応付ける辞書 (省略可能)。

1 つの画像に複数のマスクをログするには、マスクごとに個別の辞書を指定します。

mask_data = np.array([[1, 2, 2, ..., 2, 2, 1], ...])

class_labels = {1: "tree", 2: "car", 3: "road"}

mask_img = wandb.Image(
    image,
    masks={
        "predictions": {"mask_data": mask_data, "class_labels": class_labels},
        "ground_truth": {
            # ...
        },
        # ...
    },
)

各キーのセグメンテーションマスクは、ステップごと (wandb.Run.log() の呼び出しごと) に定義されます。

同じマスクキーに対してステップごとに異なる値が指定された場合、画像にはそのキーの最新の値のみが適用されます。
ステップごとに異なるマスクキーが指定された場合、可視性のコントロールにはすべてのキーが表示されますが、画像に適用されるのは選択したステップで定義されたマスクのみです。そのステップで定義されていないマスクの表示を切り替えても、画像は変わりません。

完全な設定例については、セグメンテーションマスクの report とサンプルノートブックを参照してください。

バウンディングボックス付きの画像をログし、Weights & Biases のアプリの UI でフィルターと可視性のコントロールを使用して、ボックスのグループを確認します。

wandb.Image の boxes 引数に辞書を渡します。各キーは predictions や ground_truth などのグループ名を表します。各値には次のフィールドを含めます。

フィールド	説明
`box_data`	辞書のリスト。バウンディングボックスごとに 1 つの辞書を指定します。
`class_labels`	クラス ID をわかりやすい名前に対応付ける辞書 (省略可能)。省略した場合、Weights & Biases は `class_0` や `class_1` などの名前を自動生成します。

box_data 内の各辞書は 1 つのボックスを表します。

フィールド	説明
`position`	ボックスの位置とサイズ。`minX`、`maxX`、`minY`、`maxY` の組み合わせ、または `middle`、`width`、`height` の組み合わせのいずれかで指定します。`middle` には `[x, y]` 座標を指定します。ボックスごとに異なる形式を使用できます。
`class_id`	`class_labels` 内のエントリに対応する整数のクラス ID。
`scores`	スコア名を数値に対応付ける辞書。これらのスコアを使用して、Weights & Biases のアプリの UI でボックスをフィルタリングできます。
`domain`	座標の単位。ピクセル座標を使用する場合は `"pixel"` に設定します。デフォルトでは、座標は画像サイズに対する 0 から 1 の比率で表されます。
`box_caption`	ボックス上に表示するテキスト (省略可能)。

この例では、相対座標で指定したボックスとピクセル座標で指定したボックスを 1 つずつログします。

import wandb

class_id_to_label = {
    1: "car",
    2: "road",
    3: "building"
}

img = wandb.Image(
    image,
    boxes={
        "predictions": {
            "box_data": [
                {
                    # デフォルトの相対座標（比率）ドメインで表したボックス
                    "position": {"minX": 0.1, "maxX": 0.2, "minY": 0.3, "maxY": 0.4},
                    "class_id": 2,
                    "box_caption": class_id_to_label[2],
                    "scores": {"acc": 0.1, "loss": 1.2},
                    # ピクセルドメインで表した別のボックス
                    # （これは説明用の例です。実際には、すべてのボックスが
                    # 同じドメイン／形式になることが多いでしょう）
                    "position": {"middle": [150, 20], "width": 68, "height": 112},
                    "domain": "pixel",
                    "class_id": 3,
                    "box_caption": "a building",
                    "scores": {"acc": 0.5, "loss": 0.7},
                    # ...
                    # 必要な数だけボックスをログします
                }
            ],
            "class_labels": class_id_to_label,
        },
        # 意味のあるボックスのまとまりごとに、一意のキー名を付けてログします
        "ground_truth": {
            # ...
        },
    },
)

with wandb.init(project="my_project") as run:
    run.log({"driving_scene": img})

対話型の例については、バウンディングボックスの report を参照してください。

表内の画像オーバーレイ

Weights & Biases の Table で画像オーバーレイを表示するには、マスクまたはバウンディングボックスを含む wandb.Image オブジェクトを各行に追加します。

Segmentation Masks
Bounding Boxes

この例では、表の各行にセグメンテーションマスク付きの画像を 1 つずつログします：

table = wandb.Table(columns=["ID", "Image"])

for id, img, label in zip(ids, images, labels):
    mask_img = wandb.Image(
        img,
        masks={
            "prediction": {
                "mask_data": label,
                "class_labels": class_labels
                }
            # ...
        },
    )

    table.add_data(id, mask_img)

with wandb.init(project="my_project") as run:
    run.log({"Table": table})

この例では、表の各行にバウンディングボックス付きの画像を 1 つずつログします：

table = wandb.Table(columns=["ID", "Image"])

for id, img, boxes in zip(ids, images, boxes_set):
    box_img = wandb.Image(
        img,
        boxes={
            "prediction": {
                "box_data": [
                    {
                        "position": {
                            "minX": box["minX"],
                            "minY": box["minY"],
                            "maxX": box["maxX"],
                            "maxY": box["maxY"],
                        },
                        "class_id": box["class_id"],
                        "box_caption": box["caption"],
                        "domain": "pixel",
                    }
                    for box in boxes
                ],
                "class_labels": class_labels,
            }
        },
    )

ヒストグラム

wandb.Histogram を使用すると、モデルの勾配などの数値の分布をログできます。Weights & Biases のアプリの UI では、x 軸にトレーニングステップ、y 軸にメトリクス値が表示され、色の濃淡で各ビンの件数を表します。

基本的なヒストグラムのログ
柔軟なヒストグラムのログ

リスト、配列、テンソルなどの数値のシーケンスを wandb.Histogram に渡します。Weights & Biases は配列やテンソルを平坦化し、numpy.histogram() を使用してヒストグラムを計算します。デフォルトでは、ヒストグラムのビン数は 64 です。ビン数をカスタマイズするには、num_bins に最大 512 までの値を設定します。

with wandb.init() as run:
    run.log({"gradients": wandb.Histogram(grads)})

ヒストグラムの計算方法を制御するには、np.histogram() を呼び出し、返されたタプルを np_histogram に渡します。

import numpy as np

np_hist_grads = np.histogram(grads, density=True, range=(0.0, 1.0))

with wandb.init() as run:
    run.log({"gradients": wandb.Histogram(np_hist_grads)})

必要に応じて density=True を設定すると、ビンの値を件数ではなく確率密度で表せます。

3D 可視化

wandb.Object3D を使用して、バウンディングボックス付きの 3D ポイントクラウドと lidar シーンをログします。ポイントの座標に加え、必要に応じて色またはカテゴリラベルを含めた NumPy 配列を指定します。ポイントクラウドは Weights & Biases アプリの UI で対話的に操作できます。ドラッグしてビューを回転したり、ズームして細部を確認したり、Control キーを押しながらマウスを操作してシーン内を移動したりできます。次の report では、Lyft データセットのシーンを 3D バウンディングボックス付きで表示しています。

Weights & Biases アプリの UI では、ポイントクラウドごとに最大 300,000 ポイントまで表示されます。

NumPy の配列形式

次のいずれかの配列形式を使用します。n はポイント数です。

形状	ポイント形式	説明
`(n, 3)`	`[x, y, z]`	ポイントの座標。
`(n, 4)`	`[x, y, z, category]`	座標と、1～14 のカテゴリ (セグメンテーションのクラスなど)。
`(n, 6)`	`[x, y, z, r, g, b]`	座標と、0～255 の赤、緑、青の値。

Python オブジェクト

wandb.Object3D.from_point_cloud() を使用すると、ポイント、バウンディングボックス、ベクトルを含むシーンを作成できます。

import wandb
import numpy as np

points = np.array([
    [0.2, 0.3, 0.4, 255, 0, 0],
    [0.5, 0.6, 0.7, 0, 255, 0],
    [0.8, 0.9, 0.2, 0, 0, 255],
])

boxes = [{
    "corners": [
        [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
        [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1],
    ],
    "color": [0, 0, 255],
    "label": "example region",
    "score": 0.6,
}]

scene = wandb.Object3D.from_point_cloud(
    points=points,
    boxes=boxes,
    vectors=[{"start": [0, 0, 0], "end": [0.1, 0.2, 0.5], "color": [255, 0, 0]}],
    point_cloud_type="lidar/beta",
)

with wandb.init() as run:
    run.log({"my_first_point_cloud": scene})

Weights & Biases のアプリの UI でポイントクラウド内を移動するには、Control キーを押しながらマウスを動かします。

ポイントクラウドファイル

JSON ファイルからポイントクラウドデータを読み込むには、wandb.Object3D.from_file() を使用します。

run.log({"my_cloud_from_file": wandb.Object3D.from_file(
     "./my_point_cloud.pts.json"
)})

次の JSON は、ポイントクラウドデータの形式を示しています。

{
  "points": [
    [0.2, 0.3, 0.4, 255, 0, 0],
    [0.5, 0.6, 0.7, 0, 255, 0],
    [0.8, 0.9, 0.2, 0, 0, 255]
  ],
  "boxes": [
    {
      "corners": [
        [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
        [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]
      ],
      "color": [0, 0, 255],
      "label": "example region",
      "score": 0.6
    }
  ],
  "type": "lidar/beta"
}

NumPy 配列

サポートされる配列形式のいずれかを使って、wandb.Object3D.from_numpy() を使用します。

# 座標のみ
xyz_points = np.array([[0.4, 1, 1.3], [1, 1, 1], [1.2, 1, 1.2]])

# 座標とカテゴリラベル
category_points = np.array([[0.4, 1, 1.3, 1], [1, 1, 1, 1], [1.2, 1, 1.2, 12]])

# 座標と RGB 色
rgb_points = np.array([
    [0.4, 1, 1.3, 255, 0, 0],
    [1, 1, 1, 0, 255, 0],
    [1.2, 1, 1.2, 0, 0, 255],
])

with wandb.init() as run:
    run.log({
        "xyz_point_cloud": wandb.Object3D.from_numpy(xyz_points),
        "category_point_cloud": wandb.Object3D.from_numpy(category_points),
        "rgb_point_cloud": wandb.Object3D.from_numpy(rgb_points),
    })

分子

wandb.Molecule を使用して分子データをログし、Weights & Biases のアプリの UI で 3D 構造を確認できます。

run.log({"protein": wandb.Molecule("6lu7.pdb")})

サポートされるファイルタイプは pdb、pqr、mmcif、mcif、cif、sdf、sd、gro、mol2、mmtf です。 SMILES 文字列、RDKit の mol ファイル、rdkit.Chem.rdchem.Mol オブジェクトをログすることもできます。これらの例を実行するには RDKit が必要です。

from rdkit import Chem

resveratrol = rdkit.Chem.MolFromSmiles("Oc1ccc(cc1)C=Cc1cc(O)cc(c1)O")

with wandb.init() as run:
    run.log(
        {
            "resveratrol": wandb.Molecule.from_rdkit(resveratrol),
            "green fluorescent protein": wandb.Molecule.from_rdkit("2b3p.mol"),
            "acetaminophen": wandb.Molecule.from_smiles("CC(=O)Nc1ccc(O)cc1"),
        }
    )

対話型の例については、AlphaFold ワークスペースを参照してください。

分子の2Dビュー

wandb.Image データタイプと rdkit を使用して、分子の2Dビューをログできます。

from rdkit import Chem
from rdkit.Chem import AllChem, Draw

molecule = Chem.MolFromSmiles("CC(=O)O")
AllChem.Compute2DCoords(molecule)
pil_image = Draw.MolToImage(molecule, size=(300, 300))

with wandb.init() as run:
    run.log({"acetic_acid": wandb.Image(pil_image)})

その他のメディア

Weights & Biases では、ほかにもさまざまなメディアタイプのログをサポートしています。

オーディオ

オーディオデータをログするには wandb.Audio を使用します。sample_rate には、録音のサンプリングレートをヘルツ単位で設定します。

with wandb.init() as run:
    run.log({"whale songs": wandb.Audio(np_array, caption="OooOoo", sample_rate=32)})

1ステップあたり最大100個のオーディオクリップをログすることができます。詳細については、audio-file を参照してください。

動画

wandb.Video を使用して動画ファイルをログします。

with wandb.init() as run:
    run.log({"video": wandb.Video("myvideo.mp4")})

動画フレームの NumPy 配列をログするには、出力フォーマットとフレームレートを指定します：

with wandb.init() as run:
    run.log({"video": wandb.Video(video_array, fps=4, format="gif")})

単一の動画には (frames, channels, height, width)、バッチには (batch, frames, channels, height, width) の形状を使用します。NumPy 配列のエンコードには FFmpeg と MoviePy が必要です。サポートされる形式は "gif"、"mp4"、"webm"、"ogg" です。配列またはインメモリストリームを渡す場合は、format を指定してください。生のフレームをエンコードする場合、デフォルトのフレームレートは 4 fps (1 秒あたり 4 フレーム) です。ファイルパスを指定すると、Weights & Biases はファイルが存在すること、およびサポートされる形式であることを確認します。BytesIO オブジェクトを指定すると、Weights & Biases は指定された形式を拡張子とする一時ファイルを作成します。動画を表示・再生するには、プロジェクトの Workspace、run の Workspace、または report でメディアパネルを開きます。Compare モードを使用すると、run 間やステップ間で動画を比較できます。

テキスト

wandb.Table を使用すると、予測、ラベル、その他の値と並べてテキストを表示できます。表を作成する際に列名を指定してください。デフォルトでは、列ヘッダーは ["Input", "Output", "Expected"] です。UI のパフォーマンスを最適化するため、デフォルトの最大行数は 10,000 に設定されています。ただし、wandb.Table.MAX_ROWS = {DESIRED_MAX} を使用して、最大行数を明示的に上書きすることができます。

columns = ["Text", "Predicted Sentiment", "True Sentiment"]
data = [["I love my phone", "1", "1"], ["My phone is terrible", "0", "-1"]]

with wandb.init(project="my_project") as run:
    table = wandb.Table(data=data, columns=columns)
    run.log({"examples": table})

または、wandb.Table.add_data() を使用して行を追加することもできます。

table = wandb.Table(columns=columns)
table.add_data("I love my phone", "positive", "positive")
table.add_data("My phone stopped working", "negative", "negative")
run.log({"text_examples": table})

pandas の DataFrame から表を作成するには、その DataFrame を dataframe に渡します。

table = wandb.Table(dataframe=my_dataframe)
with wandb.init() as run:
    run.log({"examples": table})

詳細な使用量情報については、string を参照してください。

HTML

wandb.Html を使用すると、Run page のパネルにカスタム HTML を表示できます。HTML ファイルまたは文字列を渡します。

with wandb.init() as run:
    run.log({"custom_string": wandb.Html('<a href="https://mysite">Link</a>')})
    
    with open("some.html") as f:
        run.log({"custom_file": wandb.Html(f)})

デフォルトでは、Weights & Biases は HTML にスタイルを追加します。この動作を無効にするには、inject=False を渡します。この動作をオフにするには、inject=False を渡します。

with wandb.init() as run:
    with open("some.html") as html_file:
        run.log({"custom_file": wandb.Html(html_file, inject=False)})

使用方法の詳細については、html-file を参照してください。

​前提条件

​画像

​画像オーバーレイ

​表内の画像オーバーレイ

​ヒストグラム

​3D 可視化

​NumPy の配列形式

​Python オブジェクト

​ポイントクラウドファイル

​NumPy 配列

​分子

​分子の2Dビュー

​その他のメディア

​オーディオ

​動画

​テキスト

​HTML

前提条件

画像

画像オーバーレイ

表内の画像オーバーレイ

ヒストグラム

3D 可視化

NumPy の配列形式

Python オブジェクト

ポイントクラウドファイル

NumPy 配列

分子

分子の2Dビュー

その他のメディア

オーディオ

動画

テキスト

HTML