Ctrlk
AboutAPI ReferenceSDK ReferenceSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Per-Vertex Annotation

Overview

Import .ply mesh files with per-vertex annotations embedded directly in the file. Each annotated vertex is painted with the color of its class (vertex colors are matched against class colors from meta.json), and an object_id groups vertices into object instances.

This is useful when annotations are produced by external pipelines (e.g. 3D segmentation models) that write labels directly into PLY vertex attributes.

Format description

Supported mesh formats: .ply (ASCII only) With annotations: yes Supported annotation format: Per-vertex PLY properties + meta.json. Data structure: Information is provided below.

Input files structure

Both directory and archive are supported. Datasets may be nested; the directory hierarchy is preserved as a nested dataset hierarchy. Mesh files placed directly next to meta.json are imported into a default dataset.

Recommended directory structure:

📦 project name
├── 📂 dataset_name
│   ├── 📄 mesh_01.ply
│   ├── 📄 mesh_02.ply
│   └── 📂 nested_dataset_name
│       └── 📄 mesh_03.ply
└── 📄 meta.json

PLY File Requirements

The .ply file must be in ASCII format (format ascii 1.0; binary PLY is not supported) and must contain per-vertex color properties (red, green, blue or diffuse_red, diffuse_green, diffuse_blue) and the class_id/object_id properties in addition to the standard geometry properties. Files without class_id and object_id are not recognized as this format.

  • Vertex colors define the class: a vertex whose color exactly matches the color of a class from meta.json is annotated with that class.

  • class_id is the annotation marker: a vertex with class_id = -1 is never imported as annotated, even if its color matches a class. This allows background vertices to coexist with a class of the same color (e.g. white).

  • object_id carries instance segmentation: vertices sharing the same object_id are grouped into a single object instance. Vertices with object_id = -1 are imported as semantic (non-instance) annotation of their class.

Example PLY header:

Vertex value conventions:

Value
Meaning

color matches a class + class_id != -1

Vertex is annotated with that class

class_id = -1

Vertex is not annotated, regardless of color

color does not match any class

Vertex is not annotated (background)

object_id = -1

Vertex does not belong to any object instance

object_id >= 0

Unique object (instance) ID within the mesh

White (255 255 255) is the neutral color written by the export for unannotated vertices of colorless meshes. Thanks to the class_id/object_id markers it can also be used as a class color.

meta.json

The meta.json file defines the classes. Vertex colors in the .ply files are matched against the color field of each class, so class colors must be unique. Classes must have shape mesh or any, and projectType must be meshes. The file follows the standard Supervisely project meta format.

Example meta.json:

At least one mesh in the project must contain annotated vertices (colors matching a class), otherwise the format will not be detected.

Semantic vs Instance Segmentation

The object_id value controls how annotated vertices are grouped into objects. Vertices are grouped by the (class, object_id) pair:

Instance segmentation — give each object its own object_id (>= 0). Vertices sharing the same object_id (and the same class color) are imported as one object instance. This also allows multiple disconnected regions of the mesh to be grouped into a single object: if three separate mesh patches all have the color of class scratch and object_id = 42, they become a single object of class scratch.

Semantic segmentation — set object_id = -1 for annotated vertices. All vertices of the same class are then merged into a single object per class, even if they form disconnected regions:

Both modes can be mixed in one file: vertices of a class with object_id = -1 form one semantic object, while vertices with explicit IDs form separate instances of that class.

An object_id is expected to belong to a single class — an object instance cannot span two classes. If the same object_id does appear with two different class colors, the import will not fail: the vertices are split into separate objects, one per class.

Mesh Cleanup on Import

The colors and class_id/object_id values baked into the .ply files are only a transport for the annotations. During import they are extracted and converted into regular, editable annotation objects — the same objects you get when labeling in the Mesh Labeling Toolbox.

The mesh file itself is stored in a cleaned-up form:

  • the class_id and object_id properties are removed;

  • previously annotated vertices are repainted with neutral white — the original color underneath is unknown, because the export overwrote it with the class color;

  • vertices that were not annotated keep their original colors;

  • if every vertex carried label paint, the color properties are removed from the file entirely.

This keeps the mesh looking clean in the labeling tool: annotations are displayed as an editable overlay on top of the mesh instead of colors permanently painted into the file, and exporting and re-importing the project gives consistent results on every round trip.

PreviousSuperviselyNextImport sample dataset

Last updated