From 1d6f81cd1c43a2b3e1eba3f8c3607ee761e6d723 Mon Sep 17 00:00:00 2001 From: GoldenAnpu Date: Wed, 27 May 2026 00:02:06 +0200 Subject: [PATCH] Add comprehensive guide for GitBook documentation editing - Introduced SKILL.md as a detailed guide for editing GitBook documentation in various environments. - Updated SUMMARY.md to include new section for Meshes. - Added links to Meshes annotations in the Annotation JSON format navigation. - Created 09_Supervisely_format_mesh.md to define the structure and format for Mesh annotations. - Created meshes.md to describe the Mesh Labeling Toolbox and its features. --- .github/copilot-instructions.md | 224 ++++ SKILL.md | 963 ++++++++++++++++++ SUMMARY.md | 2 + .../00_ann_format_navi.md | 1 + .../09_Supervisely_format_mesh.md | 104 ++ labeling/meshes/meshes.md | 110 ++ 6 files changed, 1404 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 SKILL.md create mode 100644 data-organization/Annotation-JSON-format/09_Supervisely_format_mesh.md create mode 100644 labeling/meshes/meshes.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..4b6e3a0a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,224 @@ +# Supervisely Docs — Copilot Instructions + +This is the Supervisely product documentation repository, synced to GitBook. +All pages are Markdown with GitBook-specific syntax extensions. + +**GitBook syntax reference: [`/SKILL.md`](/SKILL.md)** — read it before using any GitBook block you are unsure about (stepper, tabs, columns, embed, hint, include, variables, frontmatter fields, SUMMARY.md structure). + +--- + +## Core Principle + +Every page must answer three questions within the first 2–4 sentences: + +1. **What is this?** — one-line definition of the feature. +2. **What problem does it solve?** — the concrete limitation it removes. +3. **What does the user get?** — measurable outcome (speed, scale, accuracy, time saved). + +**Weak intro (avoid):** +> This article about the new labeling interface for 3D Point Clouds in Supervisely that introduces a significantly enhanced workflow, offering extended functionality and improved usability. + +**Strong intro (use):** +> The 3D Point Cloud labeling tool annotates LiDAR and RADAR data at scale. It unifies single-frame and episode-based workflows into one interface and handles point clouds of up to 50 million points per frame without sacrificing responsiveness. + +--- + +## Page Structure + +``` +Frontmatter (description = one tight, self-contained sentence) +H1 — exact feature name as in UI +Intro (2–4 sentences: what / problem / outcome) +Feature highlights list ← overview pages only +Quickstart ← any feature requiring activation or setup +Sub-sections (H2/H3 per capability) +Summary ← required for pages > ~600 words +``` + +### Frontmatter `description` + +One sentence, specific enough to stand alone in a search result. No "This article...", no vague adjectives. + +```markdown +--- +description: >- + Live Training continuously fine-tunes a detection or segmentation model + in parallel with human annotation, producing pre-labels from the 5th image onward. +--- +``` + +### H1 Title + +Exact feature name as it appears in the UI. No taglines, no version numbers. + +### Intro Paragraph + +- 2–4 sentences. State the feature, the problem it removes, and the concrete result. +- Include at least one specific number if available. +- Do not repeat the H1 title verbatim. + +### Feature Highlights List + +**bold name** — plain description. One level deep only. + +```markdown +- **AI-assisted labeling** — Smart Tool and Auto Labeling cut annotation time +- **Cuboid Tracking** — propagate annotations across frames automatically +- **Timeline navigation** — step through episode frames without leaving the view +``` + +### Quickstart / How-to Steps + +- Each step must name the **exact UI element** (match in-app capitalization). +- ≤ 4 steps: plain numbered list. +- ≥ 5 steps or steps with sub-actions: use `{% stepper %}` (see SKILL.md for syntax). + +--- + +## Voice and Tone + +| Do | Avoid | +|---|---| +| Second person: "you", "your" | "we", "our tool" | +| Active voice: "Click **Run**" | Passive: "the button should be clicked" | +| Present tense for UI state | Future tense: "will be shown" | +| Specific: "up to 1,000 objects" | Vague: "many objects", "large datasets" | +| Problem-first framing | Feature-first marketing language | + +**Problem-first framing example:** +> Conventional workflows require manual coordination between labeling and training phases, creating idle time. Live Training eliminates this by fine-tuning the model continuously as you annotate. + +--- + +## Formatting Rules + +### Bold and backticks + +- `**bold**` — UI element names (buttons, tabs, panels), key terms on first mention, name in a name — description list. +- `` `backticks` `` — keyboard shortcuts (`Space`, `3`), class names, file names, exact strings. +- Do not bold entire sentences. + +### Lists + +- `-` (dash) for all unordered lists. Never mix `-` and `*` in the same file. +- `1.` only for ordered steps where sequence matters. + +### Hint blocks + +| Intent | Style | +|---|---| +| Availability (Enterprise, beta, browser requirement) | `{% hint style="info" %}` | +| Tip or shortcut that saves time | `{% hint style="success" %}` | +| Risk of data loss or irreversible action | `{% hint style="warning" %}` | +| Breaking limitation or known issue | `{% hint style="danger" %}` | + +1–3 lines max. Use for callouts, not for primary content. + +### Images + +`alt` describes what the screenshot shows, not what the feature does. + +```markdown +
Auto Labeling dropdown with Live Training option selected
+``` + +### Embedded videos + +Always include a one-line caption describing what the video demonstrates. + +```markdown +{% embed url="https://youtu.be/..." %} +Annotating a vehicle in a dense urban scene using the Cuboid tool with AI auto-adjustment. +{% endembed %} +``` + +--- + +## Technical Explanations + +Always follow a technical description with a practical consequence. Never end on the technical detail alone. + +> *WebGPU provides lower-level GPU access and more rendering parallelism.* +> **In practice:** the tool renders more points per frame and stays smooth on low-end hardware. + +--- + +## Numbers and Metrics + +- Always include benchmark data when available. Prefer a table over inline prose. +- Use `\~` prefix for approximate values: `\~50 fps`. +- Write large numbers with commas (`100,000,000`) or shorthand (`100M`). +- Always state conditions: "50 fps on MacBook Air M-series with 10M points", not just "50 fps". + +--- + +## Internal Linking + +- Link to related pages the first time a concept is mentioned, not every time. +- Use the page's H1 as link text for overview page links. +- Use descriptive anchor text for section links — never "here" or "this page". + +```markdown +See [Experiments](../training/experiments.md) for checkpoint management. ✓ +See [here](../training/experiments.md) for more details. ✗ +``` + +--- + +## What to Avoid + +- **Marketing adjectives without numbers**: "powerful", "seamless", "revolutionary", "cutting-edge", "enhanced", "improved usability", "easy to use", "various", "significantly" (without a figure). +- **Restating the title in the intro**: page titled "Live Training" should not open with "Live Training is a feature of Supervisely...". +- **Passive phrasing**: "it can be used to", "can be applied when" — write what it does directly. +- **Steps without UI anchors**: every step must name the exact button, tab, or panel. +- **Algorithm dumps without user impact**: always follow technical detail with a practical consequence. +- **Captions missing on media**: every `{% embed %}` and every `
` that is ambiguous must have a caption / alt text. + +--- + +## Summary Section + +Required for pages > ~600 words. Bullet list, one line per point, outcome-first. + +```markdown +## Summary + +- **WebGPU rendering** enables smooth annotation at 100M+ points. +- **Low-end hardware** handles 40M-point scenes at usable frame rates. +- **Pen and Select tools** stay responsive regardless of scene density. +- No configuration required — improvements apply automatically on supported browsers. +``` + +--- + +## Pre-publish Checklist + +- [ ] `description` is specific and self-contained (no "This article...") +- [ ] Intro: what the feature is, what problem it solves, concrete outcome +- [ ] All UI elements are **bolded** and match exact in-app labels +- [ ] Steps are numbered; each names the specific UI element +- [ ] Every `{% embed %}` has a caption +- [ ] Every `
` has a descriptive `alt` attribute +- [ ] Hint blocks used for availability, tips, warnings — not primary content +- [ ] No vague marketing language +- [ ] Internal links use descriptive anchor text +- [ ] Pages > 600 words have a `## Summary` section +- [ ] Consulted SKILL.md for any GitBook block syntax used + +--- + +## GitBook Quick Reference + +For full syntax details, **read [`SKILL.md`](/SKILL.md)**. Short reminders: + +| Need | Block | +|---|---| +| Sequential steps (≥ 5 or with sub-actions) | `{% stepper %}...{% endstepper %}` | +| Alternative options (OS, language, plan) | `{% tabs %}...{% endtabs %}` | +| Callout / warning / tip | `{% hint style="info\|success\|warning\|danger" %}` | +| Embedded video | `{% embed url="..." %}caption{% endembed %}` | +| Expandable section | `
Titlecontent
` | +| Side-by-side comparison | `{% columns %}...{% endcolumns %}` | +| Reusable content block | `{% include "/reusable-content/rc..." %}` | +| Image | `
...
` | +| Internal link | `[text](../folder/page.md)` | diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 00000000..253c4691 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,963 @@ +# skill + +A comprehensive guide for editing GitBook documentation in external environments like Cursor, Claude Code, or other text editors. This skill provides all the formatting syntax, configuration options, and best practices needed to create and maintain GitBook content outside the GitBook web interface. + +### When to Use This Skill + +Use this skill when working with GitBook documentation through: + +* Git-synced repositories (GitHub, GitLab) +* Local markdown editors +* IDE integrations +* Command-line tools +* Any environment where you're editing GitBook content as files rather than through the GitBook UI + +### Quick Reference + +#### GitBook Content Structure + +GitBook organizes content through pages, spaces, and collections: + +* **Pages** are individual markdown files that make up your documentation +* **Spaces** are collections of pages organized into a documentation site +* **Collections** are groups of spaces + +**File structure:** + +``` +/ + .gitbook/ + assets/ # GitBook-managed images and files + includes/ # Reusable content blocks + vars.yaml # Space-level variables + .gitbook.yaml # Configuration + README.md # Homepage + SUMMARY.md # Table of contents + getting-started/ # Section folder + installation.md + quickstart.md + api-reference/ + authentication.md + endpoints.md +``` + +**Frontmatter fields:** + +```markdown +--- +description: Page description for SEO +icon: book-open +hidden: true +vars: + page_variable: value +if: visitor.claims.unsigned.condition +layout: + width: default # or 'wide' + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true + metadata: + visible: true +--- +``` + +**Variables and expressions:** + +* Space variables: `/.gitbook/vars.yaml` +* Page variables: Frontmatter `vars:` +* Expression syntax: `space.vars.variableName` + +**Most common custom blocks:** + +* `{% tabs %}...{% endtabs %}` for alternatives +* `{% hint style="..." %}...{% endhint %}` for callouts +* `{% stepper %}...{% endstepper %}` for sequential steps +* `
......
` for expandable content + +**Links:** + +* External: `[text](https://example.com)` +* Internal: Use relative paths like `[text](page.md)` or `[text](../folder/page.md)` + +**Key reminders:** + +* Read SUMMARY.md first when working with existing content to understand structure +* Test in GitBook after editing locally +* Keep SUMMARY.md synchronized with your file structure +* Variables are defined in `.gitbook/vars.yaml` (space-level) or page frontmatter (page-level) +* OpenAPI specs must be uploaded via API/CLI/UI, not embedded in markdown + +### When to Use Which Block + +Choose the right GitBook block for your content needs: + +| Need | Use | Why | +| ------------------------------------------ | --------------------------- | --------------------------------------------------------------------- | +| Sequential, ordered instructions | `{% stepper %}` | Guides users through multi-step processes with clear progression | +| Alternative options (languages, platforms) | `{% tabs %}` | Lets users choose their relevant option without cluttering the page | +| Optional or detailed information | `
` (Expandable) | Keeps page scannable while providing depth for interested readers | +| Important warnings or tips | `{% hint %}` | Draws attention with colored styling (info, warning, danger, success) | +| Side-by-side comparisons | `{% columns %}` | Shows related information in parallel (max 2 columns) | +| Timeline or changelog | `{% updates %}` | Displays dated entries in reverse chronological order | +| Visual navigation cards | `` | Creates clickable card grid for section navigation | +| Downloadable files | `{% file %}` | Provides files with captions and descriptions | +| Call-to-action links | `` | Highlights primary or secondary actions | +| Reusable content across pages | `{% include %}` | Maintains consistency for repeated content blocks | +| Dynamic content | `` | Displays variable values that update automatically | + +**Variable scope decision:** + +| If variable is... | Define it as... | Access with... | +| -------------------------- | ------------------------------------ | ------------------------- | +| Used across multiple pages | Space-level in `/.gitbook/vars.yaml` | `space.vars.variableName` | +| Specific to one page | Page-level in frontmatter `vars:` | `page.vars.variableName` | + +### Working with Existing Content + +When working with an existing GitBook space that's synced to Git, follow this workflow to understand the structure: + +1. **Read SUMMARY.md first** - This file contains the complete table of contents and navigation structure. It shows you: + * All pages and their hierarchy + * Page groups and organization + * The relative paths to each markdown file +2. **If SUMMARY.md doesn't exist** - GitBook has inferred the structure from your directory layout. Browse the directory structure to understand how pages are organized. +3. **Check .gitbook.yaml** - Review this file to understand: + * Where the root documentation directory is located + * Any custom paths for README.md or SUMMARY.md + * Existing redirects +4. **Explore .gitbook/assets/** - Contains all uploaded images and files referenced in the documentation +5. **Check .gitbook/vars.yaml** - Contains space-level variables if any are defined + +This approach ensures you understand the existing structure before making changes, helping you maintain consistency and avoid breaking internal links. + +### Configuration Files + +#### .gitbook.yaml + +The `.gitbook.yaml` file configures your GitBook space. It should be placed at the root of your documentation directory (or in a subdirectory if using monorepos). + +**Basic structure:** + +```yaml +root: ./ + +structure: + readme: ./README.md + summary: ./SUMMARY.md + +redirects: + old-page: new-page.md + help: support.md +``` + +**Configuration options:** + +* `root`: The root directory for your documentation (default: `./`) +* `structure.readme`: Path to your homepage (default: `./README.md`) +* `structure.summary`: Path to your table of contents (default: `./SUMMARY.md`) +* `redirects`: Key-value pairs mapping old URLs to new page paths + +**Monorepo support:** + +For repositories with multiple documentation projects: + +``` +/ + packages/ + docs/ + .gitbook.yaml + README.md + SUMMARY.md + api/ + .gitbook.yaml + README.md + SUMMARY.md +``` + +When setting up Git Sync, configure the "Project directory" to point to the subdirectory containing the `.gitbook.yaml` file. + +**Important notes:** + +* Paths in `.gitbook.yaml` are relative to the `root` option +* Redirects defined here are space-specific (apply only to this space) +* For site-wide redirects across multiple spaces, use the GitBook UI instead +* When using Git Sync, manage the README file only through your repository to avoid conflicts + +### The .gitbook Directory + +When using Git Sync, GitBook creates a `.gitbook` directory in your repository to store assets, variables, and generated content. + +**Directory structure:** + +``` +.gitbook/ + assets/ # Uploaded images and files + includes/ # Reusable content blocks (exported as individual .md files) + vars.yaml # Space-level variables +``` + +**Important notes about .gitbook:** + +* **Assets**: Images and files uploaded through the GitBook UI are stored in `.gitbook/assets/` +* **Reusable content**: Each reusable content block is exported as a separate markdown file in `.gitbook/includes/` +* **Variables**: Space-level variables are stored in `.gitbook/vars.yaml` as key-value pairs +* **References**: Pages reference reusable content using `{% include "/reusable-content/rc12345" %}` +* **Images**: Markdown pages reference images like `![alt](../.gitbook/assets/image-name.svg)` +* **Table of contents**: The `.gitbook/includes` folder and its files may appear in your space's table of contents. You may need to manually hide them from the TOC if this happens. +* **Location**: In monorepos, the `.gitbook` directory is created in the root of each synced space (not necessarily the repository root) + +#### SUMMARY.md + +The `SUMMARY.md` file defines your table of contents and navigation structure. It's a markdown file with a specific format that mirrors the sidebar navigation in GitBook. + +**Basic structure:** + +```markdown +# Summary + +## Use headings to create page groups like this one + +* [First page's title](page1/README.md) + * [Some child page](page1/page1-1.md) + * [Some other child page](page1/page1-2.md) +* [Second page's title](page2/README.md) + * [Some child page](page2/page2-1.md) + * [Some other child page](page2/page2-2.md) + +## A second page group + +* [Another page](another-page.md) +``` + +**Key rules:** + +* Use `#` for the main title (commonly "Table of contents" or "Summary") +* Use `##` headings to create page groups (section headers in the sidebar) +* Use `*` for unordered lists to define pages and subpages +* Indent with spaces (not tabs) to create nested/child pages +* Each list item should be a markdown link: `[Link text](path/to/file.md)` +* Paths are relative to the location specified in `.gitbook.yaml` (typically the root) + +**Page link titles (optional):** + +You can define a different title for the sidebar navigation versus the page itself: + +```markdown +# Summary + +* [Page main title](page.md "Page link title") +``` + +The text in quotes ("Page link title") will be used in: + +* The table of contents sidebar +* Pagination buttons at the bottom of pages +* Any relative links to that page + +**Important notes:** + +* SUMMARY.md is optional. If not provided, GitBook infers structure from your folder hierarchy +* You cannot reference the same markdown file twice in SUMMARY.md (each page has only one URL) +* GitBook updates SUMMARY.md automatically when you edit through the GitBook UI +* The file structure reflects exactly what users see in the navigation sidebar + +### Markdown Formatting + +GitBook uses GitHub Flavored Markdown with custom extensions. + +**Standard markdown:** + +```markdown +# Heading 1 +## Heading 2 +### Heading 3 + +**bold text** +*italic text* +`inline code` + +- Bullet list item +- Another item + - Nested item + +1. Numbered list +2. Second item + +[Link text](https://example.com) +[Internal link](getting-started.md) +``` + +**Code blocks:** + +````markdown +```javascript +const foo = 'bar'; +console.log(foo); +``` +```` + +**Code blocks with titles:** + +````markdown +{% code title="index.js" %} +```javascript +const foo = 'bar'; +console.log(foo); +``` +{% endcode %} +```` + +**Inline links:** + +* External links: `[text](https://example.com)` +* Internal pages: Use relative file paths like `[text](page.md)`, `[text](../folder/page.md)`, or `[text](subfolder/page.md)` +* Email: `[text](mailto:email@example.com)` + +**Math/TeX:** + +```markdown +Inline formula: $$E = mc^2$$ + +Block formula: + +$$ +E = mc^2 +$$ +``` + +### Page Frontmatter + +GitBook supports YAML frontmatter at the top of markdown files to configure page-specific settings. Frontmatter must be placed at the very beginning of the file, before any content. + +**Available frontmatter fields:** + +```markdown +--- +description: Page description used for SEO and page previews +icon: book-open +hidden: true +vars: + page_variable: value + another_var: another value +if: visitor.claims.unsigned.isPremium +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true + metadata: + visible: true +--- +``` + +**Field descriptions:** + +* **`description:`** - Page description text. Supports multiline with `>-` syntax: + + ```yaml + description: >- + This is a longer description + that spans multiple lines + ``` +* **`icon:`** - Icon name from Font Awesome (e.g., `book-open`, `bolt`, `stars`, `icons`, `brackets-curly`) +* **`hidden: true`** - Hides the page from the table of contents in published documentation +* **`vars:`** - Page-level variables (key-value pairs) that can be referenced in expressions: + + ```yaml + vars: + version: v1.2.3 + api_key: example_key + ``` +* **`if:`** - Adaptive content visibility condition. Controls when the page is visible based on visitor attributes: + + ```yaml + if: visitor.claims.unsigned.isPremium + ``` + + **Note:** While adaptive content conditions can be set in frontmatter, it's recommended to configure them through the GitBook UI for better maintainability and team visibility. +* **`layout:`** - Controls page layout and which elements are visible. This maps to the "Page Options" settings in the GitBook UI: + + * **`width:`** - Page content width + * `default` - Standard content width + * `wide` - Wider content area (automatically widens full-width blocks like tables and code) + * **`title.visible:`** - Show/hide the page title (boolean: `true` or `false`) + * **`description.visible:`** - Show/hide the page description (boolean: `true` or `false`) + * **`tableOfContents.visible:`** - Show/hide the left sidebar table of contents (boolean: `true` or `false`) + * **`outline.visible:`** - Show/hide the right sidebar page outline/headings (boolean: `true` or `false`) + * **`pagination.visible:`** - Show/hide next/previous page navigation links (boolean: `true` or `false`) + * **`metadata.visible:`** - Show/hide page metadata section (boolean: `true` or `false`) + + Example for a landing page with minimal chrome: + + ```yaml + layout: + width: wide + title: + visible: true + description: + visible: true + tableOfContents: + visible: false + outline: + visible: false + pagination: + visible: false + ``` + +**Example complete frontmatter:** + +```markdown +--- +description: Create reusable variables that can be referenced in pages and spaces +icon: icons +vars: + latest_version: v3.0.4 + support_email: help@example.com +layout: + width: wide + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true +--- + +# Your Page Title + +Page content starts here... +``` + +### Variables and Expressions + +GitBook supports variables that can be dynamically displayed in your content using expressions. Variables can be defined at the space level or page level. + +#### Variable Storage + +**Space-level variables** are stored in `/.gitbook/vars.yaml` at the root of your documentation: + +```yaml +# .gitbook/vars.yaml +food: apple +latest_version: v3.0.4 +company_name: Acme Corp +``` + +**Page-level variables** are stored in the page's frontmatter under `vars:`: + +```markdown +--- +vars: + page_food: orange + page_version: v2.1.0 +--- +``` + +#### Using Variables with Expressions + +Expressions allow you to reference and display variable values dynamically in your content. Expressions use JavaScript syntax and are wrapped in `` tags. + +**Syntax:** + +```markdown +JavaScript expression here +``` + +**Examples:** + +```markdown + +1 + 1 + + +space.vars.latest_version + + +"My favorite food is " + space.vars.food + + +page.vars.page_food + + +space.vars.latest_version === "v3.0.4" ? "Latest" : "Outdated" +``` + +**Variable references:** + +* `space.vars.variableName` - Access space-level variables defined in `/.gitbook/vars.yaml` +* `page.vars.variableName` - Access page-level variables defined in the page's frontmatter + +**Important notes:** + +* Variable definitions (the actual variable storage) are managed through: + * `/.gitbook/vars.yaml` for space-level variables + * Page frontmatter `vars:` for page-level variables +* Expressions can contain any valid JavaScript code and are evaluated when the page is rendered +* When editing locally, you can create space variables by editing `/.gitbook/vars.yaml` and page variables by adding them to frontmatter +* The GitBook UI provides a visual editor for managing variables, but they are fully editable in markdown files + +### GitBook Custom Blocks + +GitBook extends standard markdown with custom block syntax using tags like `{% tabs %}`, `{% hint %}`, etc. These blocks enable rich, interactive documentation features. + +#### Tabs + +Use tabs to present alternative content like different programming languages or platform-specific instructions. + +**When to use:** Comparing alternatives (code in different languages, platform-specific commands, configuration options). + +**Syntax:** + +````markdown +{% tabs %} +{% tab title="JavaScript" %} +```javascript +const greeting = 'Hello World'; +console.log(greeting); +``` +{% endtab %} + +{% tab title="Python" %} +```python +greeting = "Hello World" +print(greeting) +``` +{% endtab %} +{% endtabs %} +```` + +#### Stepper + +Use steppers for sequential, multi-step processes where order matters. + +**When to use:** Tutorials, installation guides, how-to guides, onboarding checklists, any sequential process. + +**Syntax:** + +```markdown +{% stepper %} +{% step %} +## First step + +Complete the initial setup by installing the required dependencies. +{% endstep %} + +{% step %} +## Second step + +Configure your environment variables in the `.env` file. +{% endstep %} + +{% step %} +## Third step + +Run the application with `npm start`. +{% endstep %} +{% endstepper %} +``` + +#### Hints + +Use hints to highlight important information without disrupting flow. Supported styles: `info`, `warning`, `danger`, `success`. + +**When to use:** Supplementary information, call-outs, best practices, warnings, troubleshooting tips. + +**Syntax:** + +```markdown +{% hint style="info" %} +This is an informational hint with helpful context. +{% endhint %} + +{% hint style="warning" %} +Be careful when running this command in production. +{% endhint %} + +{% hint style="danger" %} +This action cannot be undone. Make sure you have backups. +{% endhint %} + +{% hint style="success" %} +Your configuration has been saved successfully! +{% endhint %} +``` + +#### Expandable + +Use expandable sections for optional content that doesn't need to be visible by default. + +**When to use:** Optional deep-dives, advanced explanations, lengthy logs, FAQ answers, content that would clutter the page. + +**Syntax:** + +````markdown +
+Advanced Configuration Options + +Here you can find detailed information about advanced settings that most users won't need. + +```yaml +advanced: + option1: value1 + option2: value2 +``` +
+```` + +#### Columns + +Use columns to present content side-by-side (2 columns maximum). + +**When to use:** Side-by-side comparisons (pros vs cons), before/after examples, parallel instructions. + +**Syntax:** + +```markdown +{% columns %} +{% column %} +### Before + +Old implementation that was inefficient. +{% endcolumn %} + +{% column %} +### After + +New optimized approach with better performance. +{% endcolumn %} +{% endcolumns %} +``` + +#### Updates + +Use updates blocks for product updates, release notes, or changelogs. + +**When to use:** Changelog pages, release notes, version updates, product announcements. + +**Syntax:** + +```markdown +{% updates format="full" %} +{% update date="2024-01-15" %} +# Version 2.0 Released + +We've added new features including dark mode and improved search. +{% endupdate %} + +{% update date="2024-01-01" %} +# Bug Fixes + +Fixed several issues reported by the community. +{% endupdate %} +{% endupdates %} +``` + +#### Cards + +Use cards to create visual, clickable navigation elements. Cards are HTML tables with special attributes. + +**When to use:** Dashboards, feature overviews, linking to related pages, showcasing multiple resources. + +**Syntax:** + +```markdown +
+ + + + + + + + + + + + + + + + + + + + +
TitleTarget
Getting Started GuideQuick Start
API ReferenceAPI Docs
ExamplesCode Examples
+``` + +#### Embeds + +Use embeds to include external content like videos, interactive demos, or social media. + +**When to use:** Demonstration videos, interactive code sandboxes, tweets, external rich media. + +**Syntax:** + +```markdown +{% embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" %} + +{% embed url="https://codepen.io/username/pen/example" %} +``` + +#### Files + +Use file blocks to provide downloadable files with captions. + +**Syntax:** + +```markdown +{% file src="https://example.com/document.pdf" %} +Complete documentation in PDF format. +{% endfile %} +``` + +#### Buttons + +Use buttons for clear call-to-action links. Supported styles: `primary` and `secondary`. + +**When to use:** Download links, "Try it now" actions, external resource navigation. + +**Syntax:** + +```markdown +Download Now + +View Documentation +``` + +**Buttons with icons:** + +```markdown +View on GitHub +``` + +Icons use Font Awesome names (without the `fa-` prefix). + +#### Icons + +Inline icons from Font Awesome can enhance text readability. + +**When to use:** Visual indicators, status icons, improving scannability. + +**Syntax:** + +```markdown +check Feature enabled +warning Requires configuration +info Learn more +``` + +#### Reusable Content + +Reusable content blocks let you sync content across multiple pages. + +**When to use:** Call-to-actions, disclaimers, repeated instructions, any content that needs to stay consistent across pages. + +**Syntax:** + +```markdown +{% include "/reusable-content/rc12345" %} +``` + +Note: Reusable content blocks are different from pages. They're created through the GitBook UI and given unique IDs. + +#### OpenAPI Specifications + +OpenAPI specifications enable interactive, testable API documentation in GitBook. However, OpenAPI specs cannot be added directly to markdown files. + +**How to add OpenAPI specs:** + +OpenAPI specifications must be uploaded through one of these methods: + +1. **GitBook API** - Use the [OpenAPI endpoints](https://docs.gitbook.com/developers/gitbook-api/api-reference/openapi) to programmatically upload specs +2. **GitBook CLI** - Use the `gitbook openapi` command +3. **GitBook UI** - Upload specs through the web interface + +**Once uploaded**, you can reference API methods in your markdown using the OpenAPI block syntax: + +```markdown +{% openapi src="https://api.example.com/openapi.json" path="/users" method="get" %} +[https://api.example.com/openapi.json](https://api.example.com/openapi.json) +{% endopenapi %} +``` + +**Important notes:** + +* You cannot embed OpenAPI spec content directly in markdown files +* The `src` URL must point to an already-uploaded OpenAPI specification +* For more information, see the [GitBook OpenAPI documentation](https://docs.gitbook.com/api-references/openapi) + +### Nested Markdown in Custom Blocks + +Markdown formatting works inside custom block tags. Maintain standard markdown syntax within custom blocks: + +````markdown +{% tabs %} +{% tab title="Example" %} +This tab contains markdown: + +- Bullet points work + - Nested bullets too +- **Bold text** and *italic text* +- `inline code` + +```javascript +// Code blocks work too +const example = true; +``` +{% endtab %} +{% endtabs %} +```` + +### Common Pitfalls + +**File organization:** + +* Don't reference the same markdown file twice in SUMMARY.md +* Keep file paths consistent between SUMMARY.md and actual file locations +* Use relative paths consistently + +**Configuration conflicts:** + +* When using Git Sync, manage README.md only through your repository +* Keep .gitbook.yaml at the correct root level for your project +* Test redirects after moving or renaming files + +**Markdown formatting:** + +* Tables and columns are discouraged (use custom blocks instead) +* Avoid excessive nested lists (keep hierarchy simple) +* Don't mix tab/space indentation in SUMMARY.md + +**Custom blocks:** + +* Always close blocks properly (`{% endtab %}`, `{% endhint %}`, etc.) +* Match opening and closing tags exactly +* Test custom blocks in GitBook after editing locally + +### Working with Git Sync + +When GitBook is synced with Git: + +1. Changes in Git automatically update GitBook +2. Changes in GitBook automatically commit to Git +3. GitBook maintains SUMMARY.md based on UI edits +4. Merge conflicts should be resolved in Git + +**Best practices:** + +* Make structural changes (navigation) through SUMMARY.md in Git +* Make content changes either in Git or GitBook UI (be consistent) +* Review auto-generated commits from GitBook +* Use branch-based workflows for significant updates +* Test changes in a preview before merging to main + +### Example Complete Page + +Here's a complete example showing multiple GitBook features: + +```` +```markdown +# API Authentication Guide + +Learn how to authenticate with our API using API keys or OAuth 2.0. + +{% hint style="info" %} +All API requests require authentication. Choose the method that best fits your use case. +{% endhint %} + +## Authentication Methods + +{% tabs %} +{% tab title="API Key" %} +The simplest authentication method. Include your API key in the request header: +```bash +curl -H "X-API-Key: your-api-key" https://api.example.com/v1/users +``` + +{% hint style="warning" %} +Never commit API keys to version control. Use environment variables instead. +{% endhint %} +{% endtab %} + +{% tab title="OAuth 2.0" %} +More secure for user-facing applications: + +{% stepper %} +{% step %} +## Register your application +Get your client ID and secret from the developer dashboard. +{% endstep %} + +{% step %} +## Request authorization +Redirect users to our OAuth endpoint. +{% endstep %} + +{% step %} +Exchange code for token + +Use the authorization code to get an access token. +{% endstep %} +{% endstepper %} +{% endtab %} +{% endtabs %} + +## Rate Limits +{% columns %} +{% column %} +### Free Tier +1,000 requests/hour +10,000 requests/day +{% endcolumn %} + +{% column %} +### Pro Tier +10,000 requests/hour +100,000 requests/day +{% endcolumn %} +{% endcolumns %} +
+Need higher limits? + +Contact our sales team to discuss enterprise plans with custom rate limits and SLAs. +
+ +Get Started +```` + + +--- + +# Agent Instructions: Querying This Documentation + +If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. + +Perform an HTTP GET request on the current page URL with the `ask` query parameter: + +``` +GET https://gitbook.com/docs/skill.md?ask= +``` + +The question should be specific, self-contained, and written in natural language. +The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. + +Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections. \ No newline at end of file diff --git a/SUMMARY.md b/SUMMARY.md index 9a5d0ac8..0b36580c 100644 --- a/SUMMARY.md +++ b/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]() * [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) diff --git a/data-organization/Annotation-JSON-format/00_ann_format_navi.md b/data-organization/Annotation-JSON-format/00_ann_format_navi.md index 93d9ffbe..da960f1d 100644 --- a/data-organization/Annotation-JSON-format/00_ann_format_navi.md +++ b/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) diff --git a/data-organization/Annotation-JSON-format/09_Supervisely_format_mesh.md b/data-organization/Annotation-JSON-format/09_Supervisely_format_mesh.md new file mode 100644 index 00000000..56a4fc01 --- /dev/null +++ b/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//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//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": {} +} +``` + diff --git a/labeling/meshes/meshes.md b/labeling/meshes/meshes.md new file mode 100644 index 00000000..c0bc96a5 --- /dev/null +++ b/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. + +
Mesh labeling toolbox with a dental scan annotated into tooth and caries classes
+ +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 + +
Top bar showing project breadcrumb, mesh filename, NEXT button, and action icons
+ +- **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). + +
Objects panel listing tooth and caries objects with face counts and action icons
+ +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. + +
Meshes panel showing active mesh info, tags, and metadata fields
+ +### 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.