미디어 및 객체 로깅

3D 포인트 클라우드와 분자부터 HTML과 히스토그램까지 다양한 리치 미디어를 로깅합니다

이미지, 비디오, 오디오 등 다양한 형식을 지원합니다. 리치 미디어를 로그해 결과를 탐색하고 run, 모델, 데이터셋을 시각적으로 비교해 보세요. 아래에서 예제와 사용 방법 가이드를 확인하세요.

자세한 내용은 데이터 유형 레퍼런스를 참조하세요.

더 자세한 내용은 모델 예측을 시각화하는 데모 리포트를 확인하거나 비디오 워크스루를 시청하세요.

​

사전 요구 사항

W&B SDK로 미디어 객체를 로깅하려면 추가 의존성을 설치해야 할 수 있습니다. 이러한 의존성은 다음 명령어를 실행해 설치할 수 있습니다.

pip install wandb[media]

​

이미지

입력, 출력, 필터 가중치, 활성화 등을 추적하려면 이미지를 로깅하세요.

이미지는 NumPy 배열, PIL 이미지, 또는 파일 시스템에서 직접 로깅할 수 있습니다.

각 step에서 이미지를 로깅할 때마다 UI에서 확인할 수 있습니다. 이미지 패널을 펼친 다음 step 슬라이더를 사용해 서로 다른 step의 이미지를 살펴보세요. 이렇게 하면 트레이닝 중 모델 출력이 어떻게 변하는지 쉽게 비교할 수 있습니다. 미디어 패널을 클릭하면 이미지를 전체 화면 모드로 볼 수 있습니다. 여기서는 확대 및 이동이 가능하며, 키보드 단축키도 사용할 수 있습니다.

서로 다른 run, step, 또는 인덱스의 이미지나 비디오를 한 뷰에서 비교하려면 미디어 패널에서 Compare mode를 사용하세요.

트레이닝 중 로깅이 병목이 되거나, 결과를 볼 때 이미지 로딩이 병목이 되는 것을 방지하려면 step당 50개 미만의 이미지를 로깅하는 것이 좋습니다.

배열을 이미지로 로깅하기

[torchvision의 make_grid 같은 방식으로] 이미지를 수동으로 만들 때는 배열을 직접 제공하세요.

배열은 Pillow를 사용해 png로 변환됩니다.

import wandb

with wandb.init(project="image-log-example") as run:

    images = wandb.Image(image_array, caption="Top: Output, Bottom: Input")

    run.log({"examples": images})

마지막 차원이 1이면 그레이스케일, 3이면 RGB, 4이면 RGBA 이미지로 간주합니다. 배열에 float가 포함되어 있으면 0에서 255 사이의 정수로 변환합니다. 이미지를 다른 방식으로 정규화하려면 mode를 수동으로 지정하거나, 이 패널의 “Logging PIL Images” 탭에 설명된 대로 PIL.Image를 직접 제공하면 됩니다.

PIL 이미지 로깅하기

배열을 이미지로 변환하는 과정을 완전히 제어하려면 PIL.Image를 직접 생성해 바로 제공하세요.

from PIL import Image

with wandb.init(project="") 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")})

파일에서 이미지 로깅하기

더 세밀하게 제어하려면 원하는 방식으로 이미지를 만든 뒤 디스크에 저장하고 파일 경로를 제공하세요.

import wandb
from PIL import Image

with wandb.init(project="") as run:

    im = Image.fromarray(...)
    rgb_im = im.convert("RGB")
    rgb_im.save("myimage.jpg")

    run.log({"example": wandb.Image("myimage.jpg")})

​

이미지 오버레이

세그멘테이션 마스크

시맨틱 세그멘테이션 마스크를 로깅하고 W&B UI에서 불투명도 조정, 시간에 따른 변화 확인 등 다양한 방식으로 상호작용할 수 있습니다.

오버레이를 로깅하려면 wandb.Image의 masks 키워드 인수에 다음 키와 값을 포함한 딕셔너리를 전달하세요:

• 이미지 마스크를 나타내는 다음 두 키 중 하나:
  • "mask_data": 각 픽셀의 정수 클래스 레이블을 포함하는 2D NumPy 배열
  • "path": (string) 저장된 이미지 마스크 파일 경로
• "class_labels": (선택) 이미지 마스크의 정수 클래스 레이블을 알아보기 쉬운 클래스 이름에 매핑하는 딕셔너리

여러 마스크를 로깅하려면 아래 코드 스니펫과 같이 여러 키를 포함한 마스크 딕셔너리를 로깅하세요.

라이브 예제 참조

샘플 코드

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": {
            # ...
        },
        # ...
    },
)

키의 세그멘테이션 마스크는 각 step(run.log()의 각 call)에서 정의됩니다.

• step마다 동일한 마스크 키에 서로 다른 값이 있으면, 해당 키의 가장 최근 값만 이미지에 적용됩니다.
• step마다 서로 다른 마스크 키가 있으면, 각 키의 모든 값이 표시되지만 현재 보고 있는 step에 정의된 값만 이미지에 적용됩니다. 해당 step에 정의되지 않은 마스크의 표시 여부를 전환해도 이미지는 변경되지 않습니다.

바운딩 박스

이미지와 함께 바운딩 박스를 로깅하고, 필터와 표시/숨기기를 사용해 UI에서 서로 다른 박스 집합을 동적으로 시각화할 수 있습니다.

라이브 예제 보기

바운딩 박스를 로깅하려면 wandb.Image의 boxes 키워드 인수에 다음 키와 값을 포함한 딕셔너리를 제공해야 합니다:

• box_data: 각 박스에 하나씩 대응하는 딕셔너리 목록입니다. 박스 딕셔너리 형식은 아래에 설명되어 있습니다.
  • position: 아래 설명된 두 가지 형식 중 하나로 박스의 위치와 크기를 나타내는 딕셔너리입니다. 모든 박스가 같은 형식을 사용할 필요는 없습니다.
    • 옵션 1: {"minX", "maxX", "minY", "maxY"}. 각 박스 차원의 상한과 하한을 정의하는 좌표 집합을 제공합니다.
    • 옵션 2: {"middle", "width", "height"}. middle 좌표를 [x,y]로, width와 height를 스칼라 값으로 지정하는 좌표 집합을 제공합니다.
  • class_id: 박스의 클래스 ID를 나타내는 정수입니다. 아래의 class_labels 키를 참조하세요.
  • scores: 점수에 대한 문자열 레이블과 숫자 값으로 이루어진 딕셔너리입니다. UI에서 박스를 필터링하는 데 사용할 수 있습니다.
  • domain: 박스 좌표의 단위/형식을 지정합니다. 박스 좌표가 이미지 크기 범위 내의 정수처럼 픽셀 공간으로 표현되는 경우 이 값을 “pixel”로 설정하세요. 기본적으로 domain은 0과 1 사이의 부동소수점 수로 표현되는 이미지의 비율/백분율로 가정됩니다.
  • box_caption: (선택) 이 박스에 레이블 텍스트로 표시할 문자열
• class_labels: (선택) class_id를 문자열에 매핑하는 딕셔너리입니다. 기본적으로 class_0, class_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})

​

Tables의 이미지 오버레이

세그멘테이션 마스크

테이블에서 세그멘테이션 마스크를 로그하려면 각 행에 wandb.Image 객체를 제공해야 합니다.

예시는 아래 코드 스니펫에 나와 있습니다:

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})

바운딩 박스

테이블에서 바운딩 박스가 포함된 이미지를 로그하려면 각 행에 wandb.Image 객체를 제공해야 합니다.

예시는 아래 코드 스니펫에 나와 있습니다:

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,
            }
        },
    )

​

히스토그램

기본 히스토그램 로깅하기

리스트, 배열, 텐서와 같은 숫자 시퀀스를 첫 번째 인수로 제공하면 np.histogram()을 호출해 히스토그램을 자동으로 생성합니다. 모든 배열/텐서는 평탄화됩니다. 기본값인 64 bins를 재정의하려면 선택 num_bins 키워드 인수를 사용할 수 있습니다. 지원되는 최대 bins 수는 512입니다.

UI에서는 트레이닝 전반에 걸쳐 로깅된 히스토그램을 쉽게 비교할 수 있도록 x축에 트레이닝 step, y축에 메트릭 값, 색상으로 개수를 나타내는 방식으로 히스토그램을 표시합니다. 일회성 히스토그램을 로깅하는 방법에 대한 자세한 내용은 이 패널의 “Summary의 히스토그램” 탭을 참조하세요.

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

유연한 히스토그램 로깅하기

더 세밀하게 제어하려면 np.histogram()을 호출하고 반환된 튜플을 np_histogram 키워드 인수로 전달하세요.

np_hist_grads = np.histogram(grads, density=True, range=(0.0, 1.0))
run.log({"gradients": wandb.Histogram(np_hist_grads)})

히스토그램이 summary에 있으면 Run Page의 Overview 탭에 표시됩니다. 이력에 있으면 Charts 탭에서 시간에 따른 bins의 히트맵으로 표시됩니다.

​

3D 시각화

바운딩 박스가 포함된 3D 포인트 클라우드와 LiDAR 장면을 로깅합니다. 렌더링할 포인트의 좌표와 색상이 포함된 NumPy 배열을 전달하세요.

point_cloud = np.array([[0, 0, 0, COLOR]])

run.log({"point_cloud": wandb.Object3D(point_cloud)})

W&B UI는 데이터를 300,000포인트까지만 표시합니다.

​

NumPy 배열 형식

유연한 색상 구성을 위해 세 가지 NumPy 배열 형식을 지원합니다.

• [[x, y, z], ...] nx3
• [[x, y, z, c], ...] nx4 | c는 [1, 14] 범위의 범주 값입니다` (세그멘테이션에 유용)
• [[x, y, z, r, g, b], ...] nx6 | r,g,b는 빨강, 초록, 파랑 색상 채널의 [0,255] 범위 값입니다.

​

Python 객체

이 스키마를 사용하면 Python 객체를 정의한 뒤 이를 from_point_cloud 방법에 전달할 수 있습니다.

• points는 위에 나온 단순한 포인트 클라우드 렌더러와 동일한 형식으로 렌더링할 포인트의 좌표와 색상을 포함하는 NumPy 배열입니다.
• boxes는 세 가지 속성을 갖는 Python 딕셔너리의 NumPy 배열입니다:
  • corners- 8개 코너의 목록
  • label- 박스에 렌더링할 라벨을 나타내는 문자열 (선택)
  • color- 박스의 색상을 나타내는 RGB 값
  • score - 바운딩 박스에 표시되는 숫자 값으로, 표시할 바운딩 박스를 필터링하는 데 사용할 수 있습니다(예: score > 0.75인 바운딩 박스만 표시). (선택)
• type은 렌더링할 장면 유형을 나타내는 문자열입니다. 현재 지원되는 값은 lidar/beta뿐입니다.

point_list = [
    [
        2566.571924017235, # x
        746.7817289698219, # y
        -15.269245470863748,# z
        76.5, # 빨강
        127.5, # 초록
        89.46617199365393 # 파랑
    ],
    [ 2566.592983606823, 746.6791987335685, -15.275803826279521, 76.5, 127.5, 89.45471117247024 ],
    [ 2566.616361739416, 746.4903185513501, -15.28628929674075, 76.5, 127.5, 89.41336375503832 ],
    [ 2561.706014951675, 744.5349468458361, -14.877496818222781, 76.5, 127.5, 82.21868245418283 ],
    [ 2561.5281847916694, 744.2546118233013, -14.867862032341005, 76.5, 127.5, 81.87824684536432 ],
    [ 2561.3693562897465, 744.1804761656741, -14.854129178142523, 76.5, 127.5, 81.64137897587152 ],
    [ 2561.6093071504515, 744.0287526628543, -14.882135189841177, 76.5, 127.5, 81.89871499537098 ],
    # ... 이하 동일
]

run.log({"my_first_point_cloud": wandb.Object3D.from_point_cloud(
     points = point_list,
     boxes = [{
         "corners": [
                [ 2601.2765123137915, 767.5669506323393, -17.816764802288663 ],
                [ 2599.7259021588347, 769.0082337923552, -17.816764802288663 ],
                [ 2599.7259021588347, 769.0082337923552, -19.66876480228866 ],
                [ 2601.2765123137915, 767.5669506323393, -19.66876480228866 ],
                [ 2604.8684867834395, 771.4313904894723, -17.816764802288663 ],
                [ 2603.3178766284827, 772.8726736494882, -17.816764802288663 ],
                [ 2603.3178766284827, 772.8726736494882, -19.66876480228866 ],
                [ 2604.8684867834395, 771.4313904894723, -19.66876480228866 ]
        ],
         "color": [0, 0, 255], # 바운딩 박스의 RGB 색상
         "label": "car", # 바운딩 박스에 표시되는 문자열
         "score": 0.6 # 바운딩 박스에 표시되는 숫자
     }],
     vectors = [
        {"start": [0, 0, 0], "end": [0.1, 0.2, 0.5], "color": [255, 0, 0]}, # color는 선택 사항
     ],
     point_cloud_type = "lidar/beta",
)})

포인트 클라우드를 볼 때는 Ctrl 키를 누른 채 마우스로 공간 안을 이동할 수 있습니다.

​

포인트 클라우드 파일

포인트 클라우드 데이터가 담긴 JSON 파일을 로드하려면 from_file 방법을 사용할 수 있습니다.

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

포인트 클라우드 데이터 형식의 예시는 아래와 같습니다.

{
    "boxes": [
        {
            "color": [
                0,
                255,
                0
            ],
            "score": 0.35,
            "label": "My label",
            "corners": [
                [
                    2589.695869075582,
                    760.7400443552185,
                    -18.044831294622487
                ],
                [
                    2590.719039645323,
                    762.3871153874499,
                    -18.044831294622487
                ],
                [
                    2590.719039645323,
                    762.3871153874499,
                    -19.54083129462249
                ],
                [
                    2589.695869075582,
                    760.7400443552185,
                    -19.54083129462249
                ],
                [
                    2594.9666662674313,
                    757.4657929961453,
                    -18.044831294622487
                ],
                [
                    2595.9898368371723,
                    759.1128640283766,
                    -18.044831294622487
                ],
                [
                    2595.9898368371723,
                    759.1128640283766,
                    -19.54083129462249
                ],
                [
                    2594.9666662674313,
                    757.4657929961453,
                    -19.54083129462249
                ]
            ]
        }
    ],
    "points": [
        [
            2566.571924017235,
            746.7817289698219,
            -15.269245470863748,
            76.5,
            127.5,
            89.46617199365393
        ],
        [
            2566.592983606823,
            746.6791987335685,
            -15.275803826279521,
            76.5,
            127.5,
            89.45471117247024
        ],
        [
            2566.616361739416,
            746.4903185513501,
            -15.28628929674075,
            76.5,
            127.5,
            89.41336375503832
        ]
    ],
    "type": "lidar/beta"
}

​

NumPy 배열

위에서 정의한 것과 동일한 배열 형식을 사용하면 from_numpy 방법로 numpy 배열을 직접 사용해 포인트 클라우드를 정의할 수 있습니다.

run.log({"my_cloud_from_numpy_xyz": wandb.Object3D.from_numpy(
     np.array(  
        [
            [0.4, 1, 1.3], # x, y, z
            [1, 1, 1], 
            [1.2, 1, 1.2]
        ]
    )
)})

run.log({"my_cloud_from_numpy_cat": wandb.Object3D.from_numpy(
     np.array(  
        [
            [0.4, 1, 1.3, 1], # x, y, z, category 
            [1, 1, 1, 1], 
            [1.2, 1, 1.2, 12], 
            [1.2, 1, 1.3, 12], 
            [1.2, 1, 1.4, 12], 
            [1.2, 1, 1.5, 12], 
            [1.2, 1, 1.6, 11], 
            [1.2, 1, 1.7, 11], 
        ]
    )
)})

run.log({"my_cloud_from_numpy_rgb": wandb.Object3D.from_numpy(
     np.array(  
        [
            [0.4, 1, 1.3, 255, 0, 0], # x, y, z, r, g, b 
            [1, 1, 1, 0, 255, 0], 
            [1.2, 1, 1.3, 0, 255, 255],
            [1.2, 1, 1.4, 0, 255, 255],
            [1.2, 1, 1.5, 0, 0, 255],
            [1.2, 1, 1.1, 0, 0, 255],
            [1.2, 1, 0.9, 0, 0, 255],
        ]
    )
)})

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

다음 10가지 파일 형식 중 하나로 분자 데이터를 로깅할 수 있습니다: pdb, pqr, mmcif, mcif, cif, sdf, sd, gro, mol2, 또는 mmtf.

W&B는 SMILES 문자열, rdkit mol 파일, 그리고 rdkit.Chem.rdchem.Mol 객체의 분자 데이터를 로깅하는 것도 지원합니다.

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

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"),
    }
)

run이 끝나면 UI에서 분자의 3D 시각화를 직접 조작할 수 있습니다.

AlphaFold를 사용한 라이브 예시 참조

​

PNG 이미지

wandb.Image는 기본적으로 numpy 배열이나 PILImage 인스턴스를 PNG로 변환합니다.

run.log({"example": wandb.Image(...)})
# 또는 여러 이미지
run.log({"example": [wandb.Image(...) for img in images]})

​

비디오

비디오는 wandb.Video 데이터 유형으로 로깅합니다:

run.log({"example": wandb.Video("myvideo.mp4")})

이제 미디어 브라우저에서 비디오를 볼 수 있습니다. 프로젝트 workspace, run workspace 또는 리포트로 이동한 다음 Add visualization을 클릭해 리치 미디어 패널을 추가하세요.

​

분자의 2D 뷰

wandb.Image 데이터 유형과 rdkit을 사용해 분자의 2D 뷰를 로깅할 수 있습니다:

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

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

​

기타 미디어

W&B는 여러 다른 미디어 유형을 로깅하는 것도 지원합니다.

​

오디오

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

step당 최대 100개의 오디오 클립을 로깅할 수 있습니다. 자세한 사용 정보는 audio-file을 참조하세요.

​

비디오

run.log({"video": wandb.Video(numpy_array_or_path_to_video, fps=4, format="gif")})

numpy 배열이 제공되면 차원의 순서는 time, channels, width, height라고 가정합니다. 기본적으로 4fps gif 이미지를 생성합니다(numpy 객체를 전달할 때는 ffmpeg와 moviepy Python 라이브러리가 필요합니다). 지원되는 형식은 "gif", "mp4", "webm", "ogg"입니다. wandb.Video에 문자열을 전달하면 wandb에 업로드하기 전에 파일이 존재하는지, 그리고 지원되는 형식인지 확인합니다. BytesIO 객체를 전달하면 지정한 형식을 확장자로 사용하는 임시 파일이 생성됩니다.

W&B run 및 프로젝트 페이지의 Media 섹션에서 비디오를 확인할 수 있습니다.

사용에 대한 자세한 내용은 video-file을 참조하세요.

​

텍스트

wandb.Table을 사용해 테이블에 텍스트를 로깅하면 UI에 표시할 수 있습니다. 기본 열 헤더는 ["Input", "Output", "Expected"]입니다. 원활한 UI 성능을 위해 기본 최대 행 수는 10,000으로 설정되어 있습니다. 하지만 wandb.Table.MAX_ROWS = {DESIRED_MAX}를 사용해 최대값을 명시적으로 재정의할 수 있습니다.

with wandb.init(project="my_project") as run:
    columns = ["Text", "Predicted Sentiment", "True Sentiment"]
    # 방법 1
    data = [["I love my phone", "1", "1"], ["My phone sucks", "0", "-1"]]
    table = wandb.Table(data=data, columns=columns)
    run.log({"examples": table})

    # 방법 2
    table = wandb.Table(columns=columns)
    table.add_data("I love my phone", "1", "1")
    table.add_data("My phone sucks", "0", "-1")
    run.log({"examples": table})

pandas DataFrame 객체를 전달할 수도 있습니다.

table = wandb.Table(dataframe=my_dataframe)

자세한 사용법은 string을 참조하세요.

​

HTML

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

어떤 키에든 맞춤형 HTML을 로깅하면 run 페이지에 HTML 패널이 표시됩니다. 기본적으로는 기본 스타일이 적용되며, inject=False를 전달하면 이를 비활성화할 수 있습니다.

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

자세한 사용 정보는 html-file을 참조하세요.