Feature/voxel annotation

.gitignore

@@ -26,3 +26,6 @@ tsconfig.tsbuildinfo
 -/docs/python/api/index.rst
 /docs/python/api/*.rst
 /.vite
+/.idea
+/.local
+/.env

docs/index.rst

@@ -7,6 +7,7 @@ Neuroglancer
    :caption: User Guide
 
    user-guide/navigation
+   user-guide/voxel_annotation
 
 .. toctree::
    :hidden:

docs/user-guide/voxel_annotation.rst

@@ -0,0 +1,115 @@
+.. _voxel-annotation:
+
+Voxel Annotation
+================
+
+Voxel annotation allows for direct painting and editing of volumetric data
+within Neuroglancer. This feature is available for both :ref:`image-layer` and
+:ref:`segmentation-layer`.
+
+Enabling Voxel Editing
+----------------------
+
+To enable voxel editing, you must first have a writable volume source.
+
+1.  Open the **Source** tab of an Image or Segmentation layer.
+2.  Locate a volume source and click the **Write** checkbox next to it.
+
+.. note::
+  Only one source can be writable at a time within a layer. Voxel annotation is currently supported only for 3D volumes.
+
+The first time you attempt a drawing operation (like a brush stroke) after enabling writing, a confirmation dialog will appear. Note that this initial operation will be canceled; you can resume drawing once you have confirmed.
+
+.. note::
+  For the segmentation layer, it is recommended to deactivate the Highlight on hover option under the Render tab.
+
+Supported Storage and Formats
+-----------------------------
+
+Voxel editing is currently supported for the following configurations:
+
+**Storage**:
+
+- Amazon S3 or any S3 compatible storage.
+
+**Data Format**:
+
+- Zarr v2 and Zarr v3 (including OME-Zarr), with the following Compression/Encoding:
+    - None (Raw)
+    - Blosc
+    - Gzip
+
+Tools
+-----
+
+Voxel editing provides several tools for different annotation tasks. You can
+bind these tools from the **Draw** tab to use/activate them.
+
+.. _voxel-brush-tool:
+
+Brush Tool
+~~~~~~~~~~
+
+The Brush tool allows you to paint voxels by clicking and dragging.
+
+-   **Paint**: Hold :kbd:`Control` + :kbd:`Left Click` and drag.
+-   **Erase**: Hold :kbd:`Control` + :kbd:`Shift` + :kbd:`Left Click` and drag.
+-   **Quick Flood Fill**: Hold :kbd:`Control` + :kbd:`Right Click` to trigger a
+    flood fill at the current position. Hold :kbd:`Shift` as well to erase.
+
+Settings:
+    -   **Brush size**: Adjust the radius of the brush.
+    -   **Brush shape**: Choose between **Disk** and **Sphere** shapes.
+
+.. _voxel-flood-fill-tool:
+
+Flood Fill Tool
+~~~~~~~~~~~~~~~
+
+The Flood Fill tool fills a connected region of voxels on the current 2D plane.
+
+-   **Fill**: Hold :kbd:`Control` + :kbd:`Left Click`.
+-   **Clear**: Hold :kbd:`Control` + :kbd:`Shift` + :kbd:`Left Click`.
+
+Settings:
+    -   **Max fill voxels**: Limits the maximum number of voxels to fill to
+        prevent accidental large-scale changes. If the limit is exceeded, the
+        operation will be canceled.
+
+.. note::
+  The flood fill will automatically fill small gaps in the connected region, proportionally to the number of voxels in the region. This feature may sometimes leave unpainted voxels in tight corners of the region.
+
+.. _voxel-seg-picker-tool:
+
+Seg Picker
+~~~~~~~~~~
+
+The Seg Picker tool allows you to adopt the voxel value at the current mouse
+position as your active Paint Value.
+
+Common Controls
+---------------
+
+The **Draw** tab provides several common controls:
+
+-   **Erase only selected value**: When enabled, the erase action only affects
+    voxels that match the current **Paint Value**. This feature will slow down
+    painting performance when erasing.
+-   **Undo / Redo**: Revert or re-apply recent changes.
+-   **Paint Value**: Manually specify the segment ID or intensity value to paint.
+-   **New Random Value**: Generates a new random segment ID.
+
+Stamina System
+--------------
+
+When you perform many edits quickly, a stamina bar will appear below your cursor. This bar represents the amount of remaining work before all of your edits are processed and saved. **If you reload the page while the stamina bar is visible, you will lose some edits**. If the bar gets emptied painting will be halted until the system is able to catch up, this prevents neuroglancer from crashing due to too many edits in a short period of time.
+
+About multi-resolution datasets
+-------------------------------
+
+Any multi-resolution dataset that has many-to-1 mapping (i.e. one child cannot have multiple parents) can be used for voxel annotation.
+
+Although voxel annotation supports multi-resolution, any drawing operation will be performed on the highest resolution level, no matter what the current view is. Once an operation is completed, a downsampling pipeline will be triggered to update the lower resolution levels.
+
+.. note::
+  Because of the 3D nature of the datasets, the downsampling may cause visual artifacts: when zoomed out you may see annotations that then disappear when zoomed in, those "invisible" annotations will be found on nearby slices.

src/async_computation/encode_blosc.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { encodeBlosc } from "#src/async_computation/encode_blosc_request.js";
+import { registerAsyncComputation } from "#src/async_computation/handler.js";
+
+registerAsyncComputation(encodeBlosc, async (data, config) => {
+  const { default: Blosc } = await import("numcodecs/blosc");
+  const codec = Blosc.fromConfig({ id: "blosc", ...config });
+  const result = await codec.encode(data);
+  return { value: result, transfer: [result.buffer] };
+});

src/async_computation/encode_blosc_request.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { asyncComputation } from "#src/async_computation/index.js";
+
+export const encodeBlosc =
+  asyncComputation<(data: Uint8Array, config: any) => Uint8Array>(
+    "encodeBlosc",
+  );

src/chunk_manager/backend.ts

@@ -20,6 +20,7 @@ import type {
   LayerChunkProgressInfo,
 } from "#src/chunk_manager/base.js";
 import {
+  CHUNK_SOURCE_INVALIDATE_CHUNKS_RPC_ID,
   CHUNK_LAYER_STATISTICS_RPC_ID,
   CHUNK_MANAGER_RPC_ID,
   CHUNK_QUEUE_MANAGER_RPC_ID,
@@ -1110,8 +1111,10 @@ export class ChunkQueueManager extends SharedObjectCounterpart {
     }
   }
 
-  invalidateSourceCache(source: ChunkSource) {
-    for (const chunk of source.chunks.values()) {
+  invalidateCachedChunks(source: ChunkSource, keys: string[]) {
+    for (const key of keys) {
+      const chunk = source.chunks.get(key);
+      if (!chunk) continue;
       switch (chunk.state) {
         case ChunkState.DOWNLOADING:
           cancelChunkDownload(chunk);
@@ -1123,6 +1126,10 @@ export class ChunkQueueManager extends SharedObjectCounterpart {
       // Note: After calling this, chunk may no longer be valid.
       this.updateChunkState(chunk, ChunkState.QUEUED);
     }
+  }
+
+  invalidateSourceCache(source: ChunkSource) {
+    this.invalidateCachedChunks(source, [...source.chunks.keys()]);
     this.rpc!.invoke("Chunk.update", { source: source.rpcId });
     this.scheduleUpdate();
   }
@@ -1378,6 +1385,12 @@ registerRPC(CHUNK_SOURCE_INVALIDATE_RPC_ID, function (x) {
   source.chunkManager.queueManager.invalidateSourceCache(source);
 });
 
+registerRPC(CHUNK_SOURCE_INVALIDATE_CHUNKS_RPC_ID, function (x) {
+  const source = <ChunkSource>this.get(x.id);
+  source.chunkManager.queueManager.invalidateCachedChunks(source, x.keys);
+  source.chunkManager.queueManager.scheduleUpdate();
+});
+
 registerPromiseRPC(
   REQUEST_CHUNK_STATISTICS_RPC_ID,
   function (x: { queue: number }) {

src/chunk_manager/base.ts

@@ -100,6 +100,8 @@ export const PREFETCH_PRIORITY_MULTIPLIER = 1e13;
 export const CHUNK_QUEUE_MANAGER_RPC_ID = "ChunkQueueManager";
 export const CHUNK_MANAGER_RPC_ID = "ChunkManager";
 export const CHUNK_SOURCE_INVALIDATE_RPC_ID = "ChunkSource.invalidate";
+export const CHUNK_SOURCE_INVALIDATE_CHUNKS_RPC_ID =
+  "ChunkSource.invalidateChunks";
 
 export const REQUEST_CHUNK_STATISTICS_RPC_ID =
   "ChunkQueueManager.requestChunkStatistics";

src/chunk_manager/frontend.ts

@@ -19,6 +19,7 @@ import type {
   LayerChunkProgressInfo,
 } from "#src/chunk_manager/base.js";
 import {
+  CHUNK_SOURCE_INVALIDATE_CHUNKS_RPC_ID,
   CHUNK_LAYER_STATISTICS_RPC_ID,
   CHUNK_MANAGER_RPC_ID,
   CHUNK_QUEUE_MANAGER_RPC_ID,
@@ -463,6 +464,26 @@ export class ChunkSource extends SharedObject {
     this.chunks.delete(key);
   }
 
+  invalidateChunks(keys: string[]): void {
+    const validKeys: string[] = [];
+    for (const key of keys) {
+      const chunk = this.chunks.get(key);
+      if (chunk) {
+        validKeys.push(key);
+        this.deleteChunk(key);
+      }
+    }
+
+    if (validKeys.length > 0) {
+      this.rpc!.invoke(CHUNK_SOURCE_INVALIDATE_CHUNKS_RPC_ID, {
+        id: this.rpcId,
+        keys: validKeys,
+      });
+
+      this.chunkManager.chunkQueueManager.visibleChunksChanged.dispatch();
+    }
+  }
+
   addChunk(key: string, chunk: Chunk) {
     this.chunks.set(key, chunk);
   }

src/chunk_worker.bundle.js

@@ -12,3 +12,4 @@ import "#src/annotation/backend.js";
 import "#src/datasource/enabled_backend_modules.js";
 import "#src/kvstore/enabled_backend_modules.js";
 import "#src/worker_rpc_context.js";
+import "#src/voxel_annotation/backend.ts";

src/datasource/index.ts

@@ -132,6 +132,8 @@ export interface DataSubsource {
   singleMesh?: SingleMeshSource;
   segmentPropertyMap?: SegmentPropertyMap;
   segmentationGraph?: SegmentationGraphSource;
+  // specify whether the datasource & kvstore implementations supports writing, is also responsible for showing the enableWriting checkbox in the UI
+  isPotentiallyWritable?: boolean;
 }
 
 export interface CompleteUrlOptionsBase extends Partial<ProgressOptions> {
@@ -216,6 +218,7 @@ export interface DataSourceWithRedirectInfo extends DataSource {
 
 export interface DataSubsourceSpecification {
   enabled?: boolean;
+  writingEnabled?: boolean;
 }
 
 export interface DataSourceSpecification {

src/datasource/zarr/async_computation.ts

@@ -1,2 +1,3 @@
 import "#src/async_computation/decode_blosc.js";
 import "#src/async_computation/decode_zstd.js";
+import "#src/async_computation/encode_blosc.js";