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