You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 911eb52
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: CHANGELOG.md
+14Lines changed: 14 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,20 @@ All notable changes to this project will be documented here.
4
4
5
5
## [unreleased]
6
6
7
+
## [0.25.0] - Aug 5th, 2026
8
+
- Add a `bitmask` annotation mode for raster (per-pixel) segmentation, selectable via `allowed_modes: ["bitmask", ...]`.
9
+
- Painted with the brush (toggle with `toggle_brush_mode_keybind`, default `g`); erase with `toggle_erase_mode_keybind` (default `e`); resize the brush with `increase_brush_size_keybind` / `decrease_brush_size_keybind` (defaults `]` / `[`) or `alt+scroll`. The brush/erase toggles now apply to both `polygon` and `bitmask` modes.
10
+
- A paint stroke only joins an existing mask of the currently-selected class; painting a different class (or over empty space) starts a new mask of the selected class. Erase is class-agnostic. This differs from the `polygon` brush, which joins any polygon under the brush.
11
+
- Hover a mask (with the brush off) to change its class via the ID dialog, or move/delete it like any other spatial annotation.
12
+
- Each bitmask annotation stores a single binary mask. On export, `spatial_payload` is a COCO-style run-length-encoded object: `{ "counts": <number[]>, "size": [<height>, <width>] }` (column-major, starting with a background run). Fully-erased masks are deprecated (ULabel's delete semantics).
13
+
- Configurable render opacity for bitmask classes via `mask_annotation_opacity`.
14
+
- Add brush **overlap modes** for bitmask painting, controlled globally and persisted to localStorage: `none` (default), `exclude`, and `overwrite`.
15
+
-`exclude`: newly-painted pixels never cover pixels owned by other undeprecated bitmask annotations (existing masks win).
16
+
-`overwrite`: newly-painted pixels are removed from any other bitmask annotation that owned them (the new mask wins); a mask fully carved away is deprecated.
17
+
- Resolution is deferred to the end of a stroke (you see the active mask cover others, then it snaps to the resolved result on release) and only affects the pixels a stroke adds; erase is unaffected.
18
+
- Selectable via the Brush toolbox item (shown in bitmask mode) and keybinds `set_brush_overlap_none_keybind` / `set_brush_overlap_exclude_keybind` / `set_brush_overlap_overwrite_keybind` (defaults `shift+n` / `shift+e` / `shift+o`), which also appear in the `Keybinds` toolbox item. Initial value configurable via `default_brush_overlap_mode`.
19
+
- Brush toolbox buttons have hover tooltips.
20
+
7
21
## [0.24.0] - July 22nd, 2026
8
22
- Add `ConfidenceSlider` toolbox item (`AllowedToolboxItem.ConfidenceSlider`) that deprecates (hides) or shows spatial annotations based on their confidence values. Unlike the now-deprecated `KeypointSlider`, it works with all spatial annotation types that have a confidence payload (`bbox`, `bbox3`, `polygon`, `polyline`, `contour`, `tbar`, and `point`), across every subtask.
9
23
- Supports a single global "all" slider and/or per-class sliders, controlled by `class_filter_mode` (`"toggle"`, `"all-only"`, or `"class-only"`).
@@ -281,9 +288,49 @@ The full list of `"allowed_modes"` that are currently supported is:
281
288
- `"whole-image"`: A label to be applied to an entire frame
282
289
- `"global"`: A label to be applied to the entire series of frames
283
290
- `"point"`: A keypoint within a single frame
291
+
- `"bitmask"`: A raster (per-pixel) segmentation mask, painted with the brush. See [Bitmask annotations](#bitmask-annotations).
284
292
- `"delete_polygon"`: Allows drawing a polygon around an area, and all annotations within that area will be deleted
285
293
- `"delete_bbox"`: Allows drawing a bounding box around an area, and all annotations within that area will be deleted
286
294
295
+
#### Bitmask annotations
296
+
297
+
The `"bitmask"` mode enables raster (per-pixel) segmentation. Each bitmask annotation stores a single binary mask the size of the image.
298
+
299
+
**Interaction**
300
+
301
+
- Painting uses the brush, shared with the `polygon` brush. Toggle the brush with `toggle_brush_mode_keybind` (default `g`) or the Brush toolbox item, erase with `toggle_erase_mode_keybind` (default `e`), and resize the brush with `increase_brush_size_keybind` / `decrease_brush_size_keybind` (defaults `]` / `[`) or `alt+scroll`.
302
+
- Starting a paint stroke over an existing bitmask of the **currently-selected class** adds to that mask; otherwise (a different class is selected, or you start over empty space) a new bitmask annotation of the selected class is created. Erasing is class-agnostic — it removes from whichever mask is under the brush. (This class-aware joining differs from the `polygon` brush, which joins any polygon under the brush.)
303
+
- With the brush off, hovering a mask surfaces the usual edit dialogs: change its class via the ID dialog, or move/delete it like any other spatial annotation. Erasing a mask entirely deprecates the annotation (ULabel's delete semantics).
304
+
- Requires the `Brush` toolbox item (`AllowedToolboxItem.Brush`) to be present.
305
+
306
+
**Overlap modes**
307
+
308
+
When painting, the brush can enforce mutual exclusivity with *other* undeprecated bitmask annotations. The mode is a single **global** value, persisted to localStorage, and is chosen via the Brush toolbox item (shown in bitmask mode) or the overlap keybinds. Its initial value comes from [`default_brush_overlap_mode`](#default_brush_overlap_mode).
309
+
310
+
- `"none"` (default): painting only adds to the active mask; other masks are untouched (pixels may be owned by multiple annotations).
311
+
- `"exclude"`: newly-painted pixels never cover pixels owned by other bitmask annotations (existing masks win).
312
+
- `"overwrite"`: newly-painted pixels are removed from any other bitmask annotation that owned them (the new mask wins); a mask fully carved away is deprecated.
313
+
314
+
Resolution is **deferred to the end of a stroke** and only affects the pixels the stroke adds (pre-existing overlaps are left alone). Erase strokes are unaffected. These modes govern *new strokes only* — they do not retroactively de-overlap already-imported masks.
315
+
316
+
**Serialization**
317
+
318
+
A bitmask's `spatial_payload` is a COCO-style, uncompressed run-length encoding:
319
+
320
+
```javascript
321
+
{
322
+
// Alternating run lengths in column-major (Fortran) order, always starting
323
+
// with a background (0) run. A leading foreground pixel is a leading 0.
324
+
"counts": [<number>, ...],
325
+
// [height, width] of the mask (matches COCO's size convention)
326
+
"size": [<height>, <width>]
327
+
}
328
+
```
329
+
330
+
Note this is the *uncompressed* form (`counts` as an integer array), not the LEB128-packed string used by `pycocotools`. Masks import from and export to this same object shape.
331
+
332
+
The render opacity of bitmask annotations is configurable via [`mask_annotation_opacity`](#mask_annotation_opacity).
333
+
287
334
The `resume_from` attributes are used to import existing annotations into the annotation session for each subtask, respectively. Existing annotations must be provided as a list of annotations of the form specified above.
288
335
289
336
### `task_meta` and `annotation_meta`
@@ -506,16 +553,31 @@ Keybind to toggle between annotation and selection modes. Default is `u`.
506
553
Keybind to create a bounding box annotation around the `initial_crop`. Default is `f`. Requires the active subtask to have a `bbox` mode.
507
554
508
555
### `toggle_brush_mode_keybind`
509
-
Keybind to toggle brush mode for polygonannotations. Default is `g`. Requires the active subtask to have a `polygon` mode.
556
+
Keybind to toggle brush mode for `polygon` and `bitmask`annotations. Default is `g`. Requires the active subtask to have a `polygon` or `bitmask` mode.
510
557
511
558
### `toggle_erase_mode_keybind`
512
-
Keybind to toggle erase mode for polygonannotations. Default is `e`. Requires the active subtask to have a `polygon` mode.
559
+
Keybind to toggle erase mode for `polygon` and `bitmask`annotations. Default is `e`. Requires the active subtask to have a `polygon` or `bitmask` mode.
513
560
514
561
### `increase_brush_size_keybind`
515
-
Keybind to increase the brush size. Default is `]`. Requires the active subtask to have a `polygon` mode.
562
+
Keybind to increase the brush size. Default is `]`. Requires the active subtask to have a `polygon`or `bitmask`mode.
516
563
517
564
### `decrease_brush_size_keybind`
518
-
Keybind to decrease the brush size. Default is `[`. Requires the active subtask to have a `polygon` mode.
565
+
Keybind to decrease the brush size. Default is `[`. Requires the active subtask to have a `polygon` or `bitmask` mode.
566
+
567
+
### `mask_annotation_opacity`
568
+
The fill opacity (`0`-`1`) used when rendering `bitmask` (raster segmentation) annotations. Default is `0.4`.
569
+
570
+
### `default_brush_overlap_mode`
571
+
The initial [brush overlap mode](#overlap-modes) for bitmask painting: `"none"` (default), `"exclude"`, or `"overwrite"`. The live value is global and persisted to localStorage, so a user's last choice takes precedence over this default on subsequent sessions.
572
+
573
+
### `set_brush_overlap_none_keybind`
574
+
Keybind to set the brush overlap mode to `none`. Default is `shift+n`.
575
+
576
+
### `set_brush_overlap_exclude_keybind`
577
+
Keybind to set the brush overlap mode to `exclude`. Default is `shift+e`.
578
+
579
+
### `set_brush_overlap_overwrite_keybind`
580
+
Keybind to set the brush overlap mode to `overwrite`. Default is `shift+o`.
519
581
520
582
### `fly_to_next_annotation_keybind`
521
583
Keybind to set the zoom to focus on the next annotation. Default is `Tab`, which also will disable any default browser behavior for `Tab`.
0 commit comments