{"name":"focus-3d","display_name":"FOCUS-3D","visibility":"public","icon":null,"categories":[],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"focus-3d.get_reader","title":"Open data with FOCUS-3D","python_name":"focus3d._reader:napari_get_reader","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"focus-3d.write_multiple","title":"Save multi-layer data with FOCUS-3D","python_name":"focus3d._writer:write_multiple","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"focus-3d.write_single_image","title":"Save image data with FOCUS-3D","python_name":"focus3d._writer:write_single_image","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"focus-3d.make_sample_data","title":"Load sample data from FOCUS-3D","python_name":"focus3d._sample_data:make_sample_data","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"focus-3d.make_segmentation_widget","title":"Open FOCUS-3D Segmentation Widget","python_name":"focus3d._widget:SegmentationWidget","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"focus-3d.make_tracking_widget","title":"Open FOCUS-3D Tracking Widget","python_name":"focus3d._widget:TrackingWidget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":[{"command":"focus-3d.get_reader","filename_patterns":["*.npy"],"accepts_directories":false}],"writers":[{"command":"focus-3d.write_multiple","layer_types":["image*","labels*"],"filename_extensions":[],"display_name":""},{"command":"focus-3d.write_single_image","layer_types":["image"],"filename_extensions":[".npy"],"display_name":""}],"widgets":[{"command":"focus-3d.make_segmentation_widget","display_name":"3D Segmentation","autogenerate":false}],"sample_data":[{"command":"focus-3d.make_sample_data","key":"unique_id.1","display_name":"FOCUS-3D"}],"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.4","name":"focus-3d","version":"0.1.14","dynamic":["license-file"],"platform":null,"supported_platform":null,"summary":"FOCUS-3D: a user-friendly napari plugin for interactive 3D cell segmentation, curation, and analysis","description":"# FOCUS-3D\n\n[](https://github.com/Qinghua24/cellseg/raw/main/LICENSE)\n[](https://pypi.org/project/cellseg)\n[](https://python.org)\n[](https://github.com/Qinghua24/cellseg/actions)\n[](https://codecov.io/gh/Qinghua24/cellseg)\n[](https://napari-hub.org/plugins/cellseg)\n[](https://napari.org/stable/plugins/index.html)\n\nFOCUS-3D provides a user-friendly napari plugin for interactive 3D cell segmentation, manual curation, model fine-tuning, and analysis. Users can run automatic 3D segmentation with pretrained FOCUS-3D models, manually correct segmentation errors, perform one-click segmentation, prepare curated patches for human-in-the-loop fine-tuning, reconstruct selected 3D cell instances, and compute quantitative statistics within the same napari workflow. Our website is [https://www.quiclab.org.cn/focus-3d](https://www.quiclab.org.cn/focus-3d).\n\n![\"image\"](\"https://github.com/user-attachments/assets/2a9ccc08-3109-4b73-bcae-0514bcec2a86\")
\n\n## Installation\n\n#### 1. Create a new environment\n\n```bash\nconda create -n focus3d python=3.10 -y\nconda activate focus3d\n```\n\n#### 2. Install torch\nFor CUDA 12.x, replace cu12x with your specific CUDA-compatible PyTorch build. For example, for CUDA 12.6:\n\n```bash\npip install torch torchvision --index-url https://download.pytorch.org/whl/cu126\n```\nPlease check the official PyTorch installation guide if you need another CUDA version.\n\n#### 3. Install FOCUS-3D\n\n```bash\npip install -U \"focus-3d[gui]\"\n```\n\n#### 4. Install detectron2 (only for Linux model fine-tuning)\nFor Linux, FOCUS-3D requires Detectron2 for segmentation model fine-tuning. Please install Detectron2 according to the official guide:\n\nhttps://detectron2.readthedocs.io/en/latest/tutorials/install.html\n\nFor most Linux environments, the official source installation command is:\n\n```bash\npython -m pip install 'git+https://github.com/facebookresearch/detectron2.git'\n```\n\n#### 5. Launch napari\n\n```bash\npython -m napari\n```\n\n## Recommended Workflow\n\nThe following workflow is designed for first-time users. \n\n### Step 1 — Load and inspect the image\n1. In napari, open `Plugins -> 3D Segmentation (FOCUS-3D)`.\n2. Load a raw 3D microscopy image:\n - use `File -> Open Folder` for a `.zarr` dataset, which is recommended for large volumes;\n - use `File -> Open File(s)` for `.tif` or `.tiff` images.\n3. Open the `Basic` tab and use `Display Settings` when the raw image is difficult to inspect:\n - move the `Minimum` and `Maximum` sliders to adjust contrast;\n - click `Auto` for percentile-based contrast adjustment;\n - The display settings affect visualization only; they do not modify the raw image values used for segmentation.\n\n### Step 2 — Run automatic 3D segmentation\n\n1. Open the `Segmentation` tab.\n2. In `Run Segmentation`, set the parameters that are most likely to vary between datasets:\n - **Z Ratio** — the physical Z-to-XY spacing ratio. Use `1.0` for isotropic data.\n - **Output Path** — the directory used for the current segmentation result.\n - **Checkpoint** — the pretrained or fine-tuned checkpoint.\n - **Cell radius (pixel)** — the approximate cell radius in the XY plane.\n - **Background intensity** — patches or cells with grayscale values less than this value will be removed.\n - **Min size (3D)** and **Max size (3D)** — remove implausibly small or large instances.\n3. Use `Advanced` only when you need to change the GPU, configuration file, normalization percentiles, patch stride, batch size, or stitching thresholds. See the [complete menu reference](docs/MENU_REFERENCE.md#run-segmentation) for parameter definitions and defaults.\n4. Click `Run 3D Segmentation`.\n\nAfter inference, FOCUS-3D loads an editable label layer into napari. The inference outputs are saved to the specified output path in both TIFF and Zarr formats.\n\n### Step 3 — Inspect and curate the segmentation\n\n1. Return to the `Basic` tab.\n\n2. Click `Enter Curation Mode`, then click a cell label to select it.\n\n3. Correct common errors:\n\n * use `Add to Label` to recover missing regions;\n * use `Subtract from Label` to remove incorrect regions;\n * use `Add New Label` for a missed cell;\n * use `Delete Current Z` for a slice-specific error;\n * use `Delete All Z` to remove an incorrect 3D instance;\n * use `Delete Inside ROI (All Z)` to remove multiple labels in a selected region.\n\n For detailed instructions on ROI drawing, label-editing operations, and keyboard shortcuts, see [Manual Curation](docs/MENU_REFERENCE.md#manual-curation).\n\n4. For labels stored in Zarr format, edits are written directly to the underlying Zarr data, so no separate save step is required. Labels loaded from TIFF are edited in memory and must be saved manually from the `Save` panel after curation.\n\n### Step 4 — Use one-click local refinement when needed\n\nManual drawing is not always the fastest way to correct a difficult cell.\n\n1. Keep both the raw image and segmentation label layer loaded.\n2. Open `Segmentation -> One-click segmentation`.\n3. Click `Enter Inactive Mode` to load the local refinement model and activate interactive refinement.\n4. Click the target cell in the viewer and inspect the updated label.\n5. Click `Exit Inactive Mode` after finishing.\n\n\n### Step 5 — Analyze the segmentation results\n\nOpen the `Analysis` tab after the segmentation has been checked.\n\n#### Reconstruct one selected cell\n\n1. Select a non-background cell in the label layer.\n2. Set the appropriate `Z Ratio`.\n3. Click `Reconstruct Selected Label`.\n4. Save the reconstructed mesh as `.npz` when needed.\n\n#### Inspect the full volume in 3D\n\n1. Set the physical `Z Ratio`.\n2. Click `Switch to 3D View`.\n3. Rotate and inspect the image and labels.\n4. Click `Switch to 2D View` to return to slice navigation.\n\n#### Run morphometry analysis\n\n1. Set the physical voxel size in Z, Y, and X.\n2. Choose an output folder.\n3. Run one or more tasks:\n - `Basic Information` for cell morphology and optional intensity measurements;\n - `Neighborhood Analysis` for centroid-based local organization;\n - `Contact Graph Analysis` for face-touching cell relationships;\n - `Clustering` for feature-based cell grouping.\n4. Use `Show feature` to map supported results back to the napari label volume.\n\n### Step 6 — Prepare curated patches and fine-tune the model\n\nFine-tuning is a two-stage workflow: curate training patches in napari, then run the training notebook.\n\n#### A. Export curated patches from napari\n\n1. Keep the raw image and corrected label volume loaded.\n2. Open `Segmentation -> Finetune with Current Labels`.\n3. Click `Calculate Valid Patches`.\n4. Inspect the patch boxes and choose a `Patch ID`.\n5. Set the patch `Save Path`.\n6. Click `Curate Selected Patch`.\n7. In the new patch viewer, correct the labels with the `Basic` curation tools.\n8. In `Save Curated Patch`, click `Save`.\n\nEach saved sample is written as a paired TIFF image and label:\n\n```text\n/\n├── imagesTr/\n│ ├── patch_0001.tif\n│ └── ...\n└── labelsTr/\n ├── patch_0001.tif\n └── ...\n```\n\nUse `Clear Patch Boxes` when you want to remove the patch overlays and return to normal curation.\n\n#### B. Run fine-tuning from the notebook\n\n1. Expand the collapsed `Fine-tune` instruction inside the same panel.\n2. Open:\n\n```text\nnotebooks/02_finetune.ipynb\n```\n\n3. Configure the notebook to use the curated patch directory.\n4. Run fine-tuning and obtain a new checkpoint.\n5. Return to `Segmentation -> Run Segmentation`.\n6. Select the new checkpoint in the `Checkpoint` field and run segmentation again.\n\nThe napari panel prepares and exports training data, but it does not launch model training directly.\n\n## Detailed Interface Reference\n\nThe complete descriptions of all controls are maintained in:\n\n- [Basic tab](docs/MENU_REFERENCE.md#basic-tab)\n- [Segmentation tab](docs/MENU_REFERENCE.md#segmentation-tab)\n- [Analysis tab](docs/MENU_REFERENCE.md#analysis-tab)\n- [Keyboard shortcuts](docs/MENU_REFERENCE.md#keyboard-shortcuts)\n- [Output files and folders](docs/MENU_REFERENCE.md#output-files-and-folders)\n\n\n## Issues\n\nIf you encounter a problem, please [file an issue](https://github.com/Qinghua24/cellseg/issues) with a detailed description, relevant logs, and a minimal example when possible. You may also contact `zhangqh24@mails.tsinghua.edu.cn`.\n\n## Citing\n\nPlease contact us before the paper is published.\n\n","description_content_type":"text/markdown","keywords":null,"home_page":null,"download_url":null,"author":"Qinghua Zhang","author_email":"zhangqh24@mails.tsinghua.edu.cn","maintainer":null,"maintainer_email":null,"license":null,"classifier":["Development Status :: 2 - Pre-Alpha","Framework :: napari","Intended Audience :: Developers","Operating System :: OS Independent","Programming Language :: Python","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["numpy","magicgui","qtpy","scikit-image","scipy","pandas","tifffile","zarr","imageio","pyyaml","requests","dask","fsspec","numcodecs","pillow","matplotlib","scikit-learn","umap-learn","imagecodecs>=2023.9.18","timm>=1.0","napari[all]; extra == \"gui\""],"requires_python":">=3.10","requires_external":null,"project_url":null,"provides_extra":["gui"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}