EasyAR Mega Annotation 格式 0.5

本文定義 EMA 0.5 的格式規範。

開始之前

閱讀 EasyAR Mega Annotation 格式簡介瞭解 EMA 的用途和適用場景。

本文中的“生產者”指生成 EMA 數據的程序，“消費者”指讀取 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 日期與時間格式定義的 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	是	Mega Block 相對於 EMA 場景根座標系的變換。
`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 表示標註之間的關係，也可以用於將多個標註組織爲一個集合。

字段	類型	必填	說明
`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	是	緯度，爲 64 位浮點數，以十進制度表示。
`longitude`	number	是	經度，爲 64 位浮點數，以十進制度表示。
`altitude`	number	是	海拔高度，爲 64 位浮點數，單位爲米。

Transform

Transform 表示對象相對於參考座標系的空間變換。

字段	類型	必填	說明
`position`	Vector3F	是	相對於參考座標系的位置。
`rotation`	Vector4F	條件	相對於參考座標系的旋轉。
`scale`	Vector3F	條件	相對於參考座標系的縮放。

各字段在不同使用場景中的要求如下：

使用場景	`position`	`rotation`	`scale`
Mega Block	必填	必填	必填
`geometry` 爲 `point` 的標註	必填	省略	省略
`geometry` 爲 `cube` 的標註	必填	必填	必填

Vector3F

Vector3F 表示用於記錄位置和縮放的三維向量。

字段	類型	必填	說明
`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

properties 用於保存標註的通用屬性、功能屬性和擴展數據。該字段是鍵值對象，值可以是任意 JSON 值。

EMA 0.5 定義以下通用屬性：

屬性	適用對象	類型	必填	說明
`name`	`node`、`relationship`	string	否	標註的顯示名稱。
`isDirected`	`relationship`	boolean	否	關係是否有方向。未指定時爲 `true`。
`category`	`relationship`	string	否	關係類別。

功能類型

featureType 指定標註參與的功能類型。每種功能類型定義相關標註的結構、關係和專屬屬性。

導航點圖

導航點圖表示空間中的導航點、連接導航點的路徑，以及由它們組成的網絡，可用於表達路線和連通關係。組成導航點圖的標註均將 featureType 設爲 navPointGraph。

導航點圖由三類標註組成：

對象	結構要求
導航點	`type` 爲 `node`，`geometry` 爲 `point`。
路徑	`type` 爲 `relationship`，`members` 按順序引用兩個導航點。
網絡	`type` 爲 `relationship`，`members` 引用網絡包含的導航點和路徑。

導航點圖中的關係標註使用以下 properties 屬性：

屬性	適用對象	類型	必填	說明
`category`	路徑、網絡	string	是	區分關係類型：路徑爲 `route`，網絡爲 `network`。
`isDirected`	路徑	boolean	否	`true` 表示從 `members` 中第一個導航點指向第二個；`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 是擴展名稱。
版本由三個非負整數構成。
PROVIDER 和 NAME 不得包含 : 或 #。
同一 PROVIDER:NAME 在 extensions 中只聲明一次。

擴展數據存放在標註的 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
        }
      }
    }
  ]
}

一致性要求

生產者應保證：

Mega Block 和標註的 ID 在各自集合中唯一。
parent.type 爲 block 時，parent.id 引用 blocks 中存在的 Mega Block。
type 爲 relationship 時，members 中的 ID 引用 annotations 中存在的標註。
properties 中使用的擴展屬性在 extensions 中具有對應聲明。

消費者可以忽略自身不識別的普通字段。無法識別的 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