{"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.3","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### Windows\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 FOCUS-3D\n\n```bash\npip install -U \"focus-3d[all]\"\n```\n\n#### 3. Launch napari\n\n```bash\npython -m napari\n```\n\n---\n\n### Linux\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 PyTorch\n\nFor CUDA 12.6:\n\n```bash\npip install torch torchvision --index-url https://download.pytorch.org/whl/cu126\n```\n\nIf your CUDA version is different, please install the corresponding PyTorch version from the official PyTorch installation guide.\n\n#### 3. Install FOCUS-3D\n\n```bash\npip install -U \"focus-3d[all]\"\n```\n\n#### 4. Install detectron2\n\n```bash\npip install \"git+https://github.com/facebookresearch/detectron2.git\"\n```\n\n#### 5. Launch napari\n\n```bash\npython -m napari\n```\n\n## Usage\n\n1. Open FOCUS-3D from `Plugins -> FOCUS-3D`.\n2. Load the raw image from `File -> Open Folder` for a `.zarr` dataset(recommend), or `File -> Open File(s)` for `.tif` images.\n3. Use the `Basic`, `Segmentation`, and `Analysis` tabs to load labels, run segmentation, manually curate results, fine-tune models, reconstruct 3D structures, and calculate quantitative statistics.\n\n## Basic Menu\n\nThe `Basic` menu provides functions for loading segmentation labels, adjusting image display, manually curating labels, and saving edited results.\n\n### Load Label\n\n| Operation | Description |\n|---|---|\n| Load from Zarr | Load an existing 3D label map from a `.zarr` folder. This is recommended for large 3D volumes because it supports efficient data access and editing. |\n| Load from TIFF | Load an existing 3D label map from a `.tif` or `.tiff` file. |\n| Only Show Contour | Display label contours instead of filled label masks, making it easier to inspect boundaries and compare labels with the raw image. |\n\n### Display Settings\n\n| Operation | Description |\n|---|---|\n| Minimum / Maximum | Adjust the display contrast range of the currently selected image layer. |\n| Auto | Automatically estimate a suitable contrast range for the active image layer using robust intensity percentiles. |\n| Reset Contrast | Reset the contrast range of the active image layer. |\n| Channel Composite | Select one or more image layers and assign different colormaps for multi-channel visualization. |\n| Apply | Apply the selected channel visibility and colormap settings. |\n| Reset Display | Reset image layers to the default display mode. |\n\n### Manual Curation\n\n| Operation | Shortcut | Description |\n|---|---|---|\n| Enter Curation Mode | — | Activate label editing mode. Users can click on an existing label to select and modify it. |\n| Polygon Draw Mode | — | Define an ROI by clicking polygon vertices. The enclosed region is used for label editing. |\n| Brush Draw Mode | — | Define an ROI by painting directly on the image. The painted region is used for label editing. |\n| Trace Draw Mode | — | Define an ROI using trace-based drawing. |\n| Brush Size | `+` / `-` | Adjust the ROI brush size or label brush size. |\n| Brush Color | — | Change the display color of the ROI brush. |\n| Add to Label | `A` | Add the selected ROI to the currently selected label. |\n| Subtract from Label | `S` | Remove the selected ROI from the currently selected label. |\n| Add New Label | `Ctrl + D` | Create a new label. Regions from multiple Z slices can be combined into the same 3D instance. |\n| Change Label | `C` | Change the ID of the currently selected label. |\n| Apply ROI | `Ctrl + A` | Apply the current ROI operation. Used with **Add to Label**, **Subtract from Label**, and **Add New Label**. |\n| Cancel ROI | `Ctrl + C` | Cancel the current ROI operation without applying changes. |\n| Delete Current Z | `Delete` | Delete the selected label only on the current Z slice. |\n| Delete All Z | `Ctrl + Delete` | Delete the selected label across all Z slices. |\n| Delete Inside ROI (All Z) | — | Delete all labels inside the selected ROI across all Z slices. |\n| Show Log File | — | Open or show the curation log file that records editing operations. |\n| Previous Slice | `Q` | Move to the previous Z slice. |\n| Next Slice | `W` | Move to the next Z slice. |\n| Undo Local Refinement | `Ctrl + Z` | Undo the latest one-click local refinement result when available. |\n\n### Save\n\n| Operation | Description |\n|---|---|\n| Browse | Select the folder for saving the current label result. |\n| Save format | Choose the output format, including `Zarr (recommended)` or `TIFF`. |\n| Update Labels | Reassign label IDs before saving so that labels are stored in a clean consecutive order. |\n| Save | Save the current label layer to the selected output path. |\n\n## Segmentation Menu\n\nThe `Segmentation` menu provides automatic 3D segmentation with **FOCUS-3D**, one-click local segmentation refinement, and human-in-the-loop fine-tuning based on curated labels.\n![\"image\"](\"https://github.com/user-attachments/assets/74b6b9ae-0a00-4b40-bb31-fb743709c725\")
\n\n### Run Segmentation\n\n| Parameter / Operation | Description |\n|---|---|\n| Z Ratio | Set the physical Z-to-XY spacing ratio for anisotropic 3D data. |\n| Output Path | Set the output folder for FOCUS-3D segmentation results. By default, the plugin creates an output folder based on the input image path. |\n| GPU IDs | Select the GPU device used for inference, such as `0`, `1`, or `0,1`. |\n| Refresh | Refresh the list of available GPU devices. |\n| Advanced | Expand or collapse advanced inference settings. |\n| Checkpoint | Select the pretrained model checkpoint. The default path is relative to the backend folder. |\n| Configure | Select the configuration file. The default configuration is `configs/3d_test.yaml`. |\n| Lower / Upper Percentile | Set the intensity percentile range for image normalization before inference. |\n| Patch size (Z/Y/X) | Set the 3D patch size used for sliding-window inference. |\n| Stride (Z/Y/X) | Set the stride between neighboring inference patches. Smaller strides increase overlap but require more computation. |\n| Background intensity | Ignore patches whose maximum intensity is below this threshold. |\n| Batch size | Set the inference batch size. Larger values may improve speed but require more GPU memory. |\n| Score confidence | Set the object-level confidence threshold for accepting predicted instances. |\n| Mask confidence | Set the voxel-level mask confidence threshold for generating instance masks. |\n| Min area (2D) | Remove small 2D components below the specified area threshold during stitching or post-processing. |\n| Min size (3D) | Remove 3D objects smaller than the specified voxel size. A value of `0` disables minimum-size filtering. |\n| Max size (3D) | Remove 3D objects larger than the specified voxel size. The default value is `100000`. |\n| Run 3D Segmentation | Run automatic 3D segmentation using FOCUS-3D. The result is loaded back into napari as an editable label layer, and the confidence map can also be saved or visualized. |\n\n### One-click Segmentation\n\n| Operation | Description |\n|---|---|\n| Enter Inactive Mode | Load the one-click segmentation model and enter interactive local segmentation mode. After entering this mode, users can click on a target cell region to trigger local refinement. |\n| Exit Inactive Mode | Exit one-click segmentation mode and return to normal interaction. |\n| Status Label | Display the current status of the one-click segmentation module, such as inactive, loading, active, or busy. |\n| Local Refinement | Use the pretrained FOCUS-3D model to refine a clicked cell or local region, supporting fast correction of missed or inaccurate instances. |\n| Undo | Undo the latest one-click segmentation refinement result with `Ctrl + Z`. |\n\n### Finetune with Current Labels\n\n| Operation | Description |\n|---|---|\n| Calculate Valid Patches | Automatically scan the current image and label volume to find valid 3D patches for fine-tuning. Patches are selected according to patch size, stride, and intensity threshold. |\n| Select Patch ID | Select a valid patch by ID. The corresponding patch region is highlighted in the viewer. |\n| Save Path | Set the folder for saving curated training patches. The expected structure is `imagesTr/` and `labelsTr/`. |\n| Curate Selected Patch | Open the selected 3D patch in a new napari viewer for focused manual correction. |\n| Save Curated Patch | Save the curated patch image and label into `imagesTr/` and `labelsTr/`. |\n| Checkpoint Dir | Set the output directory for fine-tuned FOCUS-3D checkpoints. |\n| Run Fine-tune | Fine-tune the FOCUS-3D model using the curated patches. After fine-tuning, the newly generated checkpoint can be used for subsequent segmentation. |\n\n## Analysis Menu\n\nThe `Analysis` menu provides tools for selected-label 3D reconstruction, full-volume 3D visualization, and task-based morphometry analysis.\n\n![\"image\"](\"https://github.com/user-attachments/assets/bee8aa3e-7f57-439d-93bc-cf28ebbb0f9c\")
\n\n\n### 3D Label Reconstruction\n\nThis module reconstructs one selected non-background label into a 3D surface mesh. The mesh is generated from the selected label mask and displayed in a separate napari 3D viewer as a `Surface` layer. The Z scaling factor is applied during mesh generation, which is important for anisotropic microscopy volumes.\n\n| Operation | Description |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Z Ratio | Set the physical Z-to-XY scaling ratio used during mesh reconstruction. A larger value stretches the reconstructed mesh along the Z axis. |\n| Reconstruct Selected Label | Reconstruct the currently selected non-background label into a 3D surface mesh. The selected label is cropped before mesh extraction to reduce memory usage. |\n| Load Mesh | Load a previously saved `.npz` mesh file and display it in a separate 3D napari viewer. |\n| Save Mesh | Save the latest reconstructed mesh as a compressed `.npz` file, including vertices, faces, voxel count, Z ratio, and label ID. |\n\n### Full 3D View\n\nThis module switches the main napari viewer between 2D slice mode and full-volume 3D visualization mode. It applies anisotropic Z scaling to spatial layers before entering 3D view.\n\n| Operation | Description |\n| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Z Ratio | Set the Z-axis scaling factor for full-volume 3D visualization. For 3D data ordered as `(Z, Y, X)`, the layer scale is set to `(Z Ratio, 1.0, 1.0)`. |\n| Switch to 3D View / Switch to 2D View | Toggle the main viewer between 2D slice view and 3D visualization. When entering 3D mode, the plugin also switches layers to pan/zoom mode to enable camera rotation. |\n\n### Quick Quantitative Statistics\n\nThis module provides a lightweight size-distribution summary from the current label layer. It is intended for a quick overview of segmentation results.\n\n| Operation | Description |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Calculate Size Distribution | Count all non-background labels and compute their voxel sizes. The result dialog reports the number of cells, minimum size, maximum size, and a histogram of cell size distribution. |\n\n### Morphometry Analysis\n\nThe `Morphometry Analysis` panel provides task-based quantitative analysis for 3D label layers. Each task runs independently in the background and saves its results to a task-specific output folder.\n\n> Morphometry analysis currently supports 3D label layers. Raw image layers are only required when intensity-based features are selected.\n\n#### Common Settings\n\n| Operation | Description |\n| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Voxel size (Z / Y / X) | Set the physical voxel size used for volume, surface area, centroid, distance, and shape measurements. |\n| Output folder | Set the root folder for morphometry outputs. Each task writes results into a subfolder such as `basic_info`, `neighborhood`, `contact`, or `clustering`. |\n| Browse | Select an output folder from the file system. |\n| Open Output Folder | Open the current morphometry output folder. |\n\n#### 1. Basic Information\n\nCompute selected per-cell measurements and save them into one CSV table.\n\n| Operation | Description |\n| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Raw layer | Select the raw image layer used for intensity measurements. This is required only when intensity features are selected. |\n| Refresh Raw Layers | Refresh the raw-layer dropdown from the current napari viewer. |\n| Features to compute | Select cell-level features to calculate, including volume, equivalent diameter, surface area, centroid, sphericity, compactness, major axis length, elongation, flatness, and intensity statistics. |\n| Run Basic Information | Compute the selected features and save `basic_info_cell_features.csv` and `basic_info_summary.csv`. |\n| Show feature | Display a selected computed feature as a mapped 3D image layer in napari. Non-map features such as centroid and some scalar-only fields are saved in CSV but are not shown as feature maps. |\n\nSupported basic features include:\n\n| Feature | Description |\n| -------------------------------- | ----------------------------------------------------------------------------------- |\n| Volume | Physical cell volume computed from voxel count and voxel size. |\n| Equivalent diameter | Diameter of a sphere with the same volume. |\n| Surface area | Surface area estimated from exposed voxel faces. |\n| Centroid | Cell centroid in physical coordinates. |\n| Sphericity | Shape compactness relative to a sphere. |\n| Compactness | Surface-area-to-volume based compactness measurement. |\n| Axis major | Major axis length estimated from PCA on physical voxel coordinates. |\n| Elongation | Ratio describing long-axis elongation. |\n| Flatness | Ratio describing flattening along the minor axis. |\n| Min / Max / Mean / Std intensity | Intensity statistics computed inside each labeled cell. Requires a raw image layer. |\n\n#### 2. Neighborhood Analysis\n\nCompute centroid-based neighborhood features using either k-nearest neighbors or a radius-based neighborhood.\n\n| Operation | Description |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| Mode | Choose between `kNN distance` and `Radius count / density`. |\n| k | Number of neighbors used in kNN mode. |\n| Radius pixels | Radius used in radius mode, measured in voxel/pixel coordinates. |\n| Run Neighborhood | Compute neighborhood features and save `neighborhood_cell_features.csv` and `neighborhood_summary.csv`. |\n| Show feature | Display a selected neighborhood feature as a mapped 3D image layer. |\n| Run Local Comparison | After neighborhood analysis is finished, compute a local z-score for one selected feature by comparing each cell with its neighbors. |\n\nIn `kNN distance` mode, the plugin computes nearest-neighbor distance, mean/median kNN distance, and local density. In `Radius count / density` mode, it computes the number of neighboring cells within the selected radius and the corresponding local density.\n\nLocal comparison supports features such as mean intensity, sphericity, volume, surface area, compactness, elongation, and flatness. The output includes the original feature value, local neighbor mean, local neighbor standard deviation, and local z-score.\n\n#### 3. Contact Graph Analysis\n\nCompute face-touching contact relationships between neighboring labeled cells.\n\n| Operation | Description |\n| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Features to compute | Select contact features to calculate, including neighbor count, total contact area, mean contact area, maximum contact area, and contact fraction. |\n| Run Contact Graph | Compute the contact graph and save `contact_cell_features.csv`, `contact_edges.csv`, and `contact_summary.csv`. |\n| Show feature | Display a selected contact feature as a mapped 3D image layer. |\n\nContact area is estimated from shared voxel faces using the physical voxel size. `contact_edges.csv` stores pairwise cell-cell contact edges, while `contact_cell_features.csv` stores per-cell contact summaries.\n\n#### 4. Clustering\n\nCluster cells using one selected feature.\n\n| Operation | Description |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Feature | Select the feature used for clustering. Available features include morphology, intensity, and contact-related measurements. |\n| Clusters | Set the number of clusters for K-means clustering. |\n| Run Clustering | Cluster cells based on the selected feature and save `clustering_cell_features.csv` and `clustering_summary.csv`. The `cluster_id` result is displayed automatically in napari. |\n\nIf an intensity feature is selected for clustering, a raw image layer is required. Clustering uses the selected feature values and assigns each valid cell a `cluster_id`.\n\n## Recommended Workflow\n\nA typical workflow is:\n\n1. Load the raw 3D microscopy image into napari.\n2. Run automatic 3D segmentation with **FOCUS-3D** from the `Segmentation` menu.\n3. Inspect the segmentation result in the `Basic` menu.\n4. Correct segmentation errors using manual curation tools such as **Add to Label**, **Subtract from Label**, **Add New Label**, and **Delete Inside ROI**.\n5. Use **One-click Segmentation** for fast local correction of difficult or missed cells.\n6. Save the curated labels as `.zarr` or `.tif`.\n7. Optionally select valid curated patches and fine-tune FOCUS-3D with the corrected labels.\n8. Use the `Analysis` menu for 3D reconstruction, full 3D visualization, and quantitative statistics.\n\n## License\n\nDistributed under the terms of the [BSD-3] license, `FOCUS-3D` is free and open source software.\n\n## Issues\n\nIf you encounter any problems, please [file an issue] along with a detailed description or contact zhangqh24@mails.tsinghua.edu.cn.\n\n[napari]: https://github.com/napari/napari\n[BSD-3]: http://opensource.org/licenses/BSD-3-Clause\n[pip]: https://pypi.org/project/pip/\n[PyPI]: https://pypi.org/\n\n## Citing\n```bibtex\n@article{wang2026high,\n title={High-Fidelity Long-term Whole-embryo Lineage and Fate Reconstruction by Iterative Tracking with Error Correction},\n author={Wang, Mengfan and Zhang, Qinghua and Wang, Congchao and Chi, Yunfeng and Zheng, Wei and Mu, Zeyu and Cao, Xiangyu and Zhang, Weizhan and Yang, Boao and Schier, Alexander F. and Acedo, Joaquin Navajas and Wan, Yinan and Yu, Guoqiang},\n year={2026},\n doi={10.64898/2026.03.12.711203}\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","magicgui","qtpy","scikit-image","scipy","pandas","tifffile","zarr","imageio","pyyaml","requests","dask","fsspec","numcodecs","pillow","matplotlib","napari[all]; extra == \"all\"","torch; extra == \"all\"","torchvision; extra == \"all\""],"requires_python":">=3.10","requires_external":null,"project_url":null,"provides_extra":["all"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}