EasyAR Mega Annotation 形式 0.5

このドキュメントは EMA 0.5 の形式仕様を定義します。

開始する前に

EasyAR Mega Annotation 形式の概要を読み、EMA の用途と適用シーンを確認してください。

このドキュメントでは、「producer」は EMA データを生成するプログラム、「consumer」は EMA データを読み取るプログラムを指します。

形式の規約

EMA ファイルは UTF-8 エンコーディングを使用し、RFC 8259 で定義された JSON 構文に従います。
同じオブジェクト内のフィールド名は重複できません。
フィールド名は大文字と小文字を区別します。このドキュメントで定義するフィールド名は、表と例に示す形式を使用する必要があります。
必須フィールドは存在し、表で定義された型を使用する必要があります。任意フィールドは値がない場合に省略できます。
UUID はハイフン付き文字列として記述します。例: 123e4567-e89b-12d3-a456-426614174000。
タイムスタンプは UTC 日時文字列を使用し、形式は YYYY-MM-DDThh:mm:ssZ、秒単位の精度です。例: 2026-08-12T00:00:00Z。この形式は W3C Date and Time Formats で定義された UTC 表現に従います。
座標変換は右手系 OpenGL 座標系を使用します。+X は右、+Y は上、+Z は後方を指します。

ドキュメント構造

EMA ドキュメントのルートオブジェクトには、形式バージョン、生成元、拡張宣言、Mega Block リスト、アノテーションリストが含まれます。

EMA ルートオブジェクト構造の例:

{
  "version": "0.5.0",
  "generatedBy": "EasyAR Mega Support 2.14.0",
  "blocks": [],
  "annotations": [],
  "extensions": []
}

フィールド	型	必須	説明
`version`	string	はい	EMA 形式バージョン。0.5 ドキュメントは `0.5.0` と記述します。
`generatedBy`	string	はい	ドキュメントを生成したツールまたは主体の情報。通常は製品名とバージョンを含みます。
`blocks`	array<Block>	はい	ドキュメントが参照する Mega Block。空配列にできます。
`annotations`	array<Annotation>	はい	アノテーションオブジェクト。空配列にできます。
`extensions`	array<string>	いいえ	ドキュメントが使用する拡張宣言。拡張を参照してください。

Block

Block は EMA ドキュメントが参照する Mega Block とその座標情報を表します。

フィールド	型	必須	説明
`id`	UUID string	はい	Mega Block の一意識別子。EasyAR Mega サービスが返す値を使用する必要があります。
`timestamp`	date-time string	はい	Mega Block の最終変更時刻。EasyAR Mega サービスが返す値を使用する必要があります。形式の規約を参照してください。
`location`	Location	いいえ	Mega Block 原点の WGS 84 地理位置。
`transform`	Transform	はい	EMA シーンのルート座標系に対する Mega Block の変換。
`keepTransform`	boolean	はい	ドキュメントに記録された `transform` を保持して適用するかどうか。`true` は手動調整後の変換を保持することを意味します。

Mega Block の例:

{
  "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
  "timestamp": "2026-08-12T00:00:00Z",
  "location": {
    "latitude": 31.2304,
    "longitude": 121.4737,
    "altitude": 5.5
  },
  "transform": {
    "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
    "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
    "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }
  },
  "keepTransform": true
}

Annotation

Annotation は EMA ドキュメント内のアノテーションを表します。

フィールド	型	必須	説明
`type`	string	はい	アノテーションタイプ。値は `node` または `relationship` です。
`id`	UUID string	はい	アノテーションの一意識別子。`annotations` 内の ID は一意である必要があります。
`timestamp`	date-time string	はい	アノテーションの最終変更時刻。形式の規約を参照してください。
`featureType`	string	いいえ	アノテーションが属する機能タイプ。
`properties`	object	いいえ	アノテーションプロパティと拡張データ。

Node

Node は空間位置を持つアノテーションを表します。

フィールド	型	必須	説明
`type`	string	はい	`node` に固定。
`geometry`	string	はい	ジオメトリタイプ。値は `point` または `cube` です。
`parent`	Parent	はい	`node` アノテーションの参照座標系。Mega Block または WGS 84 地理位置を参照できます。後者の製品サポートについては WorldParent を参照してください。
`transform`	Transform	はい	参照座標系に対する `node` アノテーションの変換。含まれるフィールドは `geometry` によって決まります。

geometry が point の場合は位置点を表します。cube の場合は原点を中心とする箱状領域を表します。各ジオメトリでの transform 要件は Transform を参照してください。

点アノテーションの例:

{
  "type": "node",
  "id": "b62fd4b5-66aa-4418-a603-69ae6faedbe6",
  "timestamp": "2026-08-12T00:00:01Z",
  "geometry": "point",
  "parent": {
    "type": "block",
    "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
    "timestamp": "2026-08-12T00:00:00Z"
  },
  "transform": {
    "position": { "x": 1.0, "y": 2.0, "z": 3.0 }
  },
  "properties": {
    "name": "Entrance"
  }
}

ボックス領域アノテーションの例:

{
  "type": "node",
  "id": "76c0e24a-a01a-4a50-9246-e7d827c96b38",
  "timestamp": "2026-08-12T00:00:02Z",
  "geometry": "cube",
  "parent": {
    "type": "block",
    "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
    "timestamp": "2026-08-12T00:00:00Z"
  },
  "transform": {
    "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
    "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
    "scale": { "x": 0.5, "y": 1.75, "z": 0.5 }
  }
}

Relationship

Relationship はアノテーション間の関係を表し、複数のアノテーションを 1 つの集合として整理するためにも使用できます。

フィールド	型	必須	説明
`type`	string	はい	`relationship` に固定。
`members`	array<UUID string>	はい	メンバーアノテーション ID を順番に記録します。メンバーは `node` または `relationship` アノテーションを参照できます。

リレーションシップアノテーションの例:

{
  "type": "relationship",
  "id": "b7cf28e4-041e-460e-81cf-a0591c09faee",
  "timestamp": "2026-08-12T00:00:03Z",
  "members": [
    "b62fd4b5-66aa-4418-a603-69ae6faedbe6",
    "76c0e24a-a01a-4a50-9246-e7d827c96b38"
  ],
  "properties": {
    "name": "Annotation Group",
    "isDirected": false
  }
}

Parent

Parent は Node が依存する参照座標系を表し、Node の空間変換を解釈する基準を決定します。

BlockParent

BlockParent は Mega Block を基準とする参照座標系を表します。

フィールド	型	必須	説明
`type`	string	はい	`block` に固定。
`id`	UUID string	はい	参照される Mega Block の ID。この ID はルートオブジェクトの `blocks` 内に存在する必要があります。
`timestamp`	date-time string	はい	アノテーションの作成または更新時に参照された Mega Block の変更時刻。形式の規約を参照してください。

WorldParent

WorldParent は WGS 84 地理位置を原点とするワールド参照座標系を表します。

フィールド	型	必須	説明
`type`	string	はい	`world` に固定。
`location`	Location	はい	`node` アノテーションの参照座標系原点の WGS 84 地理位置。

警告

EMA 0.5 は parent.type が world の構造を定義しますが、EasyAR Mega Studio 2.13 および EasyAR Sense Unity Plugin 4003 より後のバージョンでは関連機能が削除されています。この形式定義は、これらの製品バージョンが WorldParent の使用をサポートすることを意味しません。

座標と基本型

Location

Location は WGS 84 地理位置を表します。

フィールド	型	必須	説明
`latitude`	number	はい	緯度。10 進度で表される 64 ビット浮動小数点数。
`longitude`	number	はい	経度。10 進度で表される 64 ビット浮動小数点数。
`altitude`	number	はい	高度。メートル単位の 64 ビット浮動小数点数。

Transform

Transform は参照座標系に対するオブジェクトの空間変換を表します。

フィールド	型	必須	説明
`position`	Vector3F	はい	参照座標系に対する位置。
`rotation`	Vector4F	条件付き	参照座標系に対する回転。
`scale`	Vector3F	条件付き	参照座標系に対するスケール。

各フィールドの使用場面ごとの要件は次のとおりです:

使用場面	`position`	`rotation`	`scale`
Mega Block	必須	必須	必須
`geometry` が `point` のアノテーション	必須	省略	省略
`geometry` が `cube` のアノテーション	必須	必須	必須

Vector3F

Vector3F は位置とスケールを記録する 3 次元ベクトルを表します。

フィールド	型	必須	説明
`x`	number	はい	x 軸成分。32 ビット浮動小数点数。
`y`	number	はい	y 軸成分。32 ビット浮動小数点数。
`z`	number	はい	z 軸成分。32 ビット浮動小数点数。

Vector4F

Vector4F は回転を記録する四元数を表します。

フィールド	型	必須	説明
`x`	number	はい	四元数の x 成分。32 ビット浮動小数点数。
`y`	number	はい	四元数の y 成分。32 ビット浮動小数点数。
`z`	number	はい	四元数の z 成分。32 ビット浮動小数点数。
`w`	number	はい	四元数の w 成分。32 ビット浮動小数点数。

プロパティ

properties はアノテーションの共通プロパティ、機能プロパティ、拡張データを保存します。このフィールドはキー値オブジェクトで、値には任意の JSON 値を使用できます。

EMA 0.5 は次の共通プロパティを定義します:

プロパティ	適用対象	型	必須	説明
`name`	`node`, `relationship`	string	いいえ	アノテーションの表示名。
`isDirected`	`relationship`	boolean	いいえ	リレーションシップが有向かどうか。指定しない場合は `true` です。
`category`	`relationship`	string	いいえ	リレーションシップカテゴリ。

機能タイプ

featureType はアノテーションが参加する機能タイプを指定します。各機能タイプは、関連アノテーションの構造、関係、専用プロパティを定義します。

ナビゲーション点グラフ

ナビゲーション点グラフは、空間内のナビゲーション点、ナビゲーション点を接続する経路、およびそれらで構成されるネットワークを表します。経路と接続関係を表現できます。ナビゲーション点グラフを構成するすべてのアノテーションは featureType を navPointGraph に設定します。

ナビゲーション点グラフは 3 種類のアノテーションで構成されます:

オブジェクト	構造要件
ナビゲーション点	`type` は `node`、`geometry` は `point` です。
経路	`type` は `relationship`、`members` は 2 つのナビゲーション点を順番に参照します。
ネットワーク	`type` は `relationship`、`members` はネットワークに含まれるナビゲーション点と経路を参照します。

ナビゲーション点グラフ内のリレーションシップアノテーションは、次の properties プロパティを使用します:

プロパティ	適用対象	型	必須	説明
`category`	経路、ネットワーク	string	はい	リレーションシップタイプを区別します。経路は `route`、ネットワークは `network` です。
`isDirected`	経路	boolean	いいえ	`true` は `members` 内の最初のナビゲーション点から 2 番目への方向を意味し、`false` は無向を意味します。
`weight`	経路	number	いいえ	経路重み。32 ビット浮動小数点数。具体的な意味はナビゲーション点グラフを使用するアプリケーションが定義します。

ナビゲーション点グラフアノテーションの例:

[
  {
    "type": "node",
    "id": "25634f2e-c42d-4163-84c4-86757e8f6e8f",
    "timestamp": "2026-08-12T00:00:00Z",
    "featureType": "navPointGraph",
    "geometry": "point",
    "parent": {
      "type": "block",
      "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
      "timestamp": "2026-08-12T00:00:00Z"
    },
    "transform": {
      "position": { "x": 0.0, "y": 0.0, "z": 0.0 }
    }
  },
  {
    "type": "node",
    "id": "fa144e57-c388-4673-a940-9a3f904247c5",
    "timestamp": "2026-08-12T00:00:01Z",
    "featureType": "navPointGraph",
    "geometry": "point",
    "parent": {
      "type": "block",
      "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
      "timestamp": "2026-08-12T00:00:00Z"
    },
    "transform": {
      "position": { "x": 0.0, "y": 0.0, "z": 0.0 }
    }
  },
  {
    "type": "relationship",
    "id": "455427a3-b68d-4237-a78f-22213de89dc8",
    "timestamp": "2026-08-12T00:00:02Z",
    "featureType": "navPointGraph",
    "members": [
      "25634f2e-c42d-4163-84c4-86757e8f6e8f",
      "fa144e57-c388-4673-a940-9a3f904247c5"
    ],
    "properties": {
      "category": "route",
      "isDirected": true,
      "weight": 1.0
    }
  },
  {
    "type": "relationship",
    "id": "b579c5fe-e574-410b-853f-77c985966d0f",
    "timestamp": "2026-08-12T00:00:03Z",
    "featureType": "navPointGraph",
    "members": [
      "25634f2e-c42d-4163-84c4-86757e8f6e8f",
      "fa144e57-c388-4673-a940-9a3f904247c5",
      "455427a3-b68d-4237-a78f-22213de89dc8"
    ],
    "properties": {
      "category": "network"
    }
  }
]

拡張

拡張は、EMA 0.5 のコア構造を変更せずにアノテーションへカスタムデータを追加するために使用します。

ルートオブジェクトの extensions 配列は、ドキュメントが使用する拡張を宣言します。各項目は次の形式を使用します:

PROVIDER:NAME#MAJOR.MINOR.PATCH

PROVIDER は拡張提供者名です。
NAME は拡張名です。
バージョンは 3 つの非負整数で構成されます。
PROVIDER と NAME に : または # を含めることはできません。
同じ PROVIDER:NAME は extensions 内で 1 回だけ宣言します。

拡張データはアノテーションの properties に保存し、プロパティ名は PROVIDER:NAME、バージョン番号は含めません。拡張値には任意の JSON 値を使用できます。後でフィールドを追加できるように JSON オブジェクトを推奨します。

拡張宣言とデータの例:

{
  "version": "0.5.0",
  "generatedBy": "Sample Producer 1.0.0",
  "extensions": [
    "SampleCompany:SampleExtension#1.0.0"
  ],
  "blocks": [],
  "annotations": [
    {
      "type": "relationship",
      "id": "15da6815-174a-4963-ac27-6dc97f324474",
      "timestamp": "2026-08-12T00:00:04Z",
      "members": [],
      "properties": {
        "SampleCompany:SampleExtension": {
          "label": "sample",
          "priority": 10
        }
      }
    }
  ]
}

一貫性要件

producer は次を保証する必要があります:

Mega Block ID とアノテーション ID はそれぞれのコレクション内で一意です。
parent.type が block の場合、parent.id は blocks 内の既存 Mega Block を参照します。
type が relationship の場合、members 内の ID は annotations 内の既存アノテーションを参照します。
properties で使用する拡張プロパティは、extensions に対応する宣言を持ちます。

consumer は認識できない通常フィールドを無視できます。認識できない type、parent.type、geometry は未サポートデータとして扱う必要があります。

完全な例

拡張データを含む完全な EMA ドキュメントの例:

{
  "version": "0.5.0",
  "generatedBy": "EasyAR Mega Support 2.14.0",
  "extensions": [
    "SampleCompany:SampleExtension#1.0.0"
  ],
  "blocks": [
    {
      "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
      "timestamp": "2026-08-12T00:00:00Z",
      "location": {
        "latitude": 31.2304,
        "longitude": 121.4737,
        "altitude": 5.5
      },
      "transform": {
        "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
        "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
        "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }
      },
      "keepTransform": true
    }
  ],
  "annotations": [
    {
      "type": "node",
      "id": "b62fd4b5-66aa-4418-a603-69ae6faedbe6",
      "timestamp": "2026-08-12T00:00:01Z",
      "geometry": "point",
      "parent": {
        "type": "block",
        "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
        "timestamp": "2026-08-12T00:00:00Z"
      },
      "transform": {
        "position": { "x": 1.0, "y": 2.0, "z": 3.0 }
      },
      "properties": {
        "name": "Entrance",
        "SampleCompany:SampleExtension": {
          "label": "sample",
          "priority": 10
        }
      }
    },
    {
      "type": "node",
      "id": "76c0e24a-a01a-4a50-9246-e7d827c96b38",
      "timestamp": "2026-08-12T00:00:02Z",
      "geometry": "cube",
      "parent": {
        "type": "block",
        "id": "37f11da4-84c0-4fd1-839f-0d86a43cce21",
        "timestamp": "2026-08-12T00:00:00Z"
      },
      "transform": {
        "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
        "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
        "scale": { "x": 0.5, "y": 1.75, "z": 0.5 }
      },
      "properties": {
        "name": "Display Area"
      }
    },
    {
      "type": "relationship",
      "id": "b7cf28e4-041e-460e-81cf-a0591c09faee",
      "timestamp": "2026-08-12T00:00:03Z",
      "members": [
        "b62fd4b5-66aa-4418-a603-69ae6faedbe6",
        "76c0e24a-a01a-4a50-9246-e7d827c96b38"
      ],
      "properties": {
        "name": "Tour Area",
        "isDirected": false
      }
    }
  ]
}

Table of Contents