Metadata-Version: 2.4
Name: focus-3d
Version: 0.1.2
Summary: FOCUS-3D: a user-friendly napari plugin for interactive 3D cell segmentation, curation, and analysis
Author: Qinghua Zhang
Author-email: zhangqh24@mails.tsinghua.edu.cn
License-Expression: BSD-3-Clause
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: magicgui
Requires-Dist: qtpy
Requires-Dist: scikit-image
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: tifffile
Requires-Dist: zarr
Requires-Dist: imageio
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: dask
Requires-Dist: fsspec
Requires-Dist: numcodecs
Requires-Dist: pillow
Requires-Dist: matplotlib
Provides-Extra: all
Requires-Dist: napari[all]; extra == "all"
Requires-Dist: torch; extra == "all"
Requires-Dist: torchvision; extra == "all"
Dynamic: license-file

# FOCUS-3D

[![License BSD-3](https://img.shields.io/pypi/l/cellseg.svg?color=green)](https://github.com/Qinghua24/cellseg/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/cellseg.svg?color=green)](https://pypi.org/project/cellseg)
[![Python Version](https://img.shields.io/pypi/pyversions/cellseg.svg?color=green)](https://python.org)
[![tests](https://github.com/Qinghua24/cellseg/workflows/tests/badge.svg)](https://github.com/Qinghua24/cellseg/actions)
[![codecov](https://codecov.io/gh/Qinghua24/cellseg/branch/main/graph/badge.svg)](https://codecov.io/gh/Qinghua24/cellseg)
[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/cellseg)](https://napari-hub.org/plugins/cellseg)
[![npe2](https://img.shields.io/badge/plugin-npe2-blue?link=https://napari.org/stable/plugins/index.html)](https://napari.org/stable/plugins/index.html)

FOCUS-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.

<img width="3839" height="2082" alt="image" src="https://github.com/user-attachments/assets/2a9ccc08-3109-4b73-bcae-0514bcec2a86" />

## Installation

### Windows

#### 1. Create a new environment

```bash
conda create -n focus3d python=3.10 -y
conda activate focus3d
```

#### 2. Install FOCUS-3D

```bash
pip install -U "focus-3d[all]"
```

#### 3. Launch napari

```bash
python -m napari
```

---

### Linux

#### 1. Create a new environment

```bash
conda create -n focus3d python=3.10 -y
conda activate focus3d
```

#### 2. Install PyTorch

For CUDA 12.6:

```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126
```

If your CUDA version is different, please install the corresponding PyTorch version from the official PyTorch installation guide.

#### 3. Install FOCUS-3D

```bash
pip install -U "focus-3d[all]"
```

#### 4. Install detectron2

```bash
pip install "git+https://github.com/facebookresearch/detectron2.git"
```

#### 5. Launch napari

```bash
python -m napari
```

## Usage

1. Open FOCUS-3D from `Plugins -> FOCUS-3D`.
2. Load the raw image from `File -> Open Folder` for a `.zarr` dataset(recommend), or `File -> Open File(s)` for `.tif` images.
3. 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.

## Basic Menu

The `Basic` menu provides functions for loading segmentation labels, adjusting image display, manually curating labels, and saving edited results.

### Load Label

| Operation | Description |
|---|---|
| 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. |
| Load from TIFF | Load an existing 3D label map from a `.tif` or `.tiff` file. |
| Only Show Contour | Display label contours instead of filled label masks, making it easier to inspect boundaries and compare labels with the raw image. |

### Display Settings

| Operation | Description |
|---|---|
| Minimum / Maximum | Adjust the display contrast range of the currently selected image layer. |
| Auto | Automatically estimate a suitable contrast range for the active image layer using robust intensity percentiles. |
| Reset Contrast | Reset the contrast range of the active image layer. |
| Channel Composite | Select one or more image layers and assign different colormaps for multi-channel visualization. |
| Apply | Apply the selected channel visibility and colormap settings. |
| Reset Display | Reset image layers to the default display mode. |

### Manual Curation

| Operation | Shortcut | Description |
|---|---|---|
| Enter Curation Mode | — | Activate label editing mode. Users can click on an existing label to select and modify it. |
| Polygon Draw Mode | — | Define an ROI by clicking polygon vertices. The enclosed region is used for label editing. |
| Brush Draw Mode | — | Define an ROI by painting directly on the image. The painted region is used for label editing. |
| Trace Draw Mode | — | Define an ROI using trace-based drawing. |
| Brush Size | `+` / `-` | Adjust the ROI brush size or label brush size. |
| Brush Color | — | Change the display color of the ROI brush. |
| Add to Label | `A` | Add the selected ROI to the currently selected label. |
| Subtract from Label | `S` | Remove the selected ROI from the currently selected label. |
| Add New Label | `Ctrl + D` | Create a new label. Regions from multiple Z slices can be combined into the same 3D instance. |
| Change Label | `C` | Change the ID of the currently selected label. |
| Apply ROI | `Ctrl + A` | Apply the current ROI operation. Used with **Add to Label**, **Subtract from Label**, and **Add New Label**. |
| Cancel ROI | `Ctrl + C` | Cancel the current ROI operation without applying changes. |
| Delete Current Z | `Delete` | Delete the selected label only on the current Z slice. |
| Delete All Z | `Ctrl + Delete` | Delete the selected label across all Z slices. |
| Delete Inside ROI (All Z) | — | Delete all labels inside the selected ROI across all Z slices. |
| Show Log File | — | Open or show the curation log file that records editing operations. |
| Previous Slice | `Q` | Move to the previous Z slice. |
| Next Slice | `W` | Move to the next Z slice. |
| Undo Local Refinement | `Ctrl + Z` | Undo the latest one-click local refinement result when available. |

### Save

| Operation | Description |
|---|---|
| Browse | Select the folder for saving the current label result. |
| Save format | Choose the output format, including `Zarr (recommended)` or `TIFF`. |
| Update Labels | Reassign label IDs before saving so that labels are stored in a clean consecutive order. |
| Save | Save the current label layer to the selected output path. |

## Segmentation Menu

The `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.
<img width="3839" height="2084" alt="image" src="https://github.com/user-attachments/assets/74b6b9ae-0a00-4b40-bb31-fb743709c725" />

### Run Segmentation

| Parameter / Operation | Description |
|---|---|
| Z Ratio | Set the physical Z-to-XY spacing ratio for anisotropic 3D data. |
| 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. |
| GPU IDs | Select the GPU device used for inference, such as `0`, `1`, or `0,1`. |
| Refresh | Refresh the list of available GPU devices. |
| Advanced | Expand or collapse advanced inference settings. |
| Checkpoint | Select the pretrained model checkpoint. The default path is relative to the backend folder. |
| Configure | Select the configuration file. The default configuration is `configs/3d_test.yaml`. |
| Lower / Upper Percentile | Set the intensity percentile range for image normalization before inference. |
| Patch size (Z/Y/X) | Set the 3D patch size used for sliding-window inference. |
| Stride (Z/Y/X) | Set the stride between neighboring inference patches. Smaller strides increase overlap but require more computation. |
| Background intensity | Ignore patches whose maximum intensity is below this threshold. |
| Batch size | Set the inference batch size. Larger values may improve speed but require more GPU memory. |
| Score confidence | Set the object-level confidence threshold for accepting predicted instances. |
| Mask confidence | Set the voxel-level mask confidence threshold for generating instance masks. |
| Min area (2D) | Remove small 2D components below the specified area threshold during stitching or post-processing. |
| Min size (3D) | Remove 3D objects smaller than the specified voxel size. A value of `0` disables minimum-size filtering. |
| Max size (3D) | Remove 3D objects larger than the specified voxel size. The default value is `100000`. |
| 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. |

### One-click Segmentation

| Operation | Description |
|---|---|
| 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. |
| Exit Inactive Mode | Exit one-click segmentation mode and return to normal interaction. |
| Status Label | Display the current status of the one-click segmentation module, such as inactive, loading, active, or busy. |
| Local Refinement | Use the pretrained FOCUS-3D model to refine a clicked cell or local region, supporting fast correction of missed or inaccurate instances. |
| Undo | Undo the latest one-click segmentation refinement result with `Ctrl + Z`. |

### Finetune with Current Labels

| Operation | Description |
|---|---|
| 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. |
| Select Patch ID | Select a valid patch by ID. The corresponding patch region is highlighted in the viewer. |
| Save Path | Set the folder for saving curated training patches. The expected structure is `imagesTr/` and `labelsTr/`. |
| Curate Selected Patch | Open the selected 3D patch in a new napari viewer for focused manual correction. |
| Save Curated Patch | Save the curated patch image and label into `imagesTr/` and `labelsTr/`. |
| Checkpoint Dir | Set the output directory for fine-tuned FOCUS-3D checkpoints. |
| 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. |

## Analysis Menu

The `Analysis` menu provides tools for 3D structure reconstruction, full-volume 3D visualization, and quantitative statistics.

<img width="3839" height="2087" alt="image" src="https://github.com/user-attachments/assets/7d499c7c-952c-4ad0-a2a4-5f1b9896d0f3" />

### 3D Label Reconstruction

| Operation | Description |
|---|---|
| Z Ratio | Set the physical Z-to-XY ratio for 3D reconstruction. This is important for anisotropic microscopy volumes. |
| Reconstruct Selected Label | Reconstruct the selected label as a 3D mesh for visualization and downstream analysis. |
| Load Mesh | Load a previously saved 3D mesh file. |
| Save Mesh | Save the reconstructed 3D mesh. |

### Full 3D View

| Operation | Description |
|---|---|
| Z Ratio | Set the Z-axis scaling factor for full-volume 3D visualization. |
| Switch to 3D View | Switch the current napari viewer between 2D slice view and 3D visualization mode. |

### Quantitative Statistics

| Operation | Description |
|---|---|
| Calculate Size Distribution | Calculate cell count and cell size distribution from the current label layer. This can be used for basic quantitative analysis of segmentation results. |

## Recommended Workflow

A typical workflow is:

1. Load the raw 3D microscopy image into napari.
2. Run automatic 3D segmentation with **FOCUS-3D** from the `Segmentation` menu.
3. Inspect the segmentation result in the `Basic` menu.
4. Correct segmentation errors using manual curation tools such as **Add to Label**, **Subtract from Label**, **Add New Label**, and **Delete Inside ROI**.
5. Use **One-click Segmentation** for fast local correction of difficult or missed cells.
6. Save the curated labels as `.zarr` or `.tif`.
7. Optionally select valid curated patches and fine-tune FOCUS-3D with the corrected labels.
8. Use the `Analysis` menu for 3D reconstruction, full 3D visualization, and quantitative statistics.

## License

Distributed under the terms of the [BSD-3] license, `FOCUS-3D` is free and open source software.

## Issues

If you encounter any problems, please [file an issue] along with a detailed description or contact zhangqh24@mails.tsinghua.edu.cn.

[napari]: https://github.com/napari/napari
[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/

## Citing
```bibtex
@article{wang2026high,
  title={High-Fidelity Long-term Whole-embryo Lineage and Fate Reconstruction by Iterative Tracking with Error Correction},
  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},
  year={2026},
  doi={10.64898/2026.03.12.711203}
}
```
