# 이미지 메타데이터

메타데이터를 사용하면 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를 사용해 자동으로 이미지에 메타데이터를 추가할 수 있습니다.

### 웹 애플리케이션

{% stepper %}
{% step %}

#### 이미지 열기

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

{% step %}

#### key와 value 입력

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

{% step %}

#### 추가

을 눌러 **Enter** 를 저장하거나 Add를 클릭하세요
{% endstep %}
{% endstepper %}

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

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

<figure><img src="/files/869ff44bf69b5b78ddff4570c48984fb07f6df24" 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](/roboflow/roboflow-ko/datasets/adding-data/upload-data-from-aws-gcp-and-azure/aws-s3-bucket.md) 를 사용해 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 }
}
```

**중첩된 객체는 자동으로 평면화됩니다** dot notation을 사용하여. 위 예시는 다음을 생성합니다:

| Key                   | Value           |
| --------------------- | --------------- |
| `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](/roboflow/roboflow-ko/workspaces/asset-library.md)에서 인덱싱되며 검색할 수 있습니다. 검색창을 사용해 메타데이터 값으로 이미지를 필터링하세요:

```
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` (으로 시작함 `.`), `공백 포함` (공백 포함)

## 메타데이터 vs. Tags

메타데이터와 [tags](/roboflow/roboflow-ko/datasets/manage-datasets/add-tags-to-images.md) 모두 이미지를 정리하는 데 도움이 되지만, 용도는 다릅니다:

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/roboflow/roboflow-ko/datasets/adding-data/image-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.