{
  "name": "napari-label-assistant",
  "display_name": "napari-label-assistant",
  "visibility": "public",
  "icon": null,
  "categories": [],
  "schema_version": "0.3.0",
  "on_activate": null,
  "on_deactivate": null,
  "contributions": {
    "commands": [
      {
        "id": "napari-label-assistant.simple_curation",
        "title": "Label Curation — Simple",
        "python_name": "napari_label_assistant_tools._label_assistant:open_simple_curation",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-label-assistant.advanced_curation",
        "title": "Label Curation — Advanced",
        "python_name": "napari_label_assistant_tools._label_assistant:open_advanced_curation",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-label-assistant.label_assistant",
        "title": "Label Curation",
        "python_name": "napari_label_assistant_tools._label_assistant:label_assistant_widget",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-label-assistant.quick_train",
        "title": "Model Training",
        "python_name": "napari_label_assistant_tools._quick_train_widget:quick_train_widget",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      },
      {
        "id": "napari-label-assistant.model_library",
        "title": "Model Library",
        "python_name": "napari_label_assistant_tools._model_library_widget:model_library_widget",
        "short_title": null,
        "category": null,
        "icon": null,
        "enablement": null
      }
    ],
    "readers": null,
    "writers": null,
    "widgets": [
      {
        "command": "napari-label-assistant.label_assistant",
        "display_name": "Label Curation",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      },
      {
        "command": "napari-label-assistant.quick_train",
        "display_name": "Model Training",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      },
      {
        "command": "napari-label-assistant.model_library",
        "display_name": "Model Library",
        "autogenerate": false,
        "default_dock_area": "right",
        "tabify": false
      }
    ],
    "sample_data": null,
    "themes": null,
    "menus": {
      "napari/plugins": [
        {
          "when": "True",
          "group": null,
          "submenu": "napari-label-assistant.main"
        }
      ],
      "napari-label-assistant.main": [
        {
          "command": "napari-label-assistant.simple_curation",
          "when": "True",
          "group": null,
          "alt": null
        },
        {
          "command": "napari-label-assistant.advanced_curation",
          "when": "True",
          "group": null,
          "alt": null
        },
        {
          "command": "napari-label-assistant.quick_train",
          "when": "True",
          "group": null,
          "alt": null
        },
        {
          "command": "napari-label-assistant.model_library",
          "when": "True",
          "group": null,
          "alt": null
        }
      ]
    },
    "submenus": [
      {
        "id": "napari-label-assistant.main",
        "label": "napari-label-assistant",
        "icon": null
      }
    ],
    "keybindings": null,
    "configurations": {}
  },
  "package_metadata": {
    "metadata_version": "2.4",
    "name": "napari-label-assistant",
    "version": "7.0.3",
    "dynamic": [
      "license-file"
    ],
    "platform": null,
    "supported_platform": null,
    "summary": "Performance-aware 2D mask annotation, component curation, and grid-addressed quality control",
    "description": "# napari-label-assistant\n\n**Performance-aware 2D mask annotation, connected-component curation, and\ntraceable spatial review—from ordinary images to datasets approaching\n100,000 × 100,000 pixels.**\n\nnapari-label-assistant connects the complete mask-development workflow:\nannotate at full resolution, inspect connected components, collect accepted\nregions into a curated Labels layer, review the result by reproducible grid\naddress, correct reported locations, and resume the project later.\n\nThe plugin is model-agnostic. Candidate masks can come from manual annotation,\nSAM3, or another segmentation workflow. The final curated layer can then be\nused for training, measurement, quantification, or export.\n\n![Simple mode showing a microscopy image, curated mask, reviewed regions, annotation batches, and the fixed progress summary](docs/simple-mode-gui.png)\n\n**Simple mode in napari:** the fixed top summary keeps task progress, confirmed\ntiles, and batch counts visible without scrolling. Purple outlines show the\nactive batch's approved regions. [View full-size screenshot](docs/simple-mode-gui.png).\n\n![Plugin purpose: curate and review masks, then measure or optionally train models](docs/purpose-flowchart.png)\n\n[Open the editable purpose flowchart](docs/purpose-flowchart.svg).\n\nSee the [system design map](docs/system-design.md) for the architecture,\nsource-module responsibilities, and data flow\n([PNG](docs/system-design.png) · [editable SVG](docs/system-design.svg)).\n\n## Simple annotation workflow\n\nOpen **Plugins → napari-label-assistant → Label Curation — Simple** for a\ncompact tile workflow. **Label Curation — Advanced** opens the same dock with\n**Workspace** and **Labels** tabs. **Plugins → napari-label-assistant → Model\nTraining** opens the independent training dock. Switching modes preserves masks\nand pending selections; training shortcuts reuse the same model and dataset.\n\nThe fixed top summary stays visible in both modes:\n\n- **Annotation:** confirmed tiles, pending selections, and the active batch's reviewed count.\n- **Current task:** progress for loading, saving, analysis, mask edits, and model work; **Stop** when supported.\n- **Feedback:** brief completion messages, persistent failures, and **⋯** for recent task details.\n\nIts height stays stable during updates. Section 3 retains batch controls and dataset details.\n\n1. **Workspace:** open a project, or save a new one once to establish durable\n   mask storage and tile-progress recovery.\n2. **Annotate & Review:** choose an aligned image and mask, set the review-tile\n   size, and paint or erase in **Edit** mode. Camera follow loads bounded\n   full-resolution areas when zoomed in; zooming out provides a read-only overview.\n   **Reviewed & Next** approves the current tile and visits the next unreviewed\n   tile. Approve only after checking every target and the remaining background.\n3. To select several checked tiles, choose **Review — select tiles** and click\n   their grid cells. Click again to deselect, then **Approve selected tiles**.\n   Approved coverage remains visible in color. Yellow selection alone does not\n   approve annotations. **Skip** visits the next unreviewed tile without changing\n   pending selections. Return to **Edit** to paint.\n4. **Progress & Dataset:** inspect coverage, prepare the dataset, and open Training.\n   Preparation reuses existing training settings; patch size remains independent\n   of review-tile size and the camera-follow edit buffer.\n   **Training amount…** opens the percentage/count controls for quick trials.\n\n**Annotation batch buttons** live in Simple **3. Progress & Dataset**, Advanced\n**Labels → Local Editing → Confirm tiles for dataset**, and **Training → Dataset**.\nThey share batch settings per image/mask pair. Click **+ New batch** before starting\nthe next annotation stage: the new batch starts empty and is selected for training.\nSubsequent approvals join it. Batch buttons select\nthe active batch for annotation and viewing; they leave the training dropdown\nunchanged. Choose **Training: Batch N** explicitly for preparation, or\n**Training: all reviewed annotations** for cumulative data.\nGlobal reviewed coverage keeps increasing independently of batch membership.\nEach batch keeps its own color, matching its button marker. **Show: Active batch /\nAll batches / Hide** controls the coordinate overlay independently of training.\nApproved regions keep their colors automatically; earlier batches are dimmed in\nAll batches, with active-batch priority at overlaps. Yellow marks pending tiles;\na red × flags batch regions that need review again after edits or revocation.\nRight-click a button to add existing reviewed selections, remove membership,\nrename, finish/reopen, or inspect dated review actions and recorded training use.\nAn empty batch disables preparation. Existing review coverage is retained as\nBatch 1 when batches are first initialized; missing historical approval dates\nremain unknown. Existing workspaces retain cumulative training by default.\n\nTo continue a model with new annotations, create the next batch, review its\nregions, prepare that batch, select the saved model, and choose **Continue\ntraining**. Earlier holdout regions remain reserved, and batch selection/version\nis recorded with the training run. Membership is stored as coordinates without\ncopying the full image/mask. Historical runs retain their input fingerprints and\ncoordinates; batches do not freeze old annotation pixel values.\n\nPending selections use a light yellow fill and a border kept approximately three\nscreen pixels wide, so selected tiles remain noticeable when zooming out.\nTile selection saves show a busy indicator and a saved/error status. Approval,\nrevocation, and review undo show the actual completed tile count; stopping a batch\nretains its partial count rather than displaying full completion.\n\nCollapsed **Tools** includes clearing pending selection, revoking selected/current\nor all reviewed areas for the chosen image/mask pair, and undoing the last review\naction. Painting invalidates affected approval and review undo; recorded past\ntraining use remains visible. Existing comparison, composition, component screening,\nand workspace options remain accessible in Advanced.\n\nAfter the first workspace save, pending selections and review metadata are\nrecorded automatically in a small `tile-progress.json` inside the workspace data\nfolder. Mask pixels use the existing bounded write/recovery mechanism. This is\ntile-progress recovery, not a replacement for **Save**: save added layers, models,\nand other project settings normally. Recovery is tied to the saved manifest and\nmatching source stores; incompatible records are reported and left unapplied.\nKeep the JSON project and its data folder together. Existing workspaces remain\ncompatible; editing alone never confirms background.\n\n## Version 7.0.3: Progress always in view\n\n- Keep task progress and annotation counts in the fixed top summary, without scrolling.\n- Follow active work without routine viewer updates replacing its message.\n- Stop supported tasks, inspect recent activity, and see failures until dismissed or retried.\n- Updated GUI screenshot above shows the current layout.\n\n### Earlier: Independent Model Training dock (7.0.2)\n\n- Advanced Label Curation focuses on **Workspace** and **Labels**.\n- Open **Model Training** from the plugin submenu or curation shortcuts as its\n  own dock, sharing the current model, dataset, and annotation batches.\n- Opening Training from Simple mode keeps Simple mode selected. **Edit & Confirm**\n  returns to Labels; dataset and Model Library shortcuts reveal the same trainer.\n\n### Earlier: Continue across sessions and optional two-node training (7.0.1)\n\n- Reopening a saved workspace reloads the previously active model checkpoint,\n  making continuation on the next annotation batch available after preparation.\n- Optionally train one Custom small U-Net across two CUDA computers through\n  **Training → Train → Training compute**, using an existing SSH connection.\n  Coverage training with holdout validation supports fresh training and continuation.\n- Keep **This computer** as the default in every new Training panel. Worker\n  connection settings stay on your computer and are excluded from shared workspaces.\n- Check both nodes before submitting; view progress, cancel jobs, and receive the\n  resulting model in the existing library. Each node needs enough memory for its\n  full model copy; two nodes do not automatically provide twice the speed.\n- See [two-node setup](docs/model-management.md#optional-two-node-training) and\n  [release notes](CHANGELOG.md#701---2026-11-19).\n\n### Earlier: Simple curation and annotation batches (7.0.0)\n\n- Choose Simple or Advanced mode, sharing the same annotations and review state.\n- Edit bounded mask areas and approve review tiles from the Simple workflow.\n  Recover pending selections and tile progress after reopening a saved workspace.\n- Organize reviewed regions into named batches with persistent colors, review\n  history, and independent display and training selections.\n- Prepare all eligible training patches or a reproducible percentage/count subset.\n  Quick trials can also sample validation while retaining reserved holdout regions.\n- Configure wider U-Nets, retain existing checkpoint architectures when continuing,\n  and save models with readable automatic filenames and training provenance.\n- Preserve existing workspace and checkpoint compatibility, with bounded operations\n  for large disk-backed masks. See [release notes](CHANGELOG.md#700---2026-11-19).\n\n### Earlier: tile confirmation and whole-mask analysis (6.4.0)\n\n- **Edit & Confirm:** retain camera-follow painting, bounded edit crops, undo/redo,\n  and save/load. Confirm fully reviewed tiles, including objects and checked\n  background, from the same panel. Unconfirmed areas remain excluded from training.\n- **Mask Analysis & Cleanup:** **Find components** defaults to **Entire mask —\n  full resolution**, independent of zoom. Stream OME-Zarr `s0` in bounded chunks,\n  join components across chunk boundaries, and inspect the population in the\n  sortable table. **Current edit area** remains available for local searches.\n- **Global cleanup with recovery:** locating, picking, copying, noise filtering,\n  and undo use full-image coordinates without loading the complete mask into RAM.\n- **Simpler partial-training preparation:** Dataset displays confirmed-tile counts,\n  editor navigation, and training/validation overlays. Missing single-image review\n  associations recover automatically; older foreground-only selections stay under\n  advanced controls. Edits require rechecking affected approvals.\n- **Reliable coverage and shutdown:** preparation respects exact saved approval\n  rectangles, viewing-crop navigation preserves unchanged prepared datasets, and\n  closing the app no longer triggers review callbacks against a deleted canvas.\n\nFull read-only validation of one **49,976 × 59,716** curated mask found **16\nconnected components** in approximately **30 seconds** in the validation\nenvironment. This is a dataset-specific measurement, not a general performance\nguarantee. See [whole-mask validation](validation_reports/17_entire_mask_analysis.md).\n\n### Existing automatic editing and loading\n\n- **Automatic camera-follow editing:** keep complete Zarr masks on disk and\n  zoom in to paint bounded full-resolution areas. **Edit at View Center** stays\n  visible; editing modes and grid navigation are under collapsed **Advanced**.\n- **Fast opening for older workspaces:** saved full-mask loading settings now\n  migrate to bounded loading before napari constructs the Labels layers. Opening\n  leaves the original JSON and masks unchanged; the next Save records the new mode.\n- **Bounded whole-mask display:** use Spatial Assistant's overview policy to\n  expose only GPU-safe pyramid levels, preserving source alignment, colors, and\n  full-resolution edit crops. Resolution locks cannot expose the full mask.\n- **Simpler annotation and training controls:** main tabs are **Workspace,\n  Labels, Training**. Review stays in Edit & Confirm, with collapsible View &\n  Compare and Label Tools. Dataset summarizes supervision and preparation state;\n  component selections live under **Advanced: saved object selections and coverage**.\n- **Full-source label tools:** relabel, merge, compose, vote, and consensus\n  operations stream disk-backed masks in bounded tiles. Results keep full image\n  dimensions and become durable with workspace Save.\n- **Existing annotation protections:** changed-region writes, interrupted-write\n  recovery, external-edit conflict checks, complete affine transforms, source\n  label IDs, and binary/multiclass/multilabel training remain supported.\n- **Validation evidence:** see the [audit and follow-up reports](validation_reports/README.md)\n  for executed tests, remaining findings, and limits. Large logical dimensions\n  do not imply every operation fits in memory or that full-image performance\n  has been benchmarked on ordinary computers.\n\n### Overlapping multilabel masks\n\nTraining now supports three annotation formats:\n\n| Format | Annotation layers for each image | Prediction |\n|---|---|---|\n| Binary | One mask: background 0, target 1 (existing instance IDs also become foreground) | One foreground mask |\n| Exclusive multiclass | One mask: background 0, named classes 1, 2, … | One class ID per pixel |\n| Overlapping multilabel | One binary 0/1 mask per named feature | Separate masks that can overlap |\n\nFor a macrophage and its organelles, create aligned **cell**, **mitochondria**,\n**nucleus**, and other binary mask layers. Paint the whole cell including its\norganelles in the cell mask. In **2. Models**, choose **Separate masks —\noverlapping channels**, then open **1. Dataset → Manage channels…**. Name the\nfeatures directly in that dialog and assign their masks. For one image, **Use\nmask layers as channels** fills the names/assignments from the existing Labels\nlayers and includes the image. You do not need to rename the layers. Names can\nalso be entered in Models. Do not combine overlapping masks into one integer\nlayer. Existing trained tasks are preserved by creating a separate task when the\nchannel definition changes.\n\n**Foreground pixels → Binary 0/1** requires binary targets. Choose **Any nonzero\nID** when a mask contains object IDs such as 2, 3, and 4 that all represent the\nsame feature. The one-image shortcut chooses this explicitly displayed mode;\ntraining reads a binary view without modifying the original labels.\n\nChoose **Complete** only when that channel is fully annotated, **Partial** with\nits associated reviewed-region mask, or **Unknown / not annotated** when its\nlabels are absent on an image. Unknown pixels do not become background. Prepare\nthe dataset and train with **All patches**. One image reserves spatial groups;\nseveral images reserve entire image/specimen groups. Each split needs known\npositive and negative examples for every channel.\n\nInference thresholds each channel independently and creates separate named\nLabels layers. A pixel can belong to both cell and mitochondria. This supports\noverlap but does not enforce containment or assign organelles to cell instances.\nChannel definitions, assignments, checkpoints, and output metadata persist with\nthe workspace. Existing one-mask workflows remain available.\n\n## Multiple-image datasets, multiclass training, and tiled inference\n\n- **Train across image–label pairs:** in **1. Dataset → Advanced source options**, choose **Multiple images**\n  and open **Manage pairs…**. Select pairs, configure annotation coverage per\n  image, and keep related images in the same specimen/split group. The table\n  opens separately, and review controls remain collapsed until needed.\n- **Learn separate tissue classes:** define foreground classes such as\n  `axon, myelin` on a new biological task. Labels use `0` for background and\n  `1`, `2`, … for the named classes, up to 254 foreground classes. Class names\n  persist with checkpoints, and validation reports per-class Dice/IoU. Empty\n  class definitions preserve binary foreground/background training.\n- **Predict more than one crop:** **4. Inference** offers **Current area**,\n  **Entire image**, and **Drawn box**, with overlapping tiled prediction,\n  progress, and cancellation for larger regions.\n- **Save replaced labels reliably:** saving a NumPy replacement of a previously\n  Zarr-backed Labels layer persists its current pixels instead of failing on a\n  stale storage reference. Prediction class metadata also survives workspace saves.\n\nPair selections use stable layer IDs and persist in the workspace. Suggested\npairs require explicit inclusion; predictions require review confirmation before\nbeing used as ground truth. Existing single-pair datasets, binary checkpoints,\nbiological tasks, and Model Library records remain supported. See the\n[changelog](CHANGELOG.md) for release details and the training guide below for\nthe complete workflow.\n\n## Model Library and workspace file management\n\nThe plugin menu provides:\n\n- **Label Curation — Simple / Advanced** — two presentations of one shared\n  annotation dock, for tile review or the full editing and analysis controls.\n- **Model Training** (formerly Quick Train) — prepare datasets, configure models,\n  train, validate, and predict.\n- **Model Library** — organize models and checkpoints, document training runs,\n  and compare recorded results across models. The Models page in Model Training\n  also provides an **Open Model Library** shortcut.\n\nModel Library shares the workspace's existing records; browsing does not load\nmodel weights. **Models** lists model families and their latest recorded runs.\n**Training History** shows one row per recorded run/checkpoint, with its own\nscores, architecture, dataset snapshot, settings, duration, and file availability.\nUse **Edit selected model / run documentation** to name a model or dataset, add\nrun notes and tags, or mark a favorite. Save the workspace to persist these edits.\n\nSearch and filter by task or dataset. **More filters** includes favorites,\nmaximum parameter count in millions, and matching dataset/validation provenance.\n**Show all history columns** exposes training settings, annotation coverage,\npatch counts, source layers, checkpoint paths, and stable identifiers. Older\nrecords with missing information display an unknown value rather than borrowing\nthe latest checkpoint's results.\n\nSelect multiple history rows with Ctrl/Shift-click and choose **Compare selected\nruns**. Available charts show validation metrics, score versus parameter count,\nresults in date order, and learning curves. Export history as CSV and charts as\nSVG or PNG. The library assigns a best recorded score only when the selected runs\nshare recorded dataset and validation provenance; other comparisons are labeled\nexploratory. Validation-selected scores are not independent test-set results.\nParameter count describes model size, not measured inference speed or memory use.\n\n**Select checkpoint** shares that checkpoint with Model Training for continuation\nor inference, opening the training panel if needed. **Import checkpoint** adds an\nexisting plugin checkpoint through the training loader. **Inspect loaded weights**\nshows tensor shapes, parameter counts, and bounded-sample statistics with CSV\nexport. Inspection requires explicit weight loading; weight statistics do not\nmeasure prediction quality. Learning curves read existing in-memory history or\nJSON sidecars, and are reported unavailable when neither is present.\n\n### Workspace-owned model files\n\nThe workspace is the catalog for its images, annotations, models, and results.\n**Search workspace** filters registered model/run records, including checkpoint\npaths and file status. It does not scan folders, discover unregistered `.pt`\nfiles, or search the **Recent workspaces** list. Open the relevant workspace\nfirst; its model records are restored without loading networks.\n\nIn Model Library, expand **Model files and workspace locations** to see the\nworkspace manifest, managed-model folder, selected checkpoint path, and counts\nof **Managed**, **Linked externally**, **Missing**, and **Unsaved** checkpoints.\nUse **More filters → File status** to find missing or externally linked files.\nThe Workspace panel's **Open Model Library** shortcut opens this same catalog.\n\n```text\nMyProject/\n├── MyProject.label-assistant.json\n└── MyProject_label_assistant_data/\n    ├── models/       # checkpoints, histories, metrics, and learning charts\n    ├── comparisons/  # saved comparison reports\n    └── …             # managed image/annotation assets\n```\n\n- **Managed** files are saved inside this workspace's models folder.\n- **Linked externally** files remain at their recorded external locations.\n  **Copy into workspace** copies a selected checkpoint and its available history,\n  metrics, and chart files into managed storage while preserving the originals.\n  Existing bundles are not overwritten; copying runs in the background.\n- **Missing** files can be repaired with **Locate missing file**. The selected\n  file is checked against the model identity, configuration, recorded training\n  history, and scores before the run reference is changed. A different model or\n  checkpoint revision must be imported separately.\n- **Unsaved** weights must be persisted with Workspace Save before copying.\n\n**Save the workspace after copying or locating a file** to persist its updated\nreferences. These actions preserve model/run identities, notes, and history;\nthey do not add another training run or move source files. A workspace change\nduring an operation prevents its result from modifying the newly opened catalog.\n**Open models folder** opens the managed folder in the desktop file manager.\nImages may remain linked externally; making model files managed does not copy\nlarge image datasets or make the entire workspace portable. Use **Include all\ndata (portable)** when the entire workspace needs to move between computers.\n\n## Prepared datasets and checkpoint selection\n\n- Selecting an existing model or loading a checkpoint now retains a compatible\n  prepared dataset, so **Train new model** remains available without repeating\n  preparation. The current dataset's validation settings and partition stay intact.\n- Checkpoints that previously trained in the reserved validation regions cannot\n  continue training against that holdout; training a new model remains available.\n- Both **Prepare dataset → select model → train** and **select model → prepare\n  dataset → train** are supported. After changing annotations, sources, or dataset\n  settings, prepare the dataset again.\n\n### Annotation and review workflow\n\n- Finish a cell with **Confirm tile & next** directly in Edit & Confirm; move\n  to the next unreviewed cell without switching to Training.\n- See the shared image/annotation pair in editing and training, with associations\n  remembered in workspace metadata and clear training/prediction prerequisites.\n- Preview cleanup counts and use **Undo last deletion** for component deletion\n  and cleanup, including disk-backed masks. Recovery preserves later nonzero\n  edits and lasts until another deletion starts or the panel closes.\n- Distinguish applied mask edits from saved workspace settings, with visible\n  change tracking and successful save/open timestamps.\n\nTraining and model management also support these workflows:\n\n- Follow five Training pages: **Dataset**, **Models**, **Train**, **Inference**,\n  and **Advanced**. Prepare datasets separately from optional patch previews.\n- Combine fully reviewed cells with selected component foreground. Persistent\n  library IDs and selections survive workspace saves and reopening.\n- Choose the existing custom U-Net, standard U-Net, optional SMP architectures,\n  or registered custom providers; organize checkpoints and compare models.\n- Evaluate with spatial holdout or independent spatial k-fold validation, inspect\n  learning curves, and export models and reports.\n- Configure augmentation, learning-rate reduction, and early stopping. Use batch\n  sizes up to 128, source patches up to 4096, and model inputs up to 2048.\n- Save model weights and per-run checkpoints with the workspace; complete-package\n  Save As includes model assets and reports. Older workspaces remain readable.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the complete release notes.\n\n## Workflow at a glance\n\n1. **Edit & Confirm:** create, extend, erase, or reshape labels at full\n   resolution through a memory-controlled editable area when needed.\n2. **Inspect:** analyze each nonzero label value as one or more connected\n   components and sort the results by size, topology, position, or grid\n   address.\n3. **Curate:** remove artifacts and copy accepted components from candidate\n   masks into a curated destination Labels layer.\n4. **Review:** register findings with grid addresses such as **R12C08**, so an\n   independent reviewer and annotator can refer to the same location.\n5. **Correct and resume:** return to a reported cell, update the source mask,\n   save the project, and continue later with the same layer and viewer state.\n\n## Everyday workflow shortcuts\n\n- **Labels → Edit & Confirm** shows the image and annotation pair shared with\n  Training. After checking every object and the background in a selected grid\n  cell, use **Confirm tile & next** to include it in training and move to the\n  next unreviewed cell. Navigation wraps at the end of the image.\n- Training shows the missing prerequisites for training and prediction. Image\n  and annotation associations are remembered in workspace metadata.\n- Component cleanup previews the number of components and pixels affected.\n  **Undo last deletion** restores the most recent component deletion or cleanup,\n  including on disk-backed masks, while preserving subsequent nonzero edits.\n  This recovery is available until another deletion starts or the panel closes.\n- Applied paint edits update the source mask. **Workspace Save** preserves the\n  project and its settings separately; the Workspace panel shows recorded changes\n  and the time of the latest successful save or open.\n\n## Connected-component inquiry and curation\n\nThe component table turns a segmentation mask into an inspectable set of\nregions. It is designed to remain usable when the mask contains many\ncomponents and the full image is too large for naive in-memory analysis.\n\n- Detect connected components independently within each nonzero label value.\n- Sort by label value, pixel count, Euler number, centroid, bounds, or grid\n  address.\n- Double-click a table row to locate its component on the canvas.\n- Click a labeled region on the canvas to select its table row; optionally add\n  successive clicks to a multi-component selection.\n- Delete noise and other unwanted regions individually or in batches.\n- Copy accepted components individually or in batches to a compatible curated\n  destination Labels layer.\n\nEuler number provides a compact 2D topology check: `1` indicates a solid\ncomponent with no holes, `0` indicates one hole, and `-1` indicates two holes.\nCombined with area sorting, this helps distinguish small artifacts, solid\nblobs, ring-like structures, and components that merit closer inspection.\n\nComponent IDs identify results within the current analysis. Editing the mask\nand running the analysis again may change those IDs. Grid addresses provide\nthe reproducible spatial reference used across review sessions.\n\n### Candidate and curated Labels layers\n\nA practical workflow uses two roles rather than requiring every segmentation\nresult to be edited in place:\n\n- **Candidate layers** contain model predictions, partial masks, or regions\n  awaiting review.\n- **Curated destination layers** collect accepted annotations for downstream\n  training, measurement, quantification, or export.\n\nCandidate regions produced by SAM3 are one example, but the same workflow\nworks with any compatible napari Labels layer. Users can inspect candidates\nvisually, select them from the table or canvas, and copy only accepted regions\ninto the curated layer.\n\n## 100,000 × 100,000-pixel workflows\n\n**Automatic mask loading now keeps large 2D Zarr masks outside napari's layer\nlist.** Open the existing workspace normally: the multiscale image remains\navailable, while Curated and review masks appear as editable 1024 × 1024 crops.\nThe complete masks stay in their original on-disk stores; no manual crop files\nor final stitching step is needed.\n\nUnder **Labels → Edit & Confirm → Mask editing**, zoom in and paint. New\nworkspaces use bounded editing with camera follow by default; no editing-mode\nchoice is needed. **Edit at View Center** remains visible for manual control.\nThe collapsed **Advanced** section contains the editing-mode selector, camera\nfollow toggle, and grid controls: 512–4096-pixel tile sizes, zero-based row/column\naddresses, **Go**, **Previous**, **Save & Next**, and **Save navigation progress**. Older projects\nsaved with full-mask loading now open through bounded crops automatically.\nOpening a project does not rewrite its JSON or masks; the next Workspace Save\nrecords the bounded mode. An explicit editing-mode choice in Advanced takes\nprecedence for the current session. Saved camera-follow preferences are retained.\nSmall in-memory masks can still be painted directly before their first save.\n\nCamera follow loads full-resolution edit windows as you zoom in and pan.\nWindows use at most 4096 × 4096 pixels,\nwith a combined mask read limit of 128 MiB. Zooming out switches to a read-only\noverview. Following waits for strokes and navigation drags to finish and saves\npending edits through the same recovery journal before changing the area.\n**Edit at View Center** and the grid navigation buttons remain available;\nautomatic following resumes when the view changes. Workspace Save remembers\nthe follow setting. Differently registered masks require manual navigation;\nautomatic following pauses with an explanation and retains the current buffers\nif loading or saving fails.\n\nMask overviews follow Spatial Assistant's display policy: napari receives only\npyramid levels within the GPU texture limit, capped at 4096 pixels per axis and\n64 MiB per level. An 80,000 × 80,000 mask uses the 2500 × 2500 and smaller\nlevels on a GPU that supports 4096-pixel textures. Full-resolution editing stays\nin the local crop. Overview coordinates, crop exclusion, and label colors remain\naligned; the display policy also applies when previews are rebuilt after Save.\n\nEdits, including erasures, update only their changed bounding region in the full\nmask. Writes use a bounded recovery journal and reject conflicting external\nedits or out-of-range label values. Paint changes normally flush after a short\nidle delay, and saving/navigating/closing also flushes pending edits. If storage\nfails, retain the reported recovery files and resolve the error; unresolved\nconflicts are not silently overwritten. Undo history is local to the active tile\nand is reset when its pixel buffer is replaced.\nUse one editing session per mask store; conflict checks are not a multi-user\nlocking protocol.\n\n**Include all data (portable)** still copies the complete source masks, not only\nthe visible crops. New aligned masks matching the active tile are backed by\nsparse full-size stores and become durable with workspace Save. Full-image\ntraining reads the backing masks rather than mistaking the displayed crop for\nthe dataset. Component analysis defaults to the entire full-resolution mask;\nthe optional current-area mode describes only that crop, where boundary objects\nmay continue into neighboring areas. The training component\nlibrary still scans the full backing mask in bounded chunks, and selecting a\nlibrary object loads its tile. After checking a review tile, confirm it under **Edit & Confirm → Confirm tiles\nfor dataset**. Confirmation includes annotated objects and checked background;\nunconfirmed regions remain excluded. Approval uses sparse full-size coverage and\nbounded writes. Save the workspace to preserve it.\n**Save navigation progress** records navigation only. Review-tile height and width\ndo not change the separate **Editable tile size**, which supports custom sides up\nto 4096 pixels and camera following. Green outlines show approval; blue outlines\nshow historical training use. Editing invalidates approval without erasing that\nhistory.\n\nThis path applies to 2D Zarr Labels stores. It reduces mask display/working memory;\nsource chunk sizes, storage speed, image rendering and other analyses still\naffect responsiveness. It does not establish a hardware-independent performance\nguarantee or remove full-image inference's output-memory requirements.\n\nA 100,000 × 100,000 label mask contains 10 billion pixels. Default bounded\nediting keeps the source store outside napari's editable layers, displays a\nsmall overview, and loads only a camera-centered crop for full-resolution edits.\n\nAt this scale, the source should use an efficiently sliceable, preferably\nchunked or on-disk array such as Zarr. Actual responsiveness depends on array\nstorage, chunk geometry, data type, disk performance, available memory, and\nhardware. The numeric scale describes the intended workflow, not an\nunconditional hardware-independent limit.\n\n## Interface\n\nAdvanced curation has two main tabs: **Workspace** and **Labels**.\nLabels contains **Edit & Confirm** and **Mask Analysis & Cleanup**.\n**Model Training** opens as an independent dock from the plugin submenu or\n**Open Training** in Simple mode. Both entry points share the same dataset,\nannotation batches, and loaded model.\n\n### Workspace\n\nOpen **Plugins → napari-label-assistant → Label Curation**, then use the first\n**Workspace** tab to create, open, and save a complete annotation workspace\nwithout SAM3 Assistant.\n\n- A normal save writes a small `.label-assistant.json` manifest.\n- **Optimize large images** optionally creates a local, chunked\n  multiscale OME-Zarr pyramid for single-scale images larger than 32,768\n  pixels on either axis. The original file remains unchanged; the saved\n  pyramid is activated automatically after a successful save. Leave the\n  option off to keep lightweight links to the original image files.\n- New in-memory Labels layers are persisted once as writable, chunked\n  OME-Zarr data beside the manifest. Later saves reuse the same store instead\n  of copying the full mask again.\n- **Data storage for next save → Include all data (portable)** saves every image\n  and mask into the data folder beside the manifest with relative paths. Select it and\n  use **Save As** in an empty folder, then transfer that **entire folder** to\n  another computer. Open the manifest there; original source paths and reader\n  plugins are no longer needed. It also supports fileless and multiscale images\n  and can be combined with image optimization. Allow time and disk space for\n  copying full datasets.\n- Saved image copies become the live data source after the save succeeds;\n  no close/reopen is needed before using **Link to source data** for fast\n  follow-up saves. Repeated saves to the same portable package also reuse its\n  existing image stores. **Save As** to a different destination still creates\n  independent mask copies, and includes image copies when portable mode is on.\n- With **Link to source data** selected, **Save As** to a new destination creates writable mask copies beside the\n  new manifest, including masks opened read-only from shared mounts. Images\n  remain linked; keep the shared mount available when reopening locally.\n  Saving to the current project path reuses its existing mask stores.\n- Saving displays progress; failures show an error dialog and keep the previous\n  active project selected.\n- Source images already loaded from files remain external references, keeping\n  routine saves fast. **Portable Snapshot** explicitly copies referenced local\n  images and masks into one folder for transfer.\n- Pending local-area edits are applied to the source Labels layer before the\n  project is saved.\n- The JSON file is a lightweight project manifest rather than a container for\n  the full image. Large mask pixels remain in writable OME-Zarr storage.\n- A recent project is not treated as the active Save destination for unrelated\n  viewer contents. Before a manifest is overwritten, its previous version is\n  retained as a `.backup.json` file.\n- Grid cell dimensions and grid display/assignment choices are restored with\n  each Labels layer.\n- Opening a project displays layer-by-layer progress in a temporary dialog;\n  the dialog closes automatically when loading succeeds or fails.\n- Temporary editable-area, editable-boundary, and grid-overlay layers are not\n  stored; the plugin recreates them when needed.\n\nExisting `.sam3.json` projects created by SAM3 Assistant can be opened for\nmigration. Use **Save As** to continue with the standalone `napari-label-assistant`\nformat.\n\n### Labels\n\nChoose a Labels layer for editing and QC:\n\n- **Edit & Confirm** contains the memory-controlled Paint and Erase workflow.\n  It edits a bounded local view and applies changes to the selected source\n  Labels layer.\n- **Mask Analysis & Cleanup** inspects the current Labels area through grid\n  registration, component actions, canvas selection, and an expandable\n  results table for large result sets. Training confirmation stays in Edit & Confirm.\n\nLayer selectors update automatically when layers are opened, added, removed,\nor renamed. **Refresh layers** remains beside the shared Labels-layer selector\nas an always-visible fallback; it is no longer buried among component actions.\n\nMask Analysis & Cleanup's **Screen & Group Objects** keeps the group destination\nbeside **Copy selected**. Enable **Select components from canvas** and **Keep\nearlier component selections**, then click objects belonging to a human-defined\ngroup, such as Remak bundles. Objects may have different source label values.\nCyan selection boxes identify the pending objects without changing their pixels;\nclick a selected object again to deselect it, or use **Undo selection** and\n**Clear selection**. **+ New** names a destination; its Labels layer is created\nwhen objects are copied. Right-click selected rows → **Copy selected to → New\ngroup…** names a group and copies the selection. Copies retain source values and\nimage coordinates. Enable **Clear selection after successful copy** for batches;\ncancellation and failed copies retain the pending selection.\n\nWorkspace Save preserves pending selections separately for each source and group.\nAfter reopening, **Find components** checks and restores matching objects. Source\nvalues, bounds, pixel footprints, and analysis coordinates must still match;\nchanged objects require reselection. Use the same analysis scope when restoring\nan editable-area selection. Grouping foreground objects does not approve the\nsurrounding background for training. The component index is still built on demand;\nlarge whole-mask searches remain chunked and cancellable, and can take time.\n\nThe **Group / destination** selector lists other Labels layers with the same 2D\nshape and matching spatial transform as the selected source, preferring **Curated**.\nReview/coverage masks and preserved originals are available only through manual\nselection, so they are not accidentally chosen as an annotation destination.\n\nUnder **Advanced: grid addresses and destination matching**, enable **Choose\ndestination manually** to select any Labels layer or type a new\nname. The first copy to an existing manual destination shows both layer names\nand dimensions, with **Copy** and **Cancel**. Cancel changes no layers or pixels;\nrepeated copies to the confirmed destination do not keep prompting.\nSwitching to a different destination asks again.\n\nCrop-sized masks copy at their original image coordinates into a larger\ndestination, including its on-disk full mask in grid mode. **Curated is not shrunk\nto the prediction crop.** Otherwise, a matching destination is prepared under the\nchosen name. The previous layer is preserved, hidden, as **<name> — original**.\nExisting overlapping annotations transfer where their pixel grids align exactly;\nlarger transfers run in bounded, cancellable chunks. There is no silent\nresampling. Annotations outside the new canvas or on a different pixel grid remain\navailable in the original layer.\nStopping an in-progress transfer keeps completed pixels; the initial confirmation's\nCancel button stops before any copying or matching. Existing model/review\nassociations stay with the preserved original when a replacement is created.\n\nRight-click selected rows → **Restore original destination before matching** to\nrestore the original layer and keep the copied result separately. If there is no\ncompatible destination yet, **Copy selected** or the context menu's **Prepare\nmatching Curated and copy** starts the matching workflow instead of showing a\ndisabled “no same-size targets” dead end. The source cannot copy into itself.\n\nWorkspace saves preserve these complete transforms, including crop offsets in\nprediction layers. Older workspaces with only scale and translation remain\nreadable. Local editable areas and their boundaries inherit the source mapping;\nchanging the source transform updates those helpers without resampling pixels.\nCombine operations also require aligned masks and preserve the reference transform.\n\nTo clean isolated specks, run **Find components**, set **Remove below** (default:\n**2 pixels**), and click **Remove small components**. This sets every connected\ncomponent with an area strictly below the threshold to background (0), and\nremoves it from the results across all pages. Components exactly at the threshold\nare kept; no row selection or sorting is needed.\n\nThe fixed top header is a compact activity indicator that confirms when napari\nis preparing a layer view and when the local editable area is ready. It uses\nshort states such as **Preparing view**, **View ready**, and **Edit area ready ·\n4096 × 4096**. Long layer names are shortened visually without changing the\ndock or table geometry; the full status and product description remain in the\nheader tooltip.\n\n**Mask editing** follows the camera by default for bounded workspace masks.\nZoom in to edit and zoom out for an overview. **Edit at View Center** provides\nmanual control. **Advanced** retains size-based Automatic, Local-area, and\nFull-layer editing for older workflows, along with manual grid navigation.\n\n**Connected-component analysis** provides measurement and region-management\ntools. Canvas picking finds components automatically and pauses painting;\n**Find components** also populates the table manually. You can:\n\n- click a column heading to sort the table;\n- double-click a result row to center that component in the viewer;\n- enable **Select components from canvas** to select a table row by clicking\n  the labeled region;\n- enable **Keep earlier component selections** to enable picking and build a multi-component selection;\n- use **Delete selected**, **Copy selected**, or **Remove small components** as needed.\n\nThe results table reports component ID, source label, pixel count, Euler\nnumber, centroid, and bounds. Optional grid columns report the grid row,\ncolumn, and cell containing each component centroid.\n\n### Training\n\nTraining has five pages: **1. Dataset** for confirmed tiles, preparation, and optional patch previews; **2. Models** for biological tasks, architecture selection, checkpoints, training history, and controlled comparisons; **3. Train** for training and validation; **4. Inference** for predictions; and **5. Advanced** for patch size, model input size, optimization, and augmentation. Progress and Cancel remain available across pages. Models supports the existing custom U-Net, a standard U-Net, and optional SMP U-Net, U-Net++, and DeepLabV3+ encoders. Prepare dataset enables training without adding canvas layers. Show patch preview is optional and displays a separate contact sheet beside the image; Return to image restores the previous view. Workspace Save includes changed model weights; standalone export remains available. See [model management and benchmarking](docs/model-management.md) for the workflow and optional dependency installation.\n\nFor partial annotations, open **Labels → Edit & Confirm**. Set the review-tile\nheight and width, inspect all objects and background, then choose **Confirm tile\nfor dataset** or **Confirm tile & next**. Enable **Click tiles to confirm for\ndataset** to approve successive fully checked tiles directly on the canvas.\nTurn selection off to paint again. **Go to dataset preparation** opens Training.\n\n**Training → Dataset** shows confirmed-tile counts and preparation status.\n**Edit & confirm tiles…** returns to the editor; **Show confirmed tiles on image**\ndisplays approval outlines. After preparation, **Show training / validation\npatches on image** locates the current dataset partitions. Model patch sizes\nremain in **5. Advanced**, independent of review-tile size and editable crop size.\n\nSaved foreground-only object selections remain available under **Advanced: saved\nobject selections and coverage**. They are preserved when reopening or saving a\nproject. Selecting a component in **Mask Analysis & Cleanup** is for inspection,\ncopying, or deletion; it does not approve training data. Cleanup that changes\nconfirmed pixels requires rechecking the affected tiles.\n\nDataset now presents one training-data overview: annotation-source counts,\nsupervision information, and No eligible annotations / Ready to prepare /\nPrepared / Outdated states. Exact foreground, background, and unknown pixel\ncounts appear after indexing, along with training and validation patch counts.\nUnknown pixels never become negatives implicitly. Individual positive-only\npatches remain supported within mixed datasets; the existing validation policy\nrequires targets and verified background in both splits. Selected objects alone\ntherefore require additional background review before preparation.\n\n\n**Training** trains the selected model from reviewed image/ground-truth patches\nand previews a bounded area of another image as a new Labels layer.\n\nInstall training dependencies in the Python environment used to launch napari.\nFrom this repository, use `python -m pip install -e '.[train]'`. For SMP models,\nuse `python -m pip install segmentation-models-pytorch`, then verify with\n`python -c \"import segmentation_models_pytorch as smp; print(smp.__version__)\"`.\nRestart napari from that same environment after installation. See\n[SMP installation and troubleshooting](docs/model-management.md#installing-and-checking-smp)\nfor environment checks and dependency errors. PyTorch is loaded only when\ntraining, prediction, or model loading is requested; other tools work without it.\n\n1. Open **Training → 1. Dataset**, or the plugin's **Model Training** panel.\n   Choose **Current pair** for one single-channel 2D image and its aligned\n   ground-truth Labels layer, or **Advanced source options → Multiple images → Manage pairs…** for several.\n   Use complete coverage only when the entire image is annotated; partial\n   annotations require associated reviewed regions and/or selected objects.\n2. In **2. Models**, choose a biological task and architecture. Leave\n   **Foreground classes** empty for binary training, or define semantic classes\n   and use their numeric IDs consistently in every included Labels layer.\n3. Return to **1. Dataset** and click **Prepare dataset**. The default\n   **All / selected training patches** workflow indexes eligible patches and streams them during\n   training. Set source patch and model input sizes in **5. Advanced**;\n   defaults are 512 × 512 pixels. Preparation locks included annotations,\n   supports cancellation, and does not open a gallery automatically.\n   Under **Training patch selection**, keep **All**, choose a **Percentage**, or\n   enter a **Patch count**. This samples the smaller model patches across approved\n   regions; it does not revoke review tiles. For example, 10% of 1,225 training\n   patches selects 123. The subset seed makes selection reproducible, and changing\n   the budget reuses the prepared index. Foreground/background patches are sampled\n   proportionally; invalid subsets report which supervision is missing.\n4. Optionally click **Show patch preview**. Cyan frames mark training patches\n   and orange frames mark validation. Double-click a tile to locate it in its\n   source image. **Return to image** hides the read-only gallery. Single-pair\n   datasets reserve spatial blocks; multiple-pair datasets reserve entire\n   image/specimen groups. Review the indexed counts and validation settings.\n   **Sample patches** remains available for complete single-pair annotations;\n   its crop count applies to a fixed sample rather than full coverage.\n5. In **3. Train**, choose epochs for **All / selected training patches** or steps for **Sample\n   patches**, then click **Train new model**. Device selection is in Advanced;\n   Automatic falls back to CPU when CUDA is unavailable or lacks memory.\n   Changed source pixels, pair selections, class definitions, patch sizes, or\n   validation settings require preparation again. Inspect validation Dice, IoU,\n   precision, and recall; multiclass models also show per-class results.\n   These validation-selected scores are not independent test-set accuracy.\n\nTraining subsets reuse the same chosen patches every epoch. By default, all reserved\nvalidation patches are evaluated. For faster experiments, enable **Quick trial —\nsmaller validation set** and choose **Validation percentage** (default 10%). With\n10% of each pool, 5,257 training / 1,813 validation patches become 526 / 182.\nThe validation sample stays fixed across epochs and training-subset changes,\npreserves the spatial/image split, and must retain required target/background and\nclass/channel supervision. Scores are labeled **Trial validation**.\n\nAfter a trial, use **Train → Validation → Evaluate full validation set** to evaluate\nthe retained weights on every reserved patch without training or reselecting weights.\nFull-validation results are saved separately from trial scores; save the workspace\nor export the model afterward. Change **Subset seed** to try different training\npatches, or return to **All** and turn Quick trial off for full training/validation.\nSource arrays remain disk-backed; selection stores coordinates rather than image\ncopies, and initial preparation still indexes the eligible pool. Workspace settings\nand completed checkpoints record the selection and evaluation provenance. Spatial\nk-fold and final all-reviewed training retain their full-index behavior.\n6. In **4. Inference**, select a **Prediction image** and choose **Current area**,\n   **Entire image**, or **Drawn box**. Current area predicts one crop; the other\n   modes blend overlapping tiles with progress and cancellation. Each run adds a\n   Labels layer with the image transforms preserved. Review the prediction.\n7. Save the workspace to persist datasets, annotations, model/run records, and\n   managed checkpoints. Use **Export current model…** to export a checkpoint,\n   and **Load model…** or Model Library to reuse it in later sessions.\n\nThe default custom model is a five-level U-Net with 8, 16, 32, 64, and 128 feature\nchannels, GroupNorm, and skip connections. Standard U-Net and optional SMP models\nare also available. Binary models use binary cross-entropy plus Dice loss;\nmulticlass models use cross-entropy plus foreground Dice loss. Select\n256 × 256 inputs for speed or 512 × 512 for more detail. At the default 512-pixel\ncontext/resolution no downsampling is needed. Larger contexts sacrifice boundary\ndetail; image area averaging and foreground-preserving mask pooling retain small\ntargets when reducing resolution. Inspect the gallery to assess this tradeoff.\nSampled single-pair training reduces context for small images to retain separate\nvalidation areas. Single-pair coverage needs two source patches on each axis;\nreduce patch size if preparation reports insufficient spatial coverage. Models\nlearn from the selected annotations and require evaluation on representative new\nimages before relying on their predictions.\n\nFor multiple tissue features, create a new biological task in **2. Models** and\nenter comma-separated **Foreground classes**, for example `axon, myelin`.\nThe semantic ground-truth Labels layer must use `0 = background`, `1 = axon`,\nand `2 = myelin`. These IDs represent tissue types, not individual objects.\nAll axons share ID 1, and all myelin pixels share ID 2. If annotations are in\nseparate layers, **Labels → Edit & Confirm → Label Tools → Compose Layers As Distinct Classes** can prepare a\nsemantic layer; check class order and overlaps before training. Existing object\nIDs are never automatically reinterpreted or converted.\n\nLeave the class field empty to retain binary training (all nonzero IDs become\nforeground). Class definitions are stored per task and checkpoint. A task with\ntrained models cannot change its class meanings; create another task instead.\nPrepare the dataset again after changing classes. Both coverage and sampled\ntraining support multiclass supervision. Each class needs examples in training\nand validation regions. Partial annotations still require reviewed coverage;\nunreviewed pixels and padding do not contribute to loss.\n\nMulticlass models use cross-entropy plus foreground Dice loss and predict the\nhighest-probability class, including background. The binary threshold is disabled.\nValidation shows foreground macro-average scores and per-class Dice/IoU.\nClass masks use nearest-neighbor resizing; if a class disappears during input\ndownsampling, preparation asks for matching patch and input sizes. Train a new\nmulticlass model; existing binary checkpoints retain their original output.\n\nTraining and prediction run in background workers. **Cancel** stops after the\ncurrent crop or training step, restores editing, and keeps the existing model.\nHuge NumPy/memmap, Zarr, and other sliceable sources are accessed by small\nregions; the full arrays are never converted to in-memory training copies.\n\nTo train across several images, choose **Advanced source options → Source mode → Multiple images** in\n**1. Dataset**, then open **Manage pairs…**. The pair table stays in a separate\ndialog to keep the Dataset panel compact. Suggested associations are not included\nautomatically. Check each image–label pair, choose complete annotations or its\nassociated reviewed-region mask, and confirm reviewed/corrected model predictions\nwith **Labels reviewed**. Click **Apply**, then **Prepare dataset** and train as\nusual. The existing **Current pair** mode remains available.\n\nMultiple-pair mode streams all eligible patches using the **All patches** workflow.\nEach image/specimen group stays entirely in training or validation; set the same\n**Specimen / split group** for related images, duplicated acquisitions, or images\nfrom one animal. Holdout requires at least two independent groups; k-fold needs\nat least as many suitable groups as folds. Each split needs targets and background,\nand multiclass datasets need each foreground class in both splits. Images can have\ndifferent dimensions, but each pair's shapes/transforms must align and image\nscales should be comparable. Patch previews retain their source image identities.\n\nPair inclusion, coverage, confirmations, and split groups are saved in the\nworkspace using stable layer IDs, so renaming layers does not break the pairing.\nMissing layers are reported for repair in Manage pairs. **Review selected pair**\nopens the normal review controls when needed; those controls stay collapsed in\nmultiple-pair mode. Training history records every included source.\n\n#### Continue training and history\n\nUse **Continue training** to improve the current or loaded model. It starts from\nthat model's weights with a fresh optimizer. **Train new model** creates a model\nusing the selected initialization instead.\n\nPrepare the dataset if needed; patch preview is optional. Set **Learning rate**\nin **Advanced**, then continue from **Train**. The best validation weights are\nretained, and cancellation preserves the previous model. Save again after a\ncompleted round to persist its weights and history.\n\nSee [continuation and training history](docs/TRAINING.md#continue-training-an-existing-model)\nfor validation restrictions, sampling, and the exported `.history.json` file.\n\n### Grid registration and QC traceability\n\nThe registration grid gives reviewers a reproducible address for every part of\na full 2D mask. With the same cell height, cell width, grid origin, and source\ncoordinate system, a reference such as **R12C08** identifies the same location\nacross masking, review, correction, and follow-up QC sessions—even between\ncollaborators.\n\nGrid-cell size is user-defined, with a default of 100 × 100 pixels. The grid\nserves both as an annotation map and as a shared review vocabulary:\nscreenshots, review notes, and correction requests can carry the same address\nwithout creating or exchanging cropped coordinate systems.\n\n- Enable **Assign grid addresses to results** to register each component by the\n  grid row, column, and cell containing its centroid.\n- Enable **Show address grid on canvas** to see cell boundaries and identifiers\n  around the current viewport.\n- Use a grid address together with a component ID—for example, “R12C08,\n  component 431”—to identify a labeled region that needs correction.\n- Use the grid address alone to register an unlabeled location where a\n  component is missing and therefore cannot appear in the results table.\n\nGrid addresses make reviewer findings and corrections traceable without\ncreating cropped copies of the source. Reuse the same grid dimensions, origin,\nand source coordinate system when addresses must remain stable. The address\ngrid is a spatial reference system. Manual tile completion and reviewed-region\napproval are separate records; it does not store reviewer comments, assignments,\nor a change-history audit log.\n\n### Labels: View & Compare\n\nThe main tabs are **Workspace | Labels | Training**. Under **Labels → Local\nEditing**, expand **View & Compare** to show Image Only, Overlay, or Labels Only,\nadjust Labels opacity, or temporarily Peek/Blink Labels. These controls preserve\nthe active editing layer and never change pixel data. **Advanced view effects**\nretains Pulse, Dim, Toggle, and Restore. Both new Labels sections start collapsed.\n\n### Labels: Label Tools\n\nExpand **Label Tools** under **Edit & Confirm** and select an operation. Only its\nrelevant settings are displayed. Select compatible, aligned 2D Labels layers:\n\n- reassign one label value;\n- merge foreground regions into one class;\n- compose layers as distinct classes;\n- create a per-pixel vote-count map;\n- create a consensus map from a minimum vote threshold.\n\nResults create a new Labels layer by default. **Overwrite first selected layer**\nis explicit and remains unavailable for vote-count maps. Large and disk-backed\nsources run in bounded tiles in the background, using full source masks rather\nthan their display crops. Temporary results are included when saving a workspace.\nThese mask-composition tools do not approve tiles for training.\n\n## Editing at 100,000 × 100,000-pixel scale\n\nWorkspace Save now builds categorical Labels pyramids (`s0`–`s6`) for 2D masks.\n`s0` keeps the original editable label IDs. Lower levels are derived previews:\neach 2 × 2 block keeps the first nonzero ID, preserving isolated foreground\nwithout averaging IDs. Competing objects can share a preview pixel; measurements\nand training always use `s0`. Very small masks stop before repeating 1 × 1 levels.\n\nLarge masks keep their editable grid tile and add a read-only **overview** layer\nfor the whole mask. Its visibility, opacity, and colors follow the source Labels\nlayer. Use **Show whole mask** in Edit & Confirm to zoom out; double-click while\nthe source or overview is selected to move the editable tile to that location.\nOverview layers are excluded from annotations, training sources, and saved layer\nrecords. Paint and erase update affected pyramid regions when edits are applied.\n\nOlder workspaces saved in full-mask mode now open through bounded crops by\ndefault. **Advanced → Editing mode → Bounded editing** returns an explicitly\nselected legacy mode to this workflow. Size-based **Automatic** also restores\nbounded rendering for large disk-backed masks. Full-size renderers are removed;\nthe overview provides whole-mask viewing.\n\nFor existing single-resolution workspaces, Save once to build the lower levels.\nThis adds disk data and takes time, but processes bounded blocks instead of\nloading the entire mask into RAM. A failed or interrupted build stays marked\noutdated; `s0` remains the annotation source and a later Save can rebuild previews.\n\nDefault camera-follow editing keeps a bounded working region editable in\nmemory. Zoom in to load that region, pan to follow, and zoom out for the read-only\noverview. **Edit at View Center** offers manual control. For older workflows,\n**Advanced → Editing mode → Local-area editing** retains the separate editable\narea and green boundary described below.\n\nThe original Labels layer remains the source of truth. Changes made in the\ntemporary editable-area layer are written back only for pixels that changed,\nand the corresponding part of the source preview is refreshed locally. The\neditable-area and boundary layers are transient helpers rather than additional\nlabel results.\n\n### Saving\n\nDefault bounded editing saves strokes after a short idle delay, waits for an\nactive stroke to finish, and flushes pending changes before navigation, saving,\nor closing. These writes use the same changed-region recovery journals and\nconflict checks. Workspace Save separately preserves project settings.\n\nIn the legacy **Local-area editing** mode, **Apply edits automatically** controls\nsynchronization:\n\n1. Saving never starts while the paint or erase mouse button is held.\n2. Releasing the mouse starts a 400 ms inactivity delay.\n3. Only the accumulated changed region is compared and written to the source.\n\nDisable automatic apply to keep changes in the local area until **Apply edits**\nis clicked. A local area with unsaved manual changes remains in place during\npan or zoom, preventing accidental loss. **Undo** and **Redo** synchronize\nimmediately in automatic mode and remain pending until **Apply edits** in manual\nmode.\n\nTile size controls the memory/performance tradeoff. A 2048 × 2048 area uses\nless memory; a 4096 × 4096 area requires fewer reloads while navigating.\n\n## Component analysis at full-image scale\n\n**Mask Analysis & Cleanup → Entire mask — full resolution** searches the complete\n`s0` mask independently of camera zoom and the current editing crop. This is the\ndefault. Search streams bounded chunks, joins components crossing their edges,\nand displays paged results with progress and Cancel. There is no need to enable\nfull-layer editing or load the complete mask into memory.\n\nChoose **Current edit area** for local inspection; its boundaries are shown in\nthe panel and objects may continue beyond them. Whole-mask results use full-image\ncoordinates for locating, picking, copying, cleanup, and undo. Cleanup invalidates\naffected dataset approvals; selecting results alone does not approve training data.\n\n## Requirements and scope\n\n- Python 3.11 or newer\n- napari 0.9.1 or newer for the camera/canvas integration\n- 2D Labels layers for local-area editing and component analysis\n- aligned 2D masks for combining; registered crops or explicit destination\n  matching when copying\n\nPractical dataset size depends on array storage, data type, chunking, available\nmemory, and hardware. Bounded workspace editing is the default for 2D Zarr\nmasks. Legacy direct editing and size-based Automatic remain under Advanced.\n\n## Installation\n\nInstall the current GitHub version (7.0.3):\n\n```bash\npython -m pip install --upgrade \"git+https://github.com/wulinteousa2-hash/napari-label-assistant.git@main\"\n```\n\nPyPI releases are published separately. To install the latest version available\non PyPI:\n\n```bash\npython -m pip install --upgrade napari-label-assistant\n```\n\nWhen upgrading from the pre-1.0 development package, remove its old plugin\nregistration before installing the current package:\n\n```bash\npython -m pip uninstall napari-label-assistant-tools\npython -m pip install napari-label-assistant\n```\n\nStart napari and open:\n\n**Plugins → napari-label-assistant → Label Curation**\n\n## Development\n\nClone the repository and install it in editable mode with test dependencies:\n\n```bash\npython -m pip install -e \".[all,test]\"\npytest\n```\n\n## License\n\nDistributed under the terms of the MIT license.\n",
    "description_content_type": "text/markdown",
    "keywords": "napari,image segmentation,labels,annotation,quality control,grid registration,large images",
    "home_page": null,
    "download_url": null,
    "author": "Wulin Teo",
    "author_email": null,
    "maintainer": null,
    "maintainer_email": null,
    "license": "The MIT License (MIT)\n\nCopyright (c) 2026 Wulin Teo\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n",
    "classifier": [
      "Development Status :: 5 - Production/Stable",
      "Framework :: napari",
      "License :: OSI Approved :: MIT License",
      "Operating System :: OS Independent",
      "Programming Language :: Python :: 3",
      "Topic :: Scientific/Engineering :: Image Processing"
    ],
    "requires_dist": [
      "napari>=0.9.1",
      "numpy",
      "qtpy",
      "scikit-image",
      "scipy",
      "zarr>=2.18",
      "napari[all]>=0.9.1; extra == \"all\"",
      "pytest; extra == \"test\"",
      "pytest-qt; extra == \"test\"",
      "napari[qt]>=0.9.1; extra == \"test\"",
      "torch>=2.1; extra == \"train\"",
      "torch>=2.1; extra == \"smp\"",
      "segmentation-models-pytorch>=0.3.3; extra == \"smp\""
    ],
    "requires_python": ">=3.11",
    "requires_external": null,
    "project_url": null,
    "provides_extra": [
      "all",
      "test",
      "train",
      "smp"
    ],
    "provides_dist": null,
    "obsoletes_dist": null
  },
  "npe1_shim": false
}