# Image Metadata

Metadataを使用すると、Roboflow workspace内の画像にカスタムのキーと値のペアを追加できます。Metadataを使って、撮影条件、デバイス識別子、品質スコア、その他ドメイン固有の属性など、構造化された情報を画像と一緒に保存し、それらの属性を基準にデータを検索、フィルタリング、整理できます。

## 概要

各画像には、任意の数のmetadataエントリを保持できます。1つのエントリは **key** （次のような名前 `camera_id`）と **value** （文字列、数値、またはboolean）を組み合わせたものです。

| 値の型     | 例                                           |
| ------- | ------------------------------------------- |
| 文字列     | `location: "warehouse-3"`, `shift: "night"` |
| 数値      | `temperature: 72.5`, `quality_score: 95`    |
| boolean | `reviewed: true`, `is_night: false`         |

### ユースケース

* **撮影コンテキスト** — camera ID、GPS座標、天候、照明条件を記録
* **品質トラッキング** — confidenceスコア、レビュー状態、アノテーターIDを付与
* **データの切り出し** — 任意の属性でデータセットをフィルタリングして、対象を絞った学習セットを作成
* **外部システム連携** — 画像を社内ツールに関連付ける識別子を保存

## Metadataの追加

Web UI、Python SDK、REST API、またはS3 Bucket Mirror経由で自動的に、画像にmetadataを追加できます。

### Web Application

{% stepper %}
{% step %}

#### 画像を開く

project内の任意の画像を開きます。
{% endstep %}

{% step %}

#### keyとvalueを入力

metadataセクションで、最初の入力欄に **key** を、2つ目の入力欄に **value** を入力します。
{% endstep %}

{% step %}

#### 追加

を押す **Enter** で保存するか、Addをクリックします
{% endstep %}
{% endstepper %}

値は型に基づいて自動的に解析されます:

| 入力された値           | 保存形式                       |
| ---------------- | -------------------------- |
| `front`          | `"front"` （文字列）            |
| `95`             | `95` （数値）                  |
| `3.14`           | `3.14` （数値）                |
| `true` / `false` | `true` / `false` （boolean） |

<figure><img src="/files/9e32629a005dc64e4665ccb8fecc587ed638ae30" alt=""><figcaption><p>Annotation Toolのmetadata editor</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

#### アップロード時にmetadataを追加

画像をアップロードするときに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を使用して [Bucket Mirror](/roboflow/roboflow-jp/datasets/adding-data/upload-data-from-aws-gcp-and-azure/aws-s3-bucket.md) でS3 bucketから画像を同期する場合、各画像と同じベース名を持つ `.json` ファイルを隣に置くことでmetadataを付与できます:

```
my-bucket/
  images/
    photo_001.jpg
    photo_001.json      # photo_001.jpg のmetadata
    photo_002.jpg
    photo_002.json      # photo_002.jpg のmetadata
```

JSONファイルには、key-valueペアとしてmetadataが含まれます:

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

**ネストされたオブジェクトは自動的にフラット化されます** ドット表記を使って処理されます。上の例では次のようになります:

| Key                   | Value           |
| --------------------- | --------------- |
| `camera_id`           | `"cam001"`      |
| `location`            | `"warehouse-3"` |
| `capture.temperature` | `72.5`          |
| `capture.humidity`    | `45`            |

#### metadataファイルの制約

* 最大ファイルサイズ: **256 KB**
* 有効なJSONである必要があります
* `null` および `undefined` の値は除外されます

#### 更新戦略

Bucket Mirrorは、同期されたmetadataがUIまたはAPIで手動設定したmetadataとどのように連携するかについて、いくつかの戦略をサポートしています:

| 戦略                            | 動作                                               |
| ----------------------------- | ------------------------------------------------ |
| **`mergeBucketWins`** （デフォルト） | 両方のソースをマージします。keyが競合した場合はbucket側の値が優先されます。       |
| **`mergeUserWins`**           | 両方のソースをマージします。keyが競合した場合はユーザー設定の値が優先されます。        |
| **`overwrite`**               | bucketのmetadataが既存のmetadataを完全に置き換えます。           |
| **`untilFirstChange`**        | ユーザーがmetadataを手動で編集するまでbucketから同期し、その後は更新を停止します。 |
| **`append`**                  | bucketから新しいkeyのみを追加します。既存のkeyは上書きしません。           |

## Metadataによる検索

metadataは [Asset Library](/roboflow/roboflow-jp/workspaces/asset-library.md)でインデックス化され、検索可能です。検索バーを使ってmetadata値で画像を絞り込めます:

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

metadataフィルターは他の検索フィルターと組み合わせることができます:

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

Asset Libraryでは、workspace内に存在する内容に基づいてmetadataのkeyとvalueのオートコンプリートも提供されます。

## key命名規則

metadataのkeyは次の規則に従う必要があります:

| 規則      | 詳細                                               |
| ------- | ------------------------------------------------ |
| 許可される文字 | 英字（`a-z`, `A-Z`）、数字（`0-9`）、アンダースコア（`_`）、ドット（`.`) |
| 最初の文字   | 英字、数字、またはアンダースコアである必要があります                       |
| 禁止される文字 | スラッシュ（`/`）は使用できません                               |

有効なkey: `camera_id`, `capture.temperature`, `_internal_ref`, `v2_score`

無効なkey: `camera/id` （含まれる） `/`), `.starts_with_dot` （で始まる） `.`), `has spaces` （スペースを含む）

## MetadataとTags

metadataと [tags](/roboflow/roboflow-jp/datasets/manage-datasets/add-tags-to-images.md) のどちらも画像の整理に役立ちますが、用途は異なります:

|           | Tags                                 | Metadata                                   |
| --------- | ------------------------------------ | ------------------------------------------ |
| **構造**    | 単純なラベル                               | key-valueペア                                |
| **値**     | 値はなく、名前のみ                            | 文字列、数値、またはboolean                          |
| **最適な用途** | 分類、ワークフローの状態                         | 構造化属性、測定値                                  |
| **例**     | `reviewed`, `v2`, `needs-annotation` | `temperature: 72.5`, `camera_id: "cam001"` |

同じ画像に両方を使えます。たとえば、画像に `reviewed` というtagを付け、さらに `reviewer: "alice"` および `confidence: 0.95` をmetadataとして保存できます。


---

# 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-jp/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.