이미지 메타데이터

메타데이터를 사용하면 Roboflow 워크스페이스의 이미지에 사용자 지정 키-값 쌍을 첨부할 수 있습니다. 메타데이터를 사용하여 캡처 조건, 장치 식별자, 품질 점수 또는 도메인별 속성과 같은 구조화된 정보를 이미지와 함께 저장한 다음 해당 속성을 기준으로 데이터를 검색, 필터링 및 구성할 수 있습니다.

개요

각 이미지는 원하는 만큼 많은 메타데이터 항목을 가질 수 있습니다. 항목은 키 (예: camera_id)와 값 (문자열, 숫자 또는 불리언)으로 이루어집니다.

값 유형	예시
문자열	location: "warehouse-3", shift: "night"
숫자	temperature: 72.5, quality_score: 95
불리언	reviewed: true, is_night: false

사용 사례

• 캡처 컨텍스트 — 카메라 ID, GPS 좌표, 날씨, 조명 상태 기록

• 품질 추적 — 신뢰도 점수, 검토 상태, 주석자 ID 첨부

• 데이터 슬라이싱 — 원하는 속성으로 데이터셋을 필터링하여 타깃 훈련 세트 구성

• 외부 시스템 연동 — 이미지를 내부 도구와 연결하는 식별자 저장

메타데이터 추가

웹 UI, Python SDK, REST API 또는 S3 Bucket Mirror를 통해 이미지에 메타데이터를 추가할 수 있습니다.

웹 애플리케이션

1

이미지 열기

프로젝트에서 아무 이미지를 엽니다.

2

키와 값 입력

메타데이터 섹션에서 키 첫 번째 입력란에 값 두 번째 입력란에

3

추가

를 눌러 Enter 저장하거나 Add를 클릭하세요

값은 자동으로 유형별로 파싱됩니다:

입력된 값	저장된 형태
front	"front" (문자열)
95	95 (숫자)
3.14	3.14 (숫자)
true / false	true / false (불리언)

Annotation Tool의 메타데이터 편집기

Python SDK

이미지 업로드 시 metadata 사전을 전달하세요:

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace("your-workspace").project("your-project")

project.upload(
    image_path="image.jpg",
    metadata={
        "camera_id": "cam001",
        "location": "warehouse-3",
        "temperature": 72.5,
        "is_night": False
    }
)

REST API

업로드 중 메타데이터 추가

multipart form data로 이미지 업로드할 때 metadata 필드(JSON 문자열화된)를 포함하세요:

curl -X POST "https://api.roboflow.com/dataset/your-dataset/upload?api_key=YOUR_API_KEY" \
  -F "name=image.jpg" \
  -F "split=train" \
  -F "[email protected]" \
  -F 'metadata={"camera_id":"cam001","temperature":72.5}'

S3 Bucket Mirror

S3 버킷에서 이미지를 동기화할 때 Bucket Mirror 이미지와 같은 기본 이름을 가진 .json 파일을 각 이미지 옆에 배치하여 메타데이터를 첨부할 수 있습니다:

my-bucket/
  images/
    photo_001.jpg
    photo_001.json      # photo_001.jpg의 메타데이터
    photo_002.jpg
    photo_002.json      # photo_002.jpg의 메타데이터

JSON 파일은 키-값 쌍으로 메타데이터를 포함합니다:

{
    "camera_id": "cam001",
    "location": "warehouse-3",
    "capture": { "temperature": 72.5, "humidity": 45 }
}

중첩 객체는 점 표기법으로 자동 평탄화됩니다 위 예시는 다음을 생성합니다:

키	값
camera_id	"cam001"
location	"warehouse-3"
capture.temperature	72.5
capture.humidity	45

메타데이터 파일 제약사항

• 최대 파일 크기: 256 KB

• 유효한 JSON이어야 함

• null 및 undefined 값은 필터링됩니다

업데이트 전략

Bucket Mirror는 동기화된 메타데이터가 UI나 API를 통해 수동으로 설정한 메타데이터와 어떻게 상호작용할지에 대해 여러 전략을 지원합니다:

전략	동작
mergeBucketWins (기본값)	두 소스를 병합합니다. 키 충돌 시 버킷 값이 우선합니다.
mergeUserWins	두 소스를 병합합니다. 키 충돌 시 사용자 설정 값이 우선합니다.
overwrite	버킷 메타데이터가 기존의 모든 메타데이터를 완전히 대체합니다.
untilFirstChange	사용자가 메타데이터를 수동으로 편집할 때까지 버킷에서 동기화하다가, 편집이 발생하면 업데이트를 중단합니다.
append	버킷의 새 키만 추가합니다. 기존 키는 절대 덮어쓰지 않습니다.

메타데이터로 검색하기

메타데이터는 인덱싱되어 Asset Library에서 검색 가능합니다. 검색창을 사용해 메타데이터 값으로 이미지를 필터링하세요:

metadata.camera_id:"cam001"
metadata.quality_score>80
metadata.reviewed:true

메타데이터 필터를 다른 검색 필터와 결합할 수 있습니다:

metadata.location:"warehouse-3" AND class:forklift

Asset Library는 워크스페이스에 존재하는 항목을 기반으로 메타데이터 키와 값에 대한 자동완성도 제공합니다.

키 명명 규칙

메타데이터 키는 다음 규칙을 따라야 합니다:

규칙	상세
허용 문자	문자 (a-z, A-Z), 숫자 (0-9), 밑줄 (_), 점 (.)
첫 번째 문자	문자, 숫자 또는 밑줄이어야 합니다
금지된 문자	슬래시 (/)는 허용되지 않습니다

유효한 키: camera_id, capture.temperature, _internal_ref, v2_score

유효하지 않은 키: camera/id (포함) /), .starts_with_dot (점으로 시작) .), has spaces (공백 포함)

메타데이터 vs. 태그

메타데이터와 태그 는 모두 이미지를 정리하는 데 도움이 되지만, 서로 다른 목적을 제공합니다:

	태그	메타데이터
구조	단순 라벨	키-값 쌍
값	값 없음, 이름만 있음	문자열, 숫자 또는 불리언
적합한 용도	분류, 워크플로우 상태	구조화된 속성, 측정값
예시	reviewed, v2, needs-annotation	temperature: 72.5, camera_id: "cam001"

동일한 이미지에서 둘 다 사용할 수 있습니다. 예를 들어 이미지를 reviewed 로 태그하고 또한 reviewer: "alice" 및 confidence: 0.95 를 메타데이터로 저장할 수 있습니다.