---
updatedAt: 2025-09-24T00:34:05.000Z
agentTools:
  projectIndex: https://annofab.readme.io/llms.txt
---

# 3次元プロジェクトのアノテーションJSON

3次元プロジェクトのアノテーションのフォーマットについて記載します。

# `details[].data`

## バウンディングボックス

`data`には、「バウンディングボックスを表すJSON」をダンプした文字列が可能されています。

```json
{
    "data": "{\"kind\":\"CUBOID\",\"shape\":{\"dimensions\":{\"width\":2.3923352451056736,\"height\":1.5576410740613937,\"depth\":5.159757984979564},\"location\":{\"x\":-0.31926004953130416,\"y\":13.089790351791807,\"z\":0.7149539962410927},\"rotation\":{\"x\":0,\"y\":0,\"z\":4.71238898038469},\"direction\":{\"front\":{\"x\":-2.220446049250313e-16,\"y\":-1,\"z\":0},\"up\":{\"x\":0,\"y\":0,\"z\":1}}},\"version\":\"2\"}",
    "_type": "Unknown"
}

```

以下は`data`キーの値をデコードしたJSONです。

```json
{
    "kind": "CUBOID",
    "shape": {
        "dimensions": {
            "width": 2.3923352451056736,
            "height": 1.5576410740613937,
            "depth": 5.159757984979564
        },
        "location": {
            "x": -0.31926004953130416,
            "y": 13.089790351791807,
            "z": 0.7149539962410927
        },
        "rotation": {
            "x": 0,
            "y": 0,
            "z": 4.71238898038469
        },
        "direction": {
            "front": {
                "x": -2.220446049250313e-16,
                "y": -1,
                "z": 0
            },
            "up": {
                "x": 0,
                "y": 0,
                "z": 1
            }
        }
    },
    "version": "2"
}
```

`shape`キーにバウンディングボックスの情報が格納されています。各項目について簡単に説明します。詳細は[CuboidLabelObjectDataV2](https://d2rljy8mjgrfyd.cloudfront.net/3d-editor-latest/annotation-data-doc/schema-doc.html#tab-pane_anyOf_i1)を参照してください。

* `dimensions`：バウンディングボックスのサイズ（幅、高さ、奥行き）
  * `width`：バウンディングボックスのローカル座標系のY軸方向の長さ
  * `height`：バウンディングボックスのローカル座標系のZ軸方向の長さ
  * `depth`：バウンディングボックスのローカル座標系のX軸方向の長さ
* `location`：バウンディングボックスの中心の位置
* `rotation`：バウンディングボックスの回転。z-x-y系のオイラー角（単位はラジアン）
* `direction`：バウンディングボックスの前側と上側の向き（`rotation`から算出できる情報）
  * `front`：バウンディングボックスの前方向を表すベクトル。`[1, 0, 0]`のベクトルを、`rotation`によって回転させた結果
  * `up`：バウンディングボックスの上方向を表すベクトル。`[0, 0, 1]`のベクトルを、`rotation`によって回転させた結果

## インスタンスセグメント

セグメントに含まれる点の情報は、アノテーションJSONファイルとは別のJSONファイル（セグメントJSONファイル）に格納されます。`data`には、セグメントJSONファイルのパス（アノテーションJSONファイルからの相対パス）が格納されます。

```json
{
    "data": "./002-0/01GGFH564X1M48ZNP3QDBRQPE9",
    "_type": "Unknown"
}
```

<br />

details`キー配下を確認してください。3次元アノテーションは、アノテーションの種類に関わらず`data.\_type`は`Unknown`です。`data.data\`の中身は、アノテーションの種類によって変わります。

* インスタンスセグメント/セマンティックセグメント：セグメント情報が格納されたファイルへのパス
* バウンディングボックス：バウンディングボックスの情報が記載されたJSON文字列

## セグメント情報が格納されたファイル

`002/002-0/`フォルダ配下のファイルを、エディタで開いてください。`points`キーは、セグメントに含まれている点の情報です。番号は、アノテーション対象の点群の0始まりのインデックスを表しています。データ構造の詳細は[SegmentLabelObjectDataV1](https://d2rljy8mjgrfyd.cloudfront.net/3d-editor-latest/annotation-data-doc/schema-doc.html#tab-pane_anyOf_i2)を参照してください。

以下は、セグメントJSONファイルの中身です。`points`には、セグメントに含まれている点の0始まりのインデックスが格納されます。

```javascript 002/002-0/01GGFYK59KA131WZ9K2SRMSVRQ
{
    "kind": "SEGMENT",
    "points": [
        130439,
        130442,
        ...,
    ],
    "version": "1"
}   
```

<br />

# 補足

# SDKでアノテーションZIPを読み込む

[annofabapi-3dpc-extensions](https://github.com/kurusugawa-computer/annofabapi-3dpc-extensions)という[annofab-api-python-client](https://github.com/kurusugawa-computer/annofabapi-3dpc-extensions)の拡張ライブラリを利用すると、3次元アノテーションに対応したデータクラスを利用できます。また、オイラー角からクォータニオンに変換する関数など、座標変換用の関数も利用できます。

```python
from annofabapi.parser import SimpleAnnotationZipParser

from annofab_3dpc.annotation import convert_annotation_detail_data


with zipfile.ZipFile("annotation.zip", "r") as zip_file:
    parser = SimpleAnnotationZipParser(zip_file, "002/002-0.json")
    
    result = parser.parse(convert_annotation_detail_data)

    car_annotation_data = result.details[3].data
    print(type(car_annotation_data))
    # => CuboidAnnotationDetailDataV2

    # バウンディングボックスのサイズを出力
    print(car_annotation_data.shape.dimensions)
		# => Size(width=2.3923352451056736, height=1.5576410740613937, depth=5.159757984979564)

    # バウンディングボックスの回転のクォータニオンを出力
    print(car_annotation_data.shape.rotation.to_quaternion())
		# => [-0.7071067811865475, 0.0, -0.0, 0.7071067811865476]

    
```