Fixes to bitmask

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented here.
 
 ## [unreleased]
 
+
+## [0.25.1] - Aug 10th, 2026
+- The `ConfidenceSlider` toolbox item now also filters `bitmask` annotations
+- The `set_annotations()` and `swap_frame_image()` public API methods now display the loading spinner while they run and return a `Promise`
+- Bitmask brush **overlap modes** (`exclude` / `overwrite`) now resolve against bitmask annotations across **all subtasks**, not just the active one.
+- Performance improvements for jobs with many large bitmask annotations:
+  - Overlap resolution (`exclude` / `overwrite`) now uses a bounding-box pre-filter and box-limited pixel operations, skipping masks that don't overlap the stroke and touching only the overlapping region of the ones that do, instead of scanning the whole mask for each candidate.
+  - Moving a bitmask renders only the moving mask over a cached snapshot of the others (throttled to one render per animation frame) instead of re-rasterizing every mask on the canvas each frame.
+  - Each bitmask caches a pre-tinted render that is reused across redraws (brush dabs, moves, pan, zoom) and rebuilt only when the mask or its color changes, removing per-frame pixel-by-pixel rasterization.
+
 ## [0.25.0] - Aug 5th, 2026
 - Add a `bitmask` annotation mode for raster (per-pixel) segmentation, selectable via `allowed_modes: ["bitmask", ...]`.
   - 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.

api_spec.md

@@ -484,7 +484,7 @@ This toolbox item requires no configuration and can be added to the `toolbox_ord
 
 ### `confidence_slider_toolbox_item`
 
-The `ConfidenceSlider` toolbox item (added to `toolbox_order` via `AllowedToolboxItem.ConfidenceSlider`) deprecates (hides) or shows spatial annotations based on their confidence values. Unlike the 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.
+The `ConfidenceSlider` toolbox item (added to `toolbox_order` via `AllowedToolboxItem.ConfidenceSlider`) deprecates (hides) or shows spatial annotations based on their confidence values. Unlike the deprecated `KeypointSlider`, it works with **all** spatial annotation types that have a confidence payload (`bbox`, `bbox3`, `polygon`, `polyline`, `contour`, `tbar`, `point`, and `bitmask`), across every subtask.
 
 It supports two modes:
 
@@ -622,7 +622,7 @@ Display utilities are provided for a constructed `ULabel` object.
 
 ### `swap_frame_image(new_src, frame=0)`
 
-*(string, int) => string* -- Changes the image source for a given frame. Returns the old source.
+*(string, int) => Promise<string>* -- Changes the image source for a given frame. Displays the loading spinner while the new image loads. Returns a `Promise` that resolves with the old source once the new image has been decoded; `await` it if you need to run code after the swap completes.
 
 ### `swap_anno_bg_color(new_bg_color)`
 
@@ -642,7 +642,7 @@ Display utilities are provided for a constructed `ULabel` object.
 
 ### `set_annotations(new_annotations, subtask)`
 
-*(array, string) => void* -- Sets the annotations for the provided subtask.
+*(array, string) => Promise<void>* -- Sets the annotations for the provided subtask. Displays the loading spinner while re-initializing the annotations (similar to a new init). Returns a `Promise` that resolves once the annotations have been set and redrawn; `await` it if you need to run code after the update completes.
 
 ### `set_saved(saved)`
 

demo/bitmask-e2e.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>ULabel - Bitmask e2e fixture</title>
+
+        <!-- ULabel Library -->
+        <script src="/ulabel.js"></script>
+
+        <!-- JQuery Library -->
+        <script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous"></script>
+
+        <!-- ULabel Usage -->
+        <script>
+            /* global $ */
+            /* global ULabel */
+
+            // Minimal two-subtask bitmask fixture for e2e tests. Uses a small generated image
+            // so masks are tiny/fast, and exposes window.ulabel for the test harness.
+            $(window).on("load", function() {
+
+                function on_submit(annotations) {
+                    console.log("submit", annotations);
+                }
+
+                // Generate a small solid image inline so masks are 64x64 (fast to encode/scan)
+                const img = document.createElement("canvas");
+                img.width = 64;
+                img.height = 64;
+                const ictx = img.getContext("2d");
+                ictx.fillStyle = "#808080";
+                ictx.fillRect(0, 0, 64, 64);
+                const image_data = img.toDataURL("image/png");
+
+                let subtasks = {
+                    "a": {
+                        "display_name": "A",
+                        "classes": [{ "name": "CA", "color": "red", "id": 1 }],
+                        "allowed_modes": ["bitmask"],
+                        "resume_from": null,
+                        "task_meta": null,
+                        "annotation_meta": null,
+                    },
+                    "b": {
+                        "display_name": "B",
+                        "classes": [{ "name": "CB", "color": "blue", "id": 2 }],
+                        "allowed_modes": ["bitmask"],
+                        "resume_from": null,
+                        "task_meta": null,
+                        "annotation_meta": null,
+                    },
+                };
+
+                let ulabel = new ULabel({
+                    "container_id": "container",
+                    "image_data": image_data,
+                    "username": "DemoUser",
+                    "submit_buttons": on_submit,
+                    "subtasks": subtasks,
+                });
+                window.ulabel = ulabel;
+                ulabel.init(function() {
+                    // ready
+                });
+
+            });
+        </script>
+    </head>
+    <body>
+        <div id="container" style="width: 100%; height: 100vh; position: absolute; top: 0; left: 0;"></div>
+    </body>
+</html>

index.d.ts

@@ -371,7 +371,7 @@ export class ULabel {
     public after_init(): void;
     public show_initial_crop(): void;
     public show_whole_image(): void;
-    public swap_frame_image(new_src: string, frame?: number): string;
+    public swap_frame_image(new_src: string, frame?: number): Promise<string>;
     public swap_anno_bg_color(new_bg_color: string): string;
 
     // Subtasks
@@ -383,10 +383,11 @@ export class ULabel {
 
     // Annotations
     public get_annotations(subtask: string): ULabelAnnotation[];
-    public set_annotations(annotations: ULabelAnnotation[], subtask: string): void;
+    public set_annotations(annotations: ULabelAnnotation[], subtask: string): Promise<void>;
     public set_saved(saved: boolean): void;
     public draw_annotation_from_id(id: string, offset?: Offset, subtask?: string): void;
     public redraw_annotation(annotation_id: string, subtask?: string, offset?: Offset): void;
+    public render_bitmask_move(annotation_id: string, subtask: string, offset: Offset): void;
     public redraw_all_annotations(
         subtask?: string,
         offset?: number | null,

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ulabel",
   "description": "An image annotation tool.",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "main": "dist/ulabel.min.js",
   "module": "dist/ulabel.min.js",
   "types": "dist/index.d.ts",

src/actions.ts

@@ -345,6 +345,13 @@ function on_in_progress_annotation_spatial_modification(
         diffY: 0,
         diffZ: 0,
     };
+    // Fast path for in-progress bitmask moves: only the moving mask is redrawn (see begin_bitmask_move).
+    const in_progress_ann = current_subtask.annotations.access[action.annotation_id!];
+    if (action.act_type === "continue_move" && in_progress_ann?.spatial_type === "bitmask") {
+        ulabel.render_bitmask_move(action.annotation_id!, subtask_key, offset);
+        ulabel.suggest_edits();
+        return;
+    }
     // Update the toolbox filter distance
     ulabel.update_filter_distance_during_polyline_move(action.annotation_id!, true, false, offset);
     // Update the annotation rendering