Copy 3D MSF Ango Export - Format Documentation

This folder documents an annotation export from iMerit Ango Hub for a 3D LiDAR point-cloud labeling task. It is organised in three parts:

1. Everything in export.json - the primary annotation file.

2. The raw downloads - how to get the heavy delivery bundle.

3. The raw files, one by one - what each unzipped file contains.

Reference docs:

• Exporting annotations

• Ango export format

Part 1 - Everything in export.json

export.json is the Ango Export Format file. It is a JSON array, where each element is one asset (one source point cloud). This file has 1 asset.

This export's asset has 3 annotated objects, drawn with two tools, so two object_type values appear:

object_type	markingTool	What it is	Geometry stored in
brush_sphere	Brush Sphere	3D semantic brush (painted points)	the labeled points in delivery.las
polygongroup	Polygon	A closed polygon outline (group of vertices)	the points array inside pct

1.1 Asset-level keys

Key	Meaning
asset	Path/URL of the source asset (the point-cloud folder).
assetId	Unique Ango ID of the asset.
externalId	Your own ID for the asset (here the source filename hash).
contextData	Custom context passed in at import time (Not used in PCT).
metadata	Custom asset-level key/value pairs (not used in PCT).
batches	Names of batches the asset belongs to
task	The main object holding all annotations + workflow data (see 1.2).

1.2 The task object

Key	Meaning
taskId	Unique ID of the task.
type	Task category (default).
stage / stageId	Current workflow stage (Complete).
updatedAt	Timestamp of last change.
updatedBy	Email of the last user to edit the task.
totalDuration	Total working time on the task, in milliseconds.
duration	Time spent in the current stage, in ms.
totalIdleDuration	Total idle time, in ms.
rawPctExport	Signed S3 URL to the raw download (deliverables.zip). This is the bridge to Part 2.
tools	Array of annotation objects -the actual labels (see 1.4).
classifications	Frame-level classifications about the whole scene (see 1.3).
relations	Relationships/links between objects (e.g. tracking)
brushDataUrl / medicalBrushDataUrl	Not required in PCT
stageHistory	Snapshots of the annotations at the end of each workflow stage (see 1.6).

1.3 task.classifications[] - frame-level attributes

Answered once for the whole frame/asset (not per object).

title	tool	Example answer
is_dusty	single-dropdown	["None"]
Image Status	single-dropdown	["None"]

1.4 tools[] - one entry per annotated object

Key	Meaning
objectId	Unique ID (UUID) of this annotation object.
title	Label class name (Tall Weeds, Trees, Immovable Objects).
schemaId	ID of the class/label schema this object belongs to.
markingTool	The drawing tool used (Brush Sphere or Polygon or Cuboid or Rectangle).
page	Frame/page index within the asset ("1").
metadata	Per-object metadata (creation info).
classifications	Per-object attributes (see 1.4.1).
pct	The annotation payload incl. geometry (see 1.5).

1.4.1 classifications[] (per-object attributes)

Key	Meaning	Example
schemaId	Schema ID of this attribute.	-
tool	Attribute input type.	boolean, single-dropdown
title	Attribute name.	is_truncated, occlusion, location
answer	The selected value(s), always an array.	[false], ["none"], ["In-field Driveable area"]

1.5 The pct payload (depends on object_type)

Common keys (all object types):

Key	Meaning
label	Schema ID of the object's class (matches schemaId).
_id	Composite key: task_<frame>_<objectId>.
id	The object UUID.
object_type	Geometry type - brush_sphere or polygongroup or cuboid or rectangle or polygon2d.
identity	Instance number for that class on the frame (1, 2, 3…).
taxonomy_attribute	attributeSchemaId → answer (boolean, or an option ID for dropdowns). Machine-readable form of the per-object classifications.
image - only applicable for rectangleand polygon2d	imagename.jpg or png
reference_folder-only applicable for rectangleand polygon2d	image folder name

brush_sphere only: classified_count - count of sub-classifications. The painted points themselves are baked into delivery.las, not stored here.

polygongroup only:

Key	Meaning
position	Group origin [x, y, z].
orientation	Group rotation quaternion [x, y, z, w].
points[]	Ordered polygon vertices, each { "position": { x, y, z } }. Coordinates are in the tool's normalized plane (z ≈ 0), projected into 3D via position/orientation.

cuboid only:

Key	Meaning
position	Group origin [x, y, z].
orientation	Group rotation quaternion [x, y, z, w].
dimension	Group measurement [width, height, depth], or in 3D space as [x, y, z]

rectangle only:

Key	Meaning
coordinates[]	Array of points defining a shape or position in 2D space or image, each with x and y values

polygon2d only:

Key	Meaning
coordinates[]	Array of points defining a shape or position in 2D space or image, each with x and y values

polyline2d only:

Key	Meaning
position	Group origin [x, y, z].
orientation	Group rotation quaternion [x, y, z, w].
points[]	NA - It will be always empty []
coordinates[]	Array of points defining a shape or position in 2D space or image, each with x and y values

1.6 stageHistory[] - workflow audit trail

Each element is a snapshot of one stage (Start → Label → … → Complete).

Key	Meaning
stage / stageId	Stage name/ID.
duration / idleDuration	Time (ms) spent / idle in that stage.
completedAt / completedBy	When and by whom the stage was finished.
tools / classifications / relations	Snapshot of the annotations as they were at the end of that stage (same shape as 1.4).
brushDataUrl / medicalBrushDataUrl	Not required for PCT
taskHistory	Internal reference (_id) to that stage's stored state.

Part 2 - The raw downloads

The task.rawPctExport field (Part 1.2) holds a temporary signed S3 URL. Downloading it gives deliverables.zip - the raw delivery bundle that holds the heavy data export.json only references.

Unzipped, it contains one folder per task (here 1/) with three raw files:

deliverables.zip → 1/ ├── delivery.las (the labeled point cloud) ├── tool_output_json (full internal editor state) └── pct_annotation_output (compact annotation summary)

Note: The signed URLs (rawPctExport, and the point-cloud links inside the files) are temporary AWS pre-signed links and expire ~1h after generation.

Part 3 - The raw files, one by one

3.1 delivery.las

The labeled LiDAR point cloud - LAS v1.4, XXX points (~XX MB), generated by LASzip. It is the original cloud with the brush annotations baked into point classification (each point carries which object/class it belongs to). This is where every brush_sphere object's actual painted geometry lives - export.json only stores the brush's metadata, not its points.

3.2 tool_output_json

The full internal editor state (richer than export.json). Top-level keys: operation, output, tasks.

operation - the editing session / batch state:

Key	Meaning
_id, batch_code, upstreamnode	Batch and pipeline-node identifiers.
annIdentity / batch_seq_no / incarnation_num	Internal identity/versioning counters.
emp_code	Annotator email.
node_id / node_type / stage_name	Current workflow node (Label).
ack_time / updateTimeStamp / ready	Session timing and ready flag.
activeFrame / lastReachFrame	Frame the editor was on / furthest reached.
camera	Saved 3D camera pose (position, yaw, pitch, radius).
viewSettings	Saved viewport/render settings.
categorySchemaVersionId	Version of the label taxonomy used.
customData[]	Editor config & state (see list below).
feedback, submit_status, engagement_code, job_code	QA feedback, submission state, project/job codes.

customData[] keys: annColorCode, identityList (object count per class), renderMode (gamma/brightness/point-color), pointSizeMode, staticSizeIdentities, configPanelSettings, batchAttributes, reviewCheckmarks (per-object QA history), attributeColors, volumeIndexes, globalStatus, brushSize.

output[] - one record per object (richest geometry). Mostly annotated objects; one is a form-input record (a task-form answer).

Annotated object record:

Key	Meaning
_id / id	Composite key / object UUID.
identity	Instance number for the class.
createdAt / updated_on	When drawn / last changed.
classId / class	Class schema ID.
color / classColor	Display color (e.g. #CDDC39).
geometry	For brush_sphere: id, position, rotation. For polygongroup: position, rotation, and polygons[] - each with a geometry block holding the exact 3D placement (matrixWorldInverse, etc.).
object_type	brush_sphere or polygongroup.
taxonomy_attribute	attributeSchemaId → answer map.
isVisible / isLocked / deleted / discarded	Object UI/state flags.
order / groundClippingMode / isStaticSize	Rendering/behavior settings.
keyFrame / baseKeyFrame / isGeometryKeyFrame / attributesKeyFrame / referenceIndex	Key-frame info (multi-frame/video).
origin / originGeometry / originAttributes	How created (Manual) and original geometry/attributes.
isFirstTimeAttribute / modified / modifiedBy / isUpdated	Edit-tracking flags and last editor.
key / idbkey / seq_no / uniqueToken / node_wise_batch_details_id	Internal storage/reference keys.

Form-input record: key (e.g. formInput_1), taskAttribute (the form answer), timeSpent, percentage, updated_on, plus internal references.

tasks - the source asset descriptor:

Key	Meaning
_id, batch_code, seqNo, task_seq_no, lifecycleIndex	Task identifiers and pipeline position.
deliverable / ready	Flags: part of delivery / ready.
storageId	Storage integration ID.
url	Signed URL to the source point cloud (Potree cloud.js).
source	bucket / path / name of the source .las.
metadata	Sensor extras: calibration_location, ego_data_location, help_images[] (camera reference images per sensor pair, e.g. T01_T03), point_cloud, potree_path, ground_channel_path, transform.shift.

3.3 pct_annotation_output

A compact, clean annotation summary - the easiest file to parse.

Key	Meaning
annotations[]	The annotations - same pct shape as Part 1.5 (incl. polygon points).
batch_attribute	The frame-level answers (is_dusty, Image Status) as attributeSchemaId → optionId.
frame_attribute	Per-frame attribute answers.
meta_info	Source-cloud links (point_cloud, etc.) for this frame.
relationship	Object-to-object relations.