For AI agents: the docs index is at https://documentation.picsellia.com/llms.txt. Append .md to any documentation page URL to get its markdown version.
In case you want to annotate your DatasetVersion using the Annotation tool but without going through an Annotation Campaign, you can use the raw Annotation tool as explained below:
1. Access the Annotation tool
Access to the Annotation tool can be done from the Details and Grid views on any DatasetVersion through the pen icon when hovering over any Asset, or through the Annotate button available in Details view:
Access the Annotation tool from the Grid view
🚧
What if an Annotation Campaign is ongoing on this DatasetVersion ?
In case an Annotation Campaign is ongoing on the current DatasetVersion, if you click on the Annotate button, you will be redirected to the Task associated to the Asset in the frame of this Campaign.
2. Interface overview
The Annotation tool opens. As shown below, the header of the Annotation tool provides you with the path of the currently displayed Asset, the Version Type of the DatasetVersion, the ID of the Asset displayed and the Accept/Reject buttons used to perform the Quality Review detailed here. Moving from one Asset to the next is done from the footer toolbar, next to the toggle of the Asset gallery, as detailed below:
Annotation tool overview
As a reminder, each Asset can only have up to one Annotation related. In case you want a more modular way to annotate your DatasetVersion, it is advised to leverage Annotation Campaigns.
🎥
Annotating a video DatasetVersion?
Video Asset use a dedicated timeline-based interface, described here.
The rest of the interface is organized as follows:
On the left side, a toolbar exposes the Selection/Pan modes and the drawing tools available for the Asset. The tools displayed here depend on the Version Type of the DatasetVersion (see Shape creation for the full detail per Version Type, including the SAM-assisted tools), plus Save, Undo, and Redo. The SAM-assisted tools are not offered at all when an Admin of your Organization has turned SAM off in the Policy page of the Organization settings (see Organization policy).
On the right side, a vertical icon rail lets you switch between its panels, in this order:
Shapes: the list of Shape composing the current Annotation, grouped by Label.
Data: a thumbnail/original toggle for the underlying Data, along with its Projections if any are configured (see Visualize Data and Projections below).
Attributes: the Attribute of the Asset and of each of its Shape gathered in a single form, with a red badge counting the values that are still invalid.
Instructions, History, and Issues: the instructions of the Campaign, the history of the Asset, and its Issue. These three panels are only displayed when the Asset is opened from an Annotation Campaign (see Annotation Campaign).
Details: every piece of information related to the current Asset and its underlying Data: properties, AssetTag, DataTag, Metadata, and Custom Metadata (see Asset and Data Details below).
Settings: your personal display and behavior preferences for the tool (see Settings & Shortcuts).
Shortcuts: a read-only recap of the currently active keyboard shortcuts (see Settings & Shortcuts).
Each of these panels can be opened with a keyboard shortcut, Alt + 1 to Alt + 0 in the order of the icons, listed here.
At the bottom, a footer lets you browse the Asset gallery of the DatasetVersion and move to the previous or the next Asset.
Left / Right and Bottom menus available in the Annotation tool
3. Navigation
A. Across the current Asset
The Annotation tool offers smooth navigation across the displayed Asset. You can use the scroll wheel of your mouse or trackpad to zoom in/out, or use the Zoom in/Zoom out buttons. Press the spacebar to pan around, or Shift + Space to scroll.
The initial view of the Asset can be retrieved through the Reset Zoom button.
By default, dragging over an empty area of the Asset in Selection mode draws a selection rectangle, while holding the pan key pans the view. A preference of the Settings panel swaps the two, for the annotators who spend their day zoomed into large images: dragging then pans the Asset and keeps the current selection, and holding the pan key draws the selection rectangle instead. In both cases, a click on a Shape selects it, a click on an empty area clears the selection, and the pan key still pans while you are drawing a Shape.
Above the zoom controls, a minimap displays the whole Asset with a frame showing the part of it you are currently looking at. On a large image annotated zoomed in, it is the quickest way to know where you are and what is left to cover: drag the frame inside the minimap to pan the view, and use the scroll wheel over it to zoom around the point under your cursor. The minimap can be hidden from the Settings panel.
A grid can also be displayed over the Asset, with its cells named A1, B3… It gives a shared vocabulary to point at a region of a large image when you discuss an Asset with a reviewer. Turn it on from the header of the Shapes panel for the current session, or from the Settings panel, where you also choose how many cells it holds.
Navigate across the image in the Annotation tool
In any case, all the navigation actions can be used via customized keyboard shortcuts; the customization of keyboard shortcuts is detailed here.
B. Across the Asset of the DatasetVersion
At the bottom of the Annotation tool, you can click on Assets to open the gallery displaying the Assets queue of your DatasetVersion and click on any of them to open it in the Annotation tool.
You can navigate across the Asset displayed in the Asset gallery using Tab / Shift + Tab or the customized shortcut you defined.
4. Visualize Data and Projections
The Data panel displays the underlying Data of the current Asset, with a toggle to switch between its thumbnail and original resolution. The view you pick is kept when you move to the next Asset, so a pass made on the original resolution stays on it; Picsellia falls back to the original, then to the default view, when the Asset you open does not have the view you were using.
On a video Asset, the same toggle switches between Mpd and Original. Mpd is the frame-by-frame player on which the Track are built, and the one you annotate on; Original plays the file you uploaded, without the Shape drawn on it, which is useful to check the source video itself.
Switch between the Mpd and Original players
If the underlying Data has one or several Projections configured, the Data panel also lets you switch between them, for instance to compare an RGB image with its infrared counterpart. Projections let you link several visualizations of the same Data together; the full detail of this mechanism is available here.
A collapsible Filters block of the same panel adjusts how the image itself is displayed: Brightness, Contrast, Saturation, Gamma, Hue, and Invert. Underexposed frames, low-contrast medical or industrial images, and thermal captures are often impossible to annotate as they were acquired; these filters make the object visible without touching the file stored in your Datalake, since they only change the display. They apply to image, video, and tiled Asset alike — except Gamma, which a tiled Asset ignores — and the values you set are kept as you move from one Asset to the next.
Annotate on Projections
5. Asset and Data Details
The Details panel gathers every piece of information related to the current Asset and its underlying Data:
Asset properties (dimensions, ID, review status, annotation author/date…) and AssetTag
Data properties (filename, file size, content type, source…) and DataTag
Metadata and Custom Metadata inherited from the Data
Just like anywhere else on the platform, Custom Metadata can be created, edited, or deleted directly from this panel, the same way as detailed here.
6. Draw a Shape
While hovering over the displayed image in the Annotation tool, you can be in two modes:
Selection: to select and edit existing Shape, this mode is the default one when opening the tool (keyboard shortcut: Esc)
Draw: to create a new Shape
🚧
Configure DatasetVersion first
Before using the Annotation tool, you must ensure that your Dataset Version is set up with a Version Type and Labels.
To draw a new Shape in the current Annotation, you just need to select a drawing tool from the left toolbar or the dedicated shortcut (D if not customized), select the Label of the new Shape, and draw it.
For instance, let's walk through the process on a polygon Shape: the logic stays the same whatever the Version Type; each one's specificities and the full detail of every drawing feature are covered in a dedicated page.
First of all, you need to select the Label of the Shape you will create (no worries, it can be modified afterwards), then select the base drawing tool as shown below:
Select the active Label and select the drawing tool
The drawing techniques depend on the Version Type, but basically you will add the different points of your Shape by clicking on the image using the cursor. Once your Shape is completed, you can validate it by pressing Enter. You can also abort the drawing of a Shape while doing it using the Esc key.
Complete Shape
When the Shape is created, a new line is added to the Shapes panel on the right side of the Annotation tool, and you can visualize the Shape and its Label on the Asset.
Shape created
You can keep creating Shape on your Annotation. Before switching to another Asset or leaving the Annotation tool, you must save your modified Annotation with the save icon or with the keyboard shortcut Cmd/Ctrl + S (or the personalized shortcut). The Annotation will be saved and turned in to Review status (in case you are not in the frame of an Annotation Campaign).
Save annotation
The exact way to draw a Shape (number of clicks, available AI-assisted tools…) depends on the Version Type of the DatasetVersion. The full details for each Version Type (Classification, Object Detection, Segmentation, Mask, Point, Line, and Keypoint), including the SAM-assisted drawing tools, is available here.
7. Modify a Shape
Now that you can create Shape in different Version Types, let's see how to modify them.
A. Select the Shape
First of all, you need to select the to-be-modified Shape. It can be done:
Directly in Selection mode by clicking on the Shape directly on the Asset.
By clicking on the Shape name in the Shapes panel located on the right side.
Select a Shape from the image or from the Shapes list
In both cases, the selected Shape will be highlighted in blue, with all the potential points composing the Shape, and its details will be displayed in the Selection panel.
👍
Focus on a Shape
To directly zoom in the selected Shape, you can click on Focus in the right-click menu.
Focus
B. Label
You can change the Label of the selected Shape by:
Right-clicking on the selected Shape on the Asset, hover Change Label action and click on the new Label
Change Label of an existing Shape from right click menu
Selecting the new Label in the dropdown located at the top-left corner
Change Label of an existing Shape in the Label dropdown
Right-clicking on the selected Shape on the Shapes panel, hover Change Label action and click on the new Label
Change Label of an existing Shape from Shapes panel
From the Selection panel directly, using the Label dropdown
Change Label of an existing Shape from Selection panel
C. Dimensions and position
When a Shape is selected, all the points composing this Shape are displayed. With your mouse, you can then click on those points to modify the Shape dimensions. You can also move the Shape anywhere in the frame of the Asset.
Shape dimension
📘
It is not applicable to Classification, Segmentation, Mask, Line
Obviously, the modification of dimensions and position of a classification Shape is not possible. For the other Version Types, the number of coordinates can be infinite so the display and editing of associated coordinates is not implemented yet.
D. Delete
You can also delete any Shape on an Annotation. Once selected, it can be done in several ways:
Press the delete key
Click on the trash icon
Delete a Shape using the Trash icon
Right-click on the Shape in the Shapes panel or on the image and click on Delete
Delete a Shape from the right-click menu
8. Fill Shape Attributes and Asset Attributes
Besides a Label, a Shape also carries a free-text Text field, mainly used for OCR use cases to transcribe the text contained in the Shape. It is filled from the Selection panel, right below the Label dropdown, and is available whatever the Version Type of the DatasetVersion.
In addition to a Label, a Shape can carry one or several Shape Attribute if some are configured on its Label (see Attributes for how to configure them from the DatasetVersionSettings). Those Attribute values can be filled directly from the Annotation tool (in addition to the Python SDK or the import of COCO file).
To fill them, select the Shape and open the Selection panel on the right side. Besides the Label dropdown and the Text field, a Shape attributes section lists one input per configuredAttribute, matching its Type (String, Integer, Float or Boolean) and its Choices if configured. Required Attribute are marked with a red *.
Fill in a required Shape Attribute with String type
🚧
Invalid Attribute block saving
A value is invalid as soon as it does not match the configuration of its Attribute: a Required one left empty, a number outside the configured Min / Max, or a value that is not one of the configured Choices. The field is flagged as you type, the Shape carrying it is marked in the Shapes panel and on the Asset, and the Attributes tab carries a red count of the values still to fix.
Saving the Annotation then fails: an error message names the Shape that is incomplete, the Attribute section opens, and it scrolls to the first field to correct.
In addition to Shape Attribute, Picsellia also supports Asset Attribute if some are configured on the DatasetVersion (see Attributes for how to configure them). Unlike Shape Attribute, an Asset Attribute describes the entire Asset rather than a specific Shape, for instance the weather conditions or the acquisition device of the image.
To fill them, deselect any Shape — or select none yet — and open the Selection panel on the right side. When no Shape is selected, or when several are, this panel displays an Asset attributes section instead, listing one input per configured Asset Attribute, matching its Type (String, Integer, Float, Boolean) and its Choices if configured. Required Asset Attribute are marked with a red *.
The Attributes tab displays the Asset Attribute too, whatever the Shape selected, together with the Shape Attribute of all the Shape.
Fill in a required Asset Attribute with Integer type
🚧
Invalid Attribute block saving
Just like Shape Attribute, an Asset Attribute whose value is missing while Required, or does not match its configuration, blocks the save of the Annotation until you correct it.
The Attribute fields of the Selection panel and of the Attributes tab, for a Shape as for the Asset, are read-only whenever the Annotation cannot be edited: with a reader access, or on a Task of an Annotation Campaign that is already Done or Accepted, that has been Skipped, or that is assigned to someone else. The recorded values stay visible, they cannot be changed.
9. Actions on Shape (Lock, Hide, and Reorder Shape)
To ease the Annotation process, you can lock, hide, duplicate, or reorder a Shape. It can be done by right-clicking on a Shape or by using the icons in the Shapes panel as shown below:
Actions on selected Shape from right-click menu
Actions on selected Shape from Shapes list
Obviously, a hidden Shape is not deleted; it is only not displayed. Locking a Shape prevents anyone from editing it. To unlock or make a Shape visible, you just need to click again on the Hide or Lock icon.
If you work on dense Asset where a Shape you have already placed easily gets dragged while you draw the next one, turn on Lock shapes after creation in the Settings panel: every Shape is then locked as soon as you validate it, and you unlock the ones you want to correct.
When several Shape overlap, you can change their stacking order from the right-click menu using Bring forward and Send backward. A click always selects the smallest Shape under the pointer, whatever the stacking order, so clicking a small Shape drawn over a large one picks the small one, and clicking next to it picks the large one.
Shape that overlap and share a Label are also hard to tell apart because they carry the same color. The palette button of the Shapes panel header displays each Shape in its own color for the current session (Shift + U), and the same display can be turned on for good, or imposed on the team, from the Settings panel. The Shapes panel and the timeline keep the Label colors, so you still read the Annotation by class in the list.
You can also lock or hide all the Shape of an Annotation with the same Label, as the Shape are all grouped together in the Shapes panel on the right side.
Action on all the Shapes with the same Label
As it is the case for most of the actions available in the Annotation tool, all the actions described above can be triggered with a keyboard shortcut (either the default one or the customized one).
A Shape copied with Cmd/Ctrl + C, or from the right-click menu, is pasted with Cmd/Ctrl + V centered on your cursor instead of on top of the original, which saves you from dragging it into place every time you reuse a Shape of the same size. The group you copied keeps its layout, and the paste is clamped so that nothing lands outside the image.
When the paste is not centered on the cursor — a mask, a classification Shape, or a cursor outside the image — and when you use Duplicate, the new Shape lands 20 pixels away from the one it comes from rather than exactly over it, so you can tell them apart at a glance instead of discovering two stacked Shape at review time. Pasting the same copy again lands further away each time, and the offset is reversed near an edge so that the Shape stays inside the image.
For visibility purposes, in addition to the possibility of hiding Shapes, you can also adjust the opacity of any Shape as shown below:
Adjust opacity of selected Shape
To change the opacity of every Shape of the Asset at once, use the slider displayed next to the zoom controls: it applies live while you drag it, and the value you release it on is saved as your Shape opacity preference. It is the fastest way to check what sits under a dense layer of masks without hiding anything. The slider can be hidden from the Settings panel, and it is read-only when your Organization enforces the opacity.
10. Group Selection
For practical reasons, the Picsellia Annotation tool offers the possibility to select several Shape at a time and make modifications to a group of Shape.
Multiple Shape selection can be done:
On the Asset by drawing within the Selection mode a rectangle over the to-be-selected Shape, the selected Shape will be highlighted with blue in the Shapes panel.
Manual Group selection
By selecting all the Shape with a specific Label directly from the Shapes panel, as Shape with the same Label are grouped. So selecting the Label will automatically select all the Shape with this Label, for instance, helmet:
Group selection by Label
Clicking the same Label row again unselects every Shape of the group, which is the quickest way to clear a group you selected by mistake.
By combining clicks in the Shapes panel: Cmd/Ctrl + click adds a Shape to the selection or removes it from it, and Shift + click extends the selection to every Shape between the last one you clicked and this one, keeping what you had already picked. A range that crosses the row of a Label selects every Shape of that group.
Selecting a Shape on the Asset expands the group of its Label in the Shapes panel, so what you selected is always visible in the list instead of being hidden under a collapsed row.
Once a group of Shape is selected, you can:
Change the position of those Shape by dragging them, and their dimensions by dragging a handle of the selection, whatever their type. On a video, each rectangle of the group gets a keyframe at the playback cursor and its other frames are left untouched. A selection that holds a mask can only be moved, not resized.
Change the Label of all the selected Shape with the right-click or the Labels dropdown (located in the top-left corner)
Delete the selected Shape with the delete key, the trash icon or the right-click menu
Duplicate the selected group Shapes
Lock or hide them with the icons or the right-click menu
Adjust their opacity...
11. Settings & Shortcuts
The Settings panel lets you configure your personal display and behavior preferences for the tool. The full details of every setting are available here.
To make the Annotation process as smooth and efficient as possible, most of the actions of the Annotation tool can be done using buttons on the tool but also through keyboard shortcuts. The full list of shortcuts, how they change depending on the Version Type of the DatasetVersion, and how to personalize them, are described here.
12. Quality review
To ensure the quality of your Annotation and as Picsellia is a collaborative platform, you can review Annotation. The idea is to leverage the Annotation status field. This field can have three values:
To Review
Accepted
Rejected
When an Annotation is created and saved, either through the Annotation tool or via Annotation import, Annotation are by default with the status To Review.
To Accept or Reject an Annotation, you just need to open the Annotation Tool on the Asset that has the Annotation to be reviewed and click on Accept annotation or Reject annotation.
Accept or Reject button
Please be aware that any user that has access to the DatasetVersion can review any of its Annotation.
Once done, the Annotation is considered reviewed, and as a consequence, it cannot be modified anymore (all Shape will be automatically locked). However, if you want to be back to editing mode on a reviewed Annotation, you just need to click on Clear review. The Annotation will be back in To Review status, and all the Shape unlocked.
Clear review of an Accepted annotation
✅
Review status
The review status field is displayed in all Assets views and as a badge in the Annotation tool gallery.
This Annotation status has no incidence on the rest of the DatasetVersion or Asset manipulations: it is a very simple, basic review mechanism whose only concrete effect is to lock the Shape of the reviewed Annotation (as detailed above). It does not restrict, block, or alter any other operation on the Asset.
For broader quality control needs, annotation task assignment, and tracking and organizing fleets of annotators, refer to Annotation Campaign.