EasyAR Mega Annotation-Format 0.5

Dieses Dokument definiert die Formatspezifikation von EMA 0.5.

Vorbereitung

Lesen Sie die Einführung in das EasyAR Mega Annotation-Format, um die Nutzung und Einsatzszenarien von EMA kennenzulernen.

In diesem Dokument bezeichnet "Producer" ein Programm, das EMA-Daten erzeugt, und "Consumer" ein Programm, das EMA-Daten liest.

Formatkonventionen

EMA-Dateien verwenden UTF-8-Codierung und folgen der durch RFC 8259 definierten JSON-Syntax.
Feldnamen innerhalb desselben Objekts dürfen nicht doppelt vorkommen.
Feldnamen unterscheiden Groß- und Kleinschreibung. Die in diesem Dokument definierten Feldnamen müssen die Formen aus Tabellen und Beispielen verwenden.
Erforderliche Felder müssen vorhanden sein und die in den Tabellen definierten Typen verwenden. Optionale Felder können ohne Wert ausgelassen werden.
UUIDs werden als Zeichenfolgen mit Bindestrichen geschrieben, zum Beispiel 123e4567-e89b-12d3-a456-426614174000.
Zeitstempel verwenden UTC-Datum-Uhrzeit-Zeichenfolgen im Format YYYY-MM-DDThh:mm:ssZ mit Sekundengenauigkeit. Zum Beispiel 2026-08-12T00:00:00Z. Dieses Format folgt der durch W3C Date and Time Formats definierten UTC-Darstellung.
Koordinatentransformationen verwenden ein rechtshändiges OpenGL-Koordinatensystem: +X nach rechts, +Y nach oben, +Z nach hinten.

Dokumentstruktur

Das Root-Objekt eines EMA-Dokuments enthält Formatversion, Generator, Erweiterungsdeklarationen, Mega-Block-Liste und Annotationsliste.

Beispiel für die Struktur des EMA-Root-Objekts:

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

Feld	Typ	Erforderlich	Beschreibung
`version`	string	Ja	EMA-Formatversion. Ein 0.5-Dokument wird als `0.5.0` geschrieben.
`generatedBy`	string	Ja	Informationen über das Werkzeug oder Subjekt, das das Dokument erzeugt hat, üblicherweise mit Produktname und Version.
`blocks`	array<Block>	Ja	Vom Dokument referenzierte Mega Blocks. Dies kann ein leeres Array sein.
`annotations`	array<Annotation>	Ja	Annotationsobjekte. Dies kann ein leeres Array sein.
`extensions`	array<string>	Nein	Vom Dokument verwendete Erweiterungsdeklarationen. Siehe Erweiterungen.

Block

Block stellt einen von einem EMA-Dokument referenzierten Mega Block und dessen Koordinateninformationen dar.

Feld	Typ	Erforderlich	Beschreibung
`id`	UUID string	Ja	Eindeutige Kennung des Mega Blocks. Es muss der vom EasyAR Mega-Dienst zurückgegebene Wert verwendet werden.
`timestamp`	date-time string	Ja	Letzte Änderungszeit des Mega Blocks. Es muss der vom EasyAR Mega-Dienst zurückgegebene Wert verwendet werden. Siehe Formatkonventionen.
`location`	Location	Nein	Geografische WGS-84-Position des Mega-Block-Ursprungs.
`transform`	Transform	Ja	Transformation des Mega Blocks relativ zum Root-Koordinatensystem der EMA-Szene.
`keepTransform`	boolean	Ja	Gibt an, ob das im Dokument aufgezeichnete `transform` beibehalten und angewendet wird. `true` bedeutet, die manuell angepasste Transformation beizubehalten.

Mega-Block-Beispiel:

{
  "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 stellt eine Annotation in einem EMA-Dokument dar.

Feld	Typ	Erforderlich	Beschreibung
`type`	string	Ja	Annotationstyp. Der Wert ist `node` oder `relationship`.
`id`	UUID string	Ja	Eindeutige Kennung der Annotation. IDs in `annotations` sollten eindeutig sein.
`timestamp`	date-time string	Ja	Letzte Änderungszeit der Annotation. Siehe Formatkonventionen.
`featureType`	string	Nein	Feature-Typ, zu dem die Annotation gehört.
`properties`	object	Nein	Annotationseigenschaften und Erweiterungsdaten.

Node

Node stellt eine Annotation mit räumlicher Position dar.

Feld	Typ	Erforderlich	Beschreibung
`type`	string	Ja	Fest auf `node`.
`geometry`	string	Ja	Geometrietyp. Der Wert ist `point` oder `cube`.
`parent`	Parent	Ja	Referenzkoordinatensystem der `node`-Annotation. Es kann auf einen Mega Block oder eine geografische WGS-84-Position verweisen; zur Produktunterstützung für Letzteres siehe WorldParent.
`transform`	Transform	Ja	Transformation der `node`-Annotation relativ zum Referenzkoordinatensystem. Die enthaltenen Felder werden durch `geometry` bestimmt.

Wenn geometry den Wert point hat, stellt es einen Positionspunkt dar. Bei cube stellt es einen quaderförmigen Bereich mit Ursprung als Zentrum dar. Anforderungen an transform finden Sie unter Transform.

Beispiel einer Punktannotation:

{
  "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"
  }
}

Beispiel einer Quaderbereich-Annotation:

{
  "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 stellt eine Beziehung zwischen Annotationen dar und kann mehrere Annotationen zu einer Sammlung organisieren.

Feld	Typ	Erforderlich	Beschreibung
`type`	string	Ja	Fest auf `relationship`.
`members`	array<UUID string>	Ja	Zeichnet die IDs der Mitgliedsannotationen der Reihe nach auf. Mitglieder können auf `node`- oder `relationship`-Annotationen verweisen.

Beispiel einer Beziehungsannotation:

{
  "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 stellt das Referenzkoordinatensystem dar, an dem ein Node hängt, und bestimmt die Interpretationsbasis seiner räumlichen Transformation.

BlockParent

BlockParent stellt ein auf einem Mega Block basierendes Referenzkoordinatensystem dar.

Feld	Typ	Erforderlich	Beschreibung
`type`	string	Ja	Fest auf `block`.
`id`	UUID string	Ja	ID des referenzierten Mega Blocks. Diese ID sollte in `blocks` des Root-Objekts vorhanden sein.
`timestamp`	date-time string	Ja	Änderungszeit des Mega Blocks, auf den bei Erstellung oder Aktualisierung der Annotation verwiesen wurde. Siehe Formatkonventionen.

WorldParent

WorldParent stellt ein Welt-Referenzkoordinatensystem dar, dessen Ursprung eine WGS-84-Position ist.

Feld	Typ	Erforderlich	Beschreibung
`type`	string	Ja	Fest auf `world`.
`location`	Location	Ja	Geografische WGS-84-Position des Ursprungs des Referenzkoordinatensystems der `node`-Annotation.

Warnung

EMA 0.5 definiert die Struktur, in der parent.type den Wert world hat, aber EasyAR Mega Studio 2.13 und Versionen nach EasyAR Sense Unity Plugin 4003 haben die zugehörigen Funktionen entfernt. Die Formatdefinition bedeutet nicht, dass diese Produktversionen die Verwendung von WorldParent unterstützen.

Koordinaten und Basistypen

Location

Location stellt eine geografische WGS-84-Position dar.

Feld	Typ	Erforderlich	Beschreibung
`latitude`	number	Ja	Breitengrad, eine 64-Bit-Gleitkommazahl in Dezimalgrad.
`longitude`	number	Ja	Längengrad, eine 64-Bit-Gleitkommazahl in Dezimalgrad.
`altitude`	number	Ja	Höhe, eine 64-Bit-Gleitkommazahl in Metern.

Transform

Transform stellt die räumliche Transformation eines Objekts relativ zu einem Referenzkoordinatensystem dar.

Feld	Typ	Erforderlich	Beschreibung
`position`	Vector3F	Ja	Position relativ zum Referenzkoordinatensystem.
`rotation`	Vector4F	Bedingt	Rotation relativ zum Referenzkoordinatensystem.
`scale`	Vector3F	Bedingt	Skalierung relativ zum Referenzkoordinatensystem.

Die Anforderungen für jedes Feld in verschiedenen Anwendungsfällen lauten wie folgt:

Anwendungsfall	`position`	`rotation`	`scale`
Mega Block	Erforderlich	Erforderlich	Erforderlich
Annotation, deren `geometry` `point` ist	Erforderlich	Ausgelassen	Ausgelassen
Annotation, deren `geometry` `cube` ist	Erforderlich	Erforderlich	Erforderlich

Vector3F

Vector3F stellt einen dreidimensionalen Vektor für Position und Skalierung dar.

Feld	Typ	Erforderlich	Beschreibung
`x`	number	Ja	x-Achsen-Komponente, eine 32-Bit-Gleitkommazahl.
`y`	number	Ja	y-Achsen-Komponente, eine 32-Bit-Gleitkommazahl.
`z`	number	Ja	z-Achsen-Komponente, eine 32-Bit-Gleitkommazahl.

Vector4F

Vector4F stellt ein Quaternion zur Aufzeichnung von Rotation dar.

Feld	Typ	Erforderlich	Beschreibung
`x`	number	Ja	x-Komponente des Quaternions, eine 32-Bit-Gleitkommazahl.
`y`	number	Ja	y-Komponente des Quaternions, eine 32-Bit-Gleitkommazahl.
`z`	number	Ja	z-Komponente des Quaternions, eine 32-Bit-Gleitkommazahl.
`w`	number	Ja	w-Komponente des Quaternions, eine 32-Bit-Gleitkommazahl.

Eigenschaften

properties speichert allgemeine Eigenschaften, Feature-Eigenschaften und Erweiterungsdaten von Annotationen. Dieses Feld ist ein Schlüssel-Wert-Objekt, dessen Wert jeder JSON-Wert sein kann.

EMA 0.5 definiert die folgenden allgemeinen Eigenschaften:

Eigenschaft	Gültiges Objekt	Typ	Erforderlich	Beschreibung
`name`	`node`, `relationship`	string	Nein	Anzeigename der Annotation.
`isDirected`	`relationship`	boolean	Nein	Gibt an, ob die Beziehung gerichtet ist. Wenn nicht angegeben, ist der Wert `true`.
`category`	`relationship`	string	Nein	Beziehungskategorie.

Feature-Typen

featureType gibt den Feature-Typ an, an dem die Annotation teilnimmt. Jeder Feature-Typ definiert Struktur, Beziehung und spezielle Eigenschaften der zugehörigen Annotationen.

Navigationspunktgraph

Ein Navigationspunktgraph stellt Navigationspunkte im Raum, Routen zwischen Navigationspunkten und das daraus bestehende Netzwerk dar. Er kann Routen und Konnektivitätsbeziehungen ausdrücken. Alle Annotationen, die den Navigationspunktgraph bilden, setzen featureType auf navPointGraph.

Der Navigationspunktgraph besteht aus drei Annotationstypen:

Objekt	Strukturanforderung
Navigationspunkt	`type` ist `node`, und `geometry` ist `point`.
Route	`type` ist `relationship`, und `members` verweist der Reihe nach auf zwei Navigationspunkte.
Netzwerk	`type` ist `relationship`, und `members` verweist auf Navigationspunkte und Routen, die im Netzwerk enthalten sind.

Beziehungsannotationen in einem Navigationspunktgraph verwenden die folgenden properties-Eigenschaften:

Eigenschaft	Gültiges Objekt	Typ	Erforderlich	Beschreibung
`category`	Route, Netzwerk	string	Ja	Unterscheidet Beziehungstypen: Route ist `route`, Netzwerk ist `network`.
`isDirected`	Route	boolean	Nein	`true` bedeutet vom ersten Navigationspunkt in `members` zum zweiten; `false` bedeutet ungerichtet.
`weight`	Route	number	Nein	Routengewicht, eine 32-Bit-Gleitkommazahl. Die genaue Bedeutung wird von der Anwendung definiert, die den Navigationspunktgraph verwendet.

Beispiel einer Navigationspunktgraph-Annotation:

[
  {
    "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"
    }
  }
]

Erweiterungen

Erweiterungen fügen Annotationen benutzerdefinierte Daten hinzu, ohne die EMA-0.5-Kernstruktur zu ändern.

Das Array extensions des Root-Objekts deklariert die vom Dokument verwendeten Erweiterungen. Jeder Eintrag verwendet das folgende Format:

PROVIDER:NAME#MAJOR.MINOR.PATCH

PROVIDER ist der Name des Erweiterungsanbieters.
NAME ist der Name der Erweiterung.
Die Version besteht aus drei nicht negativen Ganzzahlen.
PROVIDER und NAME dürfen weder : noch # enthalten.
Dasselbe PROVIDER:NAME wird in extensions nur einmal deklariert.

Erweiterungsdaten werden in den properties der Annotation gespeichert, mit dem Eigenschaftsnamen PROVIDER:NAME und ohne Versionsnummer. Der Erweiterungswert kann jeder JSON-Wert sein. Ein JSON-Objekt wird empfohlen, damit später Felder hinzugefügt werden können.

Beispiel für Erweiterungsdeklaration und -daten:

{
  "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
        }
      }
    }
  ]
}

Konsistenzanforderungen

Producer sollten sicherstellen, dass:

Mega-Block-IDs und Annotations-IDs sind in ihren jeweiligen Sammlungen eindeutig.
Wenn parent.type block ist, verweist parent.id auf einen vorhandenen Mega Block in blocks.
Wenn type relationship ist, verweisen IDs in members auf vorhandene Annotationen in annotations.
In properties verwendete Erweiterungseigenschaften haben entsprechende Deklarationen in extensions.

Consumer können unbekannte normale Felder ignorieren. Unbekannte Werte für type, parent.type oder geometry sind als nicht unterstützte Daten zu behandeln.

Vollständiges Beispiel

Beispiel eines vollständigen EMA-Dokuments mit Erweiterungsdaten:

{
  "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