{"name":"focus-3d","display_name":"FOCUS-3D","visibility":"public","icon":null,"categories":[],"schema_version":"0.3.0","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,"configurations":{}},"package_metadata":{"metadata_version":"2.4","name":"focus-3d","version":"0.1.21","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://www.quiclab.org.cn/focus-3d)\n[](https://github.com/yu-lab-vt/FOCUS-3D)\n[](https://doi.org/10.64898/2026.08.25.746907)\n[](https://huggingface.co/spaces/Qinghua-thu/FOCUS-3D)\n[](https://www.python.org/)\n[](https://napari.org/)\n\n\nFOCUS-3D provides a user-friendly **napari plugin** for interactive 3D cell segmentation and analysis.\n\n### āØ What you can do\n\n š Run automatic 3D cell segmentation with pretrained FOCUS-3D models
\n āļø Manually correct segmentation errors
\n š±ļø Perform one-click segmentation
\n š§© Prepare curated patches for human-in-the-loop fine-tuning
\n š§ Fine-tune FOCUS-3D models on your own data
\n š¬ Reconstruct selected 3D cell instances
\n š Compute quantitative statistics\n\n### š Examples & Tutorials\n\nVisit our website for examples, tutorials, and usage instructions: š [FOCUS-3D Website](https://www.quiclab.org.cn/focus-3d)\n\n### āļø Try FOCUS-3D Online\n\nWant to try FOCUS-3D without installing anything? š [**FOCUS-3D Online**](https://huggingface.co/spaces/Qinghua-thu/FOCUS-3D) on Hugging Face Spaces allows you to upload your own 3D fluorescence microscopy data for quick online inference and testing.\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. Download pretrained model\nUsers can download the pretrained model for 3D segmentation: https://huggingface.co/Qinghua-thu/FOCUS-3D/.\n\n\n#### 5. Install detectron2 (optional, 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 --no-build-isolation 'git+https://github.com/facebookresearch/detectron2.git'\n```\n\n#### 6. Launch napari\n\n```bash\npython -m napari\n```\n\n## Recommended Workflow\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\n### Step 2 ā Run automatic 3D segmentation\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 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 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 a 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 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 segmentation when needed\n\nOne-click segmentation can accelerate the curation.\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 `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 training data and fine-tune the model\n\nFine-tuning consists of preparing annotated training data and then running the fine-tuning notebook.\n\n#### A. Prepare training data\n\nThere are two ways to prepare the annotations:\n\n* **If the entire volume has been annotated:** you do **not** need to use `Calculate Valid Patches` in napari. Provide the fully annotated raw image and label volume to the fine-tuning notebook. The notebook includes code to automatically crop the full volume into training patches and organize them into `imagesTr` and `labelsTr`.\n\n* **If annotating the entire volume is impractical:** use the napari plugin to curate selected patches:\n\n 1. Keep the raw image and corrected label volume loaded.\n 2. Open `Segmentation -> Finetune with Current Labels`.\n 3. Click `Calculate Valid Patches`.\n 4. Choose a `Patch ID` and set the `Save Path`.\n 5. Click `Curate Selected Patch`.\n 6. Correct the labels in the patch viewer and click `Save`.\n\nCurated patches are saved as:\n\n```text\n/\nāāā imagesTr/\nā āāā patch_0001.tif\nā āāā ...\nāāā labelsTr/\n āāā patch_0001.tif\n āāā ...\n```\n\nUse `Clear Patch Boxes` to remove the patch overlays when finished.\n\n#### B. Run fine-tuning from the notebook\n\nThe fine-tuning notebook is **not included in the `pip` installation** and must be downloaded separately from the FOCUS-3D repository.\n\nOpen:\n\n```text\nnotebooks/02_finetune.ipynb\n```\n\nIf using a fully annotated volume, first run the notebook section that crops it into training patches. If patches were already exported from napari, directly set the notebook to use the prepared `imagesTr` and `labelsTr` directories.\n\nRun fine-tuning to obtain a new checkpoint, then return to `Segmentation -> Run Segmentation`, select the new checkpoint in the `Checkpoint` field, and run segmentation again.\n\nThe napari plugin can assist with patch preparation, while model fine-tuning itself is performed in the notebook.\n\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/yu-lab-vt/FOCUS-3D/issues) with a detailed description, relevant logs, and a minimal example when possible. You can also contact `zhangqh24@mails.tsinghua.edu.cn`. We also look forward to collaborating and jointly developing new algorithms, or customizing models based on your data.\n\n## Citing\n```bibtex\n@article{zhang2026focus,\n title={FOCUS-3D: Robust, generalizable volumetric cell segmentation for three-dimensional fluorescence microscopy},\n author={Zhang, Qinghua and Mu, Zeyu and Liu, Boqi and Chi, Yunfeng and Li, Donglin and Wang, Wenjuan and Ni, Jian-Quan and Wan, Yinan and Yu, Li and Navajas Acedo, Joaquin and Yu, Guoqiang},\n journal={bioRxiv},\n year={2026},\n doi={10.64898/2026.08.25.746907}\n}\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","qtpy","scikit-image","scipy","pandas","tifffile","zarr","pyyaml","requests","dask","matplotlib","scikit-learn","tqdm","imagecodecs>=2023.9.18","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}