Format EasyAR Mega Annotation 0.5

Dokumen ini mendefinisikan spesifikasi format EMA 0.5.

Sebelum memulai

Baca pengantar format EasyAR Mega Annotation untuk memahami kegunaan EMA dan skenario yang sesuai.

Dalam dokumen ini, "produsen" mengacu pada program yang menghasilkan data EMA, dan "konsumen" mengacu pada program yang membaca data EMA.

Konvensi format

File EMA menggunakan encoding UTF-8 dan mengikuti sintaks JSON yang didefinisikan oleh RFC 8259.
Nama bidang dalam objek yang sama tidak boleh duplikat.
Nama bidang peka huruf besar/kecil. Nama bidang yang didefinisikan dalam dokumen ini harus menggunakan bentuk dalam tabel dan contoh.
Bidang wajib harus ada dan menggunakan tipe yang didefinisikan dalam tabel. Bidang opsional dapat dihilangkan jika tidak memiliki nilai.
UUID ditulis sebagai string dengan tanda hubung, misalnya 123e4567-e89b-12d3-a456-426614174000.
Timestamp menggunakan string tanggal-waktu UTC dalam format YYYY-MM-DDThh:mm:ssZ, dengan akurasi detik. Contoh: 2026-08-12T00:00:00Z. Format ini mengikuti representasi UTC yang didefinisikan oleh W3C Date and Time Formats.
Transformasi koordinat menggunakan sistem koordinat OpenGL tangan kanan: +X ke kanan, +Y ke atas, dan +Z ke belakang.

Struktur dokumen

Objek root dokumen EMA berisi versi format, pembuat, deklarasi ekstensi, daftar Mega Block, dan daftar anotasi.

Contoh struktur objek root EMA:

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

Bidang	Tipe	Wajib	Deskripsi
`version`	string	Ya	Versi format EMA. Dokumen 0.5 ditulis sebagai `0.5.0`.
`generatedBy`	string	Ya	Informasi tentang alat atau subjek yang menghasilkan dokumen, biasanya mencakup nama produk dan versi.
`blocks`	array<Block>	Ya	Mega Block yang direferensikan oleh dokumen. Ini dapat berupa array kosong.
`annotations`	array<Annotation>	Ya	Objek anotasi. Ini dapat berupa array kosong.
`extensions`	array<string>	Tidak	Deklarasi ekstensi yang digunakan dokumen. Lihat Ekstensi.

Block

Block merepresentasikan Mega Block yang direferensikan oleh dokumen EMA beserta informasi koordinatnya.

Bidang	Tipe	Wajib	Deskripsi
`id`	UUID string	Ya	Pengidentifikasi unik Mega Block. Nilai yang dikembalikan oleh layanan EasyAR Mega harus digunakan.
`timestamp`	date-time string	Ya	Waktu modifikasi terakhir Mega Block. Nilai yang dikembalikan oleh layanan EasyAR Mega harus digunakan. Lihat Konvensi format.
`location`	Location	Tidak	Lokasi geografis WGS 84 dari origin Mega Block.
`transform`	Transform	Ya	Transformasi Mega Block relatif terhadap sistem koordinat root scene EMA.
`keepTransform`	boolean	Ya	Apakah `transform` yang tercatat dalam dokumen dipertahankan dan diterapkan. `true` berarti mempertahankan transformasi yang disesuaikan secara manual.

Contoh 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 merepresentasikan anotasi dalam dokumen EMA.

Bidang	Tipe	Wajib	Deskripsi
`type`	string	Ya	Tipe anotasi. Nilainya `node` atau `relationship`.
`id`	UUID string	Ya	Pengidentifikasi unik anotasi. ID dalam `annotations` harus unik.
`timestamp`	date-time string	Ya	Waktu modifikasi terakhir anotasi. Lihat Konvensi format.
`featureType`	string	Tidak	Tipe fitur tempat anotasi berada.
`properties`	object	Tidak	Properti anotasi dan data ekstensi.

Node

Node merepresentasikan anotasi yang memiliki posisi spasial.

Bidang	Tipe	Wajib	Deskripsi
`type`	string	Ya	Tetap `node`.
`geometry`	string	Ya	Tipe geometri. Nilainya `point` atau `cube`.
`parent`	Parent	Ya	Sistem koordinat referensi anotasi `node`. Sistem ini dapat mereferensikan Mega Block atau lokasi geografis WGS 84; untuk dukungan produk atas yang terakhir, lihat WorldParent.
`transform`	Transform	Ya	Transformasi anotasi `node` relatif terhadap sistem koordinat referensi. Field yang disertakan ditentukan oleh `geometry`.

Jika geometry bernilai point, anotasi merepresentasikan titik posisi. Jika geometry bernilai cube, anotasi merepresentasikan area kotak yang berpusat di origin. Lihat Transform untuk persyaratan transform pada berbagai tipe geometri.

Contoh anotasi titik:

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

Contoh anotasi area kotak:

{
  "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 merepresentasikan hubungan antar anotasi, dan juga dapat digunakan untuk mengatur beberapa anotasi menjadi satu koleksi.

Bidang	Tipe	Wajib	Deskripsi
`type`	string	Ya	Tetap `relationship`.
`members`	array<UUID string>	Ya	Mencatat ID anotasi anggota secara berurutan. Anggota dapat mereferensikan anotasi `node` atau `relationship`.

Contoh anotasi hubungan:

{
  "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 merepresentasikan sistem koordinat referensi tempat Node melekat, dan menentukan dasar interpretasi transformasi spasial Node.

BlockParent

BlockParent merepresentasikan sistem koordinat referensi berbasis Mega Block.

Bidang	Tipe	Wajib	Deskripsi
`type`	string	Ya	Tetap `block`.
`id`	UUID string	Ya	ID Mega Block yang direferensikan. ID ini harus ada dalam `blocks` pada objek root.
`timestamp`	date-time string	Ya	Waktu modifikasi Mega Block yang direferensikan saat anotasi dibuat atau diperbarui. Lihat Konvensi format.

WorldParent

WorldParent merepresentasikan sistem koordinat referensi dunia dengan asal berupa lokasi geografis WGS 84.

Bidang	Tipe	Wajib	Deskripsi
`type`	string	Ya	Tetap `world`.
`location`	Location	Ya	Lokasi geografis WGS 84 dari origin sistem koordinat referensi anotasi `node`.

Peringatan

EMA 0.5 mendefinisikan struktur dengan parent.type bernilai world, tetapi EasyAR Mega Studio 2.13 dan versi setelah EasyAR Sense Unity Plugin 4003 telah menghapus fitur terkait. Definisi format ini tidak berarti versi produk tersebut mendukung penggunaan WorldParent.

Koordinat dan tipe dasar

Location

Location merepresentasikan lokasi geografis WGS 84.

Bidang	Tipe	Wajib	Deskripsi
`latitude`	number	Ya	Lintang, angka floating-point 64-bit dalam derajat desimal.
`longitude`	number	Ya	Bujur, angka floating-point 64-bit dalam derajat desimal.
`altitude`	number	Ya	Ketinggian, angka floating-point 64-bit dalam meter.

Transform

Transform merepresentasikan transformasi spasial objek relatif terhadap sistem koordinat referensi.

Bidang	Tipe	Wajib	Deskripsi
`position`	Vector3F	Ya	Posisi relatif terhadap sistem koordinat referensi.
`rotation`	Vector4F	Bersyarat	Rotasi relatif terhadap sistem koordinat referensi.
`scale`	Vector3F	Bersyarat	Skala relatif terhadap sistem koordinat referensi.

Persyaratan setiap bidang dalam berbagai kasus penggunaan adalah sebagai berikut:

Kasus penggunaan	`position`	`rotation`	`scale`
Mega Block	Wajib	Wajib	Wajib
`geometry` bernilai `point`	Wajib	Dihilangkan	Dihilangkan
`geometry` bernilai `cube`	Wajib	Wajib	Wajib

Vector3F

Vector3F merepresentasikan vektor tiga dimensi untuk mencatat posisi dan skala.

Bidang	Tipe	Wajib	Deskripsi
`x`	number	Ya	Komponen sumbu x, angka floating-point 32-bit.
`y`	number	Ya	Komponen sumbu y, angka floating-point 32-bit.
`z`	number	Ya	Komponen sumbu z, angka floating-point 32-bit.

Vector4F

Vector4F merepresentasikan quaternion untuk mencatat rotasi.

Bidang	Tipe	Wajib	Deskripsi
`x`	number	Ya	Komponen x quaternion, angka floating-point 32-bit.
`y`	number	Ya	Komponen y quaternion, angka floating-point 32-bit.
`z`	number	Ya	Komponen z quaternion, angka floating-point 32-bit.
`w`	number	Ya	Komponen w quaternion, angka floating-point 32-bit.

Properti

properties menyimpan properti umum, properti fitur, dan data ekstensi anotasi. Bidang ini adalah objek key-value, dan nilainya dapat berupa nilai JSON apa pun.

EMA 0.5 mendefinisikan properti umum berikut:

Properti	Objek berlaku	Tipe	Wajib	Deskripsi
`name`	`node`, `relationship`	string	Tidak	Nama tampilan anotasi.
`isDirected`	`relationship`	boolean	Tidak	Apakah hubungan memiliki arah. Jika tidak ditentukan, nilainya `true`.
`category`	`relationship`	string	Tidak	Kategori hubungan.

Tipe fitur

featureType menentukan tipe fitur yang diikuti anotasi. Setiap tipe fitur mendefinisikan struktur, hubungan, dan properti khusus dari anotasi terkait.

Graf titik navigasi

Graf titik navigasi merepresentasikan titik navigasi di ruang, rute yang menghubungkan titik navigasi, dan jaringan yang tersusun darinya. Ini dapat mengekspresikan rute dan hubungan konektivitas. Semua anotasi penyusun graf titik navigasi menetapkan featureType ke navPointGraph.

Graf titik navigasi terdiri dari tiga tipe anotasi:

Objek	Syarat struktur
Titik navigasi	`type` bernilai `node`, dan `geometry` bernilai `point`.
Rute	`type` bernilai `relationship`, dan `members` mereferensikan dua titik navigasi secara berurutan.
Jaringan	`type` bernilai `relationship`, dan `members` mereferensikan titik navigasi dan rute yang termasuk dalam jaringan.

Anotasi hubungan dalam graf titik navigasi menggunakan properti properties berikut:

Properti	Objek berlaku	Tipe	Wajib	Deskripsi
`category`	Rute, jaringan	string	Ya	Membedakan tipe hubungan: rute adalah `route`, dan jaringan adalah `network`.
`isDirected`	Rute	boolean	Tidak	`true` berarti dari titik navigasi pertama dalam `members` ke titik kedua; `false` berarti tidak berarah.
`weight`	Rute	number	Tidak	Bobot rute, angka floating-point 32-bit. Makna spesifiknya didefinisikan oleh aplikasi yang menggunakan graf titik navigasi.

Contoh anotasi graf titik navigasi:

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

Ekstensi

Ekstensi digunakan untuk menambahkan data kustom ke anotasi tanpa mengubah struktur inti EMA 0.5.

Array extensions pada objek root mendeklarasikan ekstensi yang digunakan dokumen. Setiap item menggunakan format berikut:

PROVIDER:NAME#MAJOR.MINOR.PATCH

PROVIDER adalah nama penyedia ekstensi.
NAME adalah nama ekstensi.
Versi terdiri dari tiga bilangan bulat non-negatif.
PROVIDER dan NAME tidak boleh berisi : atau #.
PROVIDER:NAME yang sama hanya dideklarasikan sekali dalam extensions.

Data ekstensi disimpan dalam properties anotasi, dengan nama properti PROVIDER:NAME dan tanpa nomor versi. Nilai ekstensi dapat berupa nilai JSON apa pun. Objek JSON direkomendasikan agar bidang dapat ditambahkan kemudian.

Contoh deklarasi dan data ekstensi:

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

Persyaratan konsistensi

Produsen harus memastikan bahwa:

ID Mega Block dan ID anotasi unik dalam koleksi masing-masing.
parent.type bernilai block saat parent.id mereferensikan Mega Block yang ada dalam blocks.
type bernilai relationship saat ID dalam members mereferensikan anotasi yang ada dalam annotations.
Properti ekstensi yang digunakan dalam properties memiliki deklarasi yang sesuai dalam extensions.

Konsumen dapat mengabaikan bidang biasa yang tidak dikenali. type, parent.type, atau geometry yang tidak dikenali harus diperlakukan sebagai data yang tidak didukung.

Contoh lengkap

Contoh dokumen EMA lengkap yang berisi data ekstensi:

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