# 이미지 메타데이터

메타데이터를 사용하면 Roboflow workspace의 이미지에 사용자 지정 key-value 쌍을 첨부할 수 있습니다. 메타데이터를 사용해 촬영 조건, 디바이스 식별자, 품질 점수 또는 도메인별 속성 등과 같은 구조화된 정보를 이미지와 함께 저장한 다음, 이러한 속성을 기준으로 데이터를 검색, 필터링, 정리할 수 있습니다.

## 개요

각 이미지는 원하는 개수의 메타데이터 항목을 담을 수 있습니다. 각 항목은 **key** (예를 들어 `camera_id`와 같은 이름)와 **value** (문자열, 숫자 또는 불리언)의 쌍입니다.

| 값 유형 | 예시                                          |
| ---- | ------------------------------------------- |
| 문자열  | `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를 사용해 자동으로 이미지에 메타데이터를 추가할 수 있습니다.

### Web Application

{% stepper %}
{% step %}

#### 이미지 열기

프로젝트의 아무 이미지나 엽니다.
{% endstep %}

{% step %}

#### key와 value 입력

메타데이터 섹션에서 **key** 을 첫 번째 입력란에, **value** 을 두 번째 입력란에 입력합니다.
{% endstep %}

{% step %}

#### 추가

을 누르거나 Add를 클릭하여 저장 **Enter** 합니다.
{% endstep %}
{% endstepper %}

값은 유형에 따라 자동으로 파싱됩니다:

| 입력한 값            | 저장 형식                  |
| ---------------- | ---------------------- |
| `front`          | `"front"` (문자열)        |
| `95`             | `95` (숫자)              |
| `3.14`           | `3.14` (숫자)            |
| `true` / `false` | `true` / `false` (불리언) |

<figure><img src="https://3958014485-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M6S9nPJhEX9FYH6clfW%2Fuploads%2Fh7L2L0c22TIzCxjxuiU1%2Fimage.png?alt=media&#x26;token=3f3eba92-e194-43b4-bd98-801a038836ff" alt=""><figcaption><p>Annotation Tool의 메타데이터 편집기</p></figcaption></figure>

### Python SDK

이미지를 업로드할 때 `metadata` 사전을 전달하세요:

```python
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 문자열화됨)를 포함하세요:

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

### S3 Bucket Mirror

를 사용할 때 [Bucket Mirror](https://docs.roboflow.com/roboflow/roboflow-ko/datasets/adding-data/broken-reference) 를 사용해 S3 bucket의 이미지를 동기화할 경우, 각 이미지와 같은 기본 이름을 가진 `.json` 파일을 함께 배치하여 메타데이터를 첨부할 수 있습니다:

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

JSON 파일에는 메타데이터가 key-value 쌍으로 들어 있습니다:

```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`** (기본값) | 두 소스를 병합합니다. key 충돌 시 bucket 값이 우선합니다.                   |
| **`mergeUserWins`**         | 두 소스를 병합합니다. key 충돌 시 사용자가 설정한 값이 우선합니다.                 |
| **`overwrite`**             | Bucket 메타데이터가 기존 메타데이터를 완전히 대체합니다.                       |
| **`untilFirstChange`**      | 사용자가 메타데이터를 수동으로 수정할 때까지 bucket에서 동기화하고, 이후 업데이트를 중지합니다. |
| **`append`**                | bucket에서 새 key만 추가합니다. 기존 key는 절대 덮어쓰지 않습니다.             |

## 메타데이터로 검색

메타데이터는 [Asset Library](https://docs.roboflow.com/roboflow/roboflow-ko/datasets/adding-data/broken-reference)에서 인덱싱되며 검색 가능합니다. 검색창을 사용해 메타데이터 값으로 이미지를 필터링하세요:

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

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

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

Asset Library는 workspace에 존재하는 항목을 기반으로 메타데이터 key와 value에 대한 자동완성도 제공합니다.

## key 명명 규칙

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

| 규칙      | 세부 사항                                        |
| ------- | -------------------------------------------- |
| 허용 문자   | 문자(`a-z`, `A-Z`), 숫자(`0-9`), 밑줄(`_`), 점(`.`) |
| 첫 번째 문자 | 문자, 숫자 또는 밑줄이어야 함                            |
| 금지 문자   | 슬래시(`/`)는 허용되지 않음                            |

유효한 key: `camera_id`, `capture.temperature`, `_internal_ref`, `v2_score`

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

## 메타데이터 vs. Tags

메타데이터와 [tags](https://docs.roboflow.com/roboflow/roboflow-ko/datasets/adding-data/broken-reference) 모두 이미지를 정리하는 데 도움이 되지만, 용도는 다릅니다:

|               | Tags                                 | 메타데이터                                      |
| ------------- | ------------------------------------ | ------------------------------------------ |
| **구조**        | 단순 레이블                               | key-value 쌍                                |
| **값**         | 값 없음, 이름만 있음                         | 문자열, 숫자 또는 불리언                             |
| **가장 적합한 용도** | 분류, 워크플로 상태                          | 구조화된 속성, 측정값                               |
| **예시**        | `reviewed`, `v2`, `needs-annotation` | `temperature: 72.5`, `camera_id: "cam001"` |

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