Add Mesh project type descr

SUMMARY.md

@@ -112,6 +112,7 @@
     * [Performance Upgrade for Dense Clouds](labeling/3D-Point-Clouds/3D-point-cloud-episodes-2/3D-point-cloud-optimizations.md)
     * [3D Point Cloud and Episodes (legacy)](labeling/3D-Point-Clouds/3D-Point-Clouds-episodes-1.md)
   * [DICOM](labeling/DICOM/DICOM.md)
+  * [Meshes](labeling/meshes/meshes.md)
   * [Multiview images](<labeling/images/Multi-view images/Multi-view-images.md>)
   * [Overlay](labeling/images/Overlay/overlay.md)
   * [Multiview videos](labeling/videos/Multi-view-videos/Multi-view-videos.md)
@@ -259,6 +260,7 @@
   * [Single-Video Annotation](data-organization/Annotation-JSON-format/06_Supervisely_format_videos.md)
   * [Point Cloud Episodes](data-organization/Annotation-JSON-format/07_Supervisely_format_pointcloud_episode.md)
   * [Volumes Annotation](data-organization/Annotation-JSON-format/08_Supervisely_format_volume.md)
+  * [Meshes Annotations](data-organization/Annotation-JSON-format/09_Supervisely_format_mesh.md)
 * [Developer Portal](https://developer.supervisely.com/)
 * [SDK](https://supervisely.readthedocs.io/en/latest/sdk_packages.html)
 * [API](https://api.docs.supervisely.com)

data-organization/Annotation-JSON-format/00_ann_format_navi.md

@@ -12,3 +12,4 @@ In Supervisely you can annotate data from several different mediums: images, vid
 * [Single-Video Annotation JSON](../../data-organization/Annotation-JSON-format/05_Supervisely_format_images.md)
 * [Point Cloud Episodes](../../data-organization/Annotation-JSON-format/07_Supervisely_format_pointcloud_episode.md)
 * [Volumes Annotations](../../data-organization/Annotation-JSON-format/08_Supervisely_format_volume.md)
+* [Meshes Annotations](../../data-organization/Annotation-JSON-format/09_Supervisely_format_mesh.md)

data-organization/Annotation-JSON-format/09_Supervisely_format_mesh.md

@@ -0,0 +1,104 @@
+# Meshes Annotation
+
+## Project Structure
+
+Root 📁 `project_name` folder named with the project name
+
+- 📄 `meta.json` — project-wide class and tag definitions. See [Project Meta](./02_Project_Classes_And_Tags.md) for the full field reference.
+- 📄 `key_id_map.json` — optional mapping between object keys and their numeric IDs in Supervisely.
+- 📁 `meshes` — source mesh files in `.ply`, `.stl`, or `.obj` format.
+- 📁 `annotations` — one subfolder per mesh file, named after the mesh (e.g. `mesh_01.ply`), each containing:
+  - 📄 `annotation.json` — labeled objects for that mesh.
+  - 📁 `geometries` — binary `.bin` files, one per object, storing the face index set.
+
+**Example directory layout:**
+
+```
+📦 project_name
+├── 📂 annotations
+│   ├── 📂 mesh_01.ply
+│   │   ├── 📄 annotation.json
+│   │   └── 📂 geometries
+│   │       ├── 📄 4178a5fbc3284da9876d76ef9688de09.indices.bin
+│   │       └── 📄 9c3e12ab7f1045bc901d34ef5a72c108.indices.bin
+│   └── 📂 mesh_02.ply
+│       ├── 📄 annotation.json
+│       └── 📂 geometries
+│           └── 📄 b2d09f3e1c6840a7882e15cf4d39710a.indices.bin
+├── 📂 meshes
+│   ├── 📄 mesh_01.ply
+│   └── 📄 mesh_02.ply
+├── 📄 key_id_map.json
+└── 📄 meta.json
+```
+
+## Format of `annotation.json`
+
+Each mesh has a corresponding `annotation.json` at `annotations/<mesh_filename>/annotation.json`.
+
+```json
+{
+  "key": "be08c6a07eb04c9c8861c6b85bc97d61",
+  "meshId": 6152776,
+  "tags": [],
+  "objects": [
+    {
+      "key": "b0a626eac7a741d39c32fc02ac1db32b",
+      "id": 417339,
+      "classTitle": "scratch",
+      "tags": [],
+      "geometryType": "mesh",
+      "geometry": {
+        "indices": null,
+        "indicesPath": "geometries/4178a5fbc3284da9876d76ef9688de09.indices.bin"
+      }
+    }
+  ]
+}
+```
+
+**Field descriptions:**
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | string | Unique identifier for this annotation. |
+| `meshId` | integer | Numeric ID of the mesh in Supervisely. |
+| `tags` | array | Tags applied to the mesh itself (not to individual objects). |
+| `objects` | array | List of labeled objects. Each entry describes one annotated region on the mesh. |
+
+**Per-object fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | string | Unique identifier for the object, referenced by `key_id_map.json`. |
+| `id` | integer | Numeric ID of the object in Supervisely. |
+| `classTitle` | string | Name of the annotation class as defined in `meta.json`. |
+| `tags` | array | Tags applied to this specific object. |
+| `geometryType` | string | Always `"mesh"` for mesh objects. |
+| `geometry.indices` | null | Reserved for inline face indices; always `null` when `indicesPath` is used. |
+| `geometry.indicesPath` | string | Path to the `.bin` file containing the face index set, relative to the annotation folder. |
+
+## Geometry `.bin` Files
+
+Object geometry is stored as a binary file of 32-bit unsigned integers. Each value is a zero-based face index referring to the triangles in the source mesh. The file contains all face indices belonging to the annotated object — selecting those faces from the mesh reconstructs the labeled region.
+
+The file is named with a hex-encoded UUID and stored under `annotations/<mesh_filename>/geometries/`.
+
+```
+geometries/4178a5fbc3284da9876d76ef9688de09.indices.bin
+```
+
+## `key_id_map.json`
+
+The optional `key_id_map.json` maps string keys used in annotation files to their numeric IDs in Supervisely. This file is generated automatically when exporting a project from Supervisely and is used for round-trip import.
+
+```json
+{
+  "tags": {},
+  "objects": {
+    "b0a626eac7a741d39c32fc02ac1db32b": 417339
+  },
+  "figures": {}
+}
+```
+

labeling/meshes/meshes.md

@@ -0,0 +1,110 @@
+---
+description: >-
+  The Mesh Labeling Toolbox lets you annotate 3D mesh surfaces — PLY, STL, and OBJ files — by painting face selections directly on the mesh. Each labeled region becomes a named object tied to a class defined in your project.
+---
+
+# Meshes
+
+The Mesh Labeling Toolbox is a browser-based annotation interface for 3D surface data. It allows you to select and label groups of mesh faces, assign them to classes, attach tags and metadata, and navigate between multiple meshes in a dataset — all without leaving the browser.
+
+<figure><img src="../../.gitbook/assets/meshes/mesh-toolbox-overview.png" alt="Mesh labeling toolbox with a dental scan annotated into tooth and caries classes"></figure>
+
+The interface is divided into four areas:
+
+1. [**Top bar**](#top-bar) — navigation, undo/redo, hotkeys, and workspace controls.
+2. [**Tools panel**](#tools-panel) — annotation tools for selecting and painting mesh faces.
+3. [**Objects panel**](#objects-panel) — list of all labeled objects on the current mesh.
+4. [**Meshes panel**](#meshes-panel) — mesh list, tags, and metadata for the current mesh.
+
+---
+
+## Top Bar
+
+<figure><img src="../../.gitbook/assets/meshes/mesh-top-bar.png" alt="Top bar showing project breadcrumb, mesh filename, NEXT button, and action icons"></figure>
+
+- **Breadcrumb** — shows the current project, dataset, and mesh filename. Click any level to navigate up.
+- **NEXT / PREV** — move to the next or previous mesh in the dataset.
+- **Undo / Redo** — step backward or forward through annotation actions.
+- **Hotkeys** — open the full hotkey reference for all tools and shortcuts.
+- **More** — additional workspace options: fullscreen, screenshot, restore default layout.
+
+---
+
+## Tools Panel
+
+The vertical toolbar on the left provides tools for navigating and annotating the mesh. Only one tool can be active at a time.
+
+### Pan & Zoom (`1`)
+
+Rotate, pan, and zoom the 3D mesh. While this tool is active, interactions with annotations on the scene are disabled.
+
+### Select (`2`)
+
+Click a labeled object on the mesh to select it. Selected objects can be edited, tagged, or deleted from the Objects panel.
+
+### Vertex Paint (`5`)
+
+The main annotation tool for creating and editing mesh objects. It operates in four sub-modes, switchable from the tool settings bar that appears when the tool is active:
+
+- **Paint vertices** — brush over the mesh surface to add vertices to the active object.
+- **Erase painted vertices** — brush over existing selections to remove vertices from the active object.
+- **Paint faces** — select entire faces at once instead of individual vertices. Useful for coarser, faster annotation.
+- **Paint individual vertices** — click single vertices one by one for precise boundary control.
+
+**Brush radius** — adjust the brush size using the radius slider in the tool settings bar, or scroll the mouse wheel while the tool is active.
+
+---
+
+## Objects Panel
+
+The Objects panel lists all labeled objects on the current mesh. It mirrors the behavior of the [Images toolbox Objects panel](../images/README.md#objects-panel).
+
+<figure><img src="../../.gitbook/assets/meshes/mesh-objects-panel.png" alt="Objects panel listing tooth and caries objects with face counts and action icons"></figure>
+
+Each row shows:
+- **Class color** — the color assigned to the object's class in project settings.
+- **Class name** — the class this object belongs to (e.g., `tooth`, `caries`).
+- **Object ID** — numeric identifier (e.g., `.806`).
+- **Face count** — number of mesh faces included in this object.
+- **Tag count** — number of tags attached to this object.
+- **Visibility toggle** — hide or show the object on the mesh.
+- **Delete** — remove the object from the annotation.
+
+**Creating a new object** — at the top of the panel, use the **Click on scene to create new** selector to choose a class, then paint faces directly on the mesh. The new object is created as soon as you paint the first face.
+
+### Object actions
+
+Right-click an object row or use the action icons to:
+- **Select** — activate the object for editing.
+- **Rename / change class** — reassign the object to a different class.
+- **Add tag** — attach a metadata tag to the individual object.
+- **Delete** — remove the object and all its face selections.
+
+---
+
+## Meshes Panel
+
+The Meshes panel, in the bottom-right area, contains three sections: mesh navigation, mesh-level tags, and mesh metadata.
+
+<figure><img src="../../.gitbook/assets/meshes/mesh-meshes-panel.png" alt="Meshes panel showing active mesh info, tags, and metadata fields"></figure>
+
+### Mesh list
+
+The panel shows all meshes in the current dataset. Click any mesh in the list to switch to it. The active mesh is highlighted and displays its annotation progress (`labeled / total` faces and object count).
+
+### Mesh Property Tags
+
+Tags attached to the mesh as a whole — not to individual objects. Use mesh-level tags for properties that describe the entire scan, such as patient ID, scan quality, or acquisition date.
+
+- Click **Tags Available** to expand the full list of project tags.
+- Use the **search box** to filter tags by name.
+- Click a tag to attach it to the current mesh. Click again to remove it.
+
+### Mesh Metadata
+
+Displays system-generated and custom metadata for the current mesh:
+
+- **ID** — numeric mesh ID in Supervisely.
+- **Created** — timestamp when the mesh was first uploaded.
+- **Updated** — timestamp of the last annotation change.
+- **Custom metadata** — a free-form JSON or text field. Use it to store any additional information about the mesh (acquisition parameters, source device, processing notes). Click the field to edit and save.