Metadata-Version: 2.4
Name: morphodeep
Version: 0.1
Summary: Instance segmentation of membranes in 2D and 3D microscopy images
Author-email: Emmanuel Faure <emmanuel.faure@lirmm.fr>
License-Expression: LGPL-3.0-only
Project-URL: Homepage, https://codeberg.org/FaureEmmanuel/MorphoDeep
Project-URL: Source code, https://codeberg.org/FaureEmmanuel/MorphoDeep
Project-URL: Documentation, https://faureemmanuel.codeberg.page/MorphoDeep/
Project-URL: Issues, https://codeberg.org/FaureEmmanuel/MorphoDeep/issues
Project-URL: Model weights, https://doi.org/10.6084/m9.figshare.34245426
Keywords: image analysis,bioimage,segmentation,instance-segmentation,deep learning,unet,napari plugin,microscopy
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: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: <3.12,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: tqdm
Requires-Dist: tensorflow==2.15.0
Requires-Dist: scikit-image
Requires-Dist: matplotlib
Requires-Dist: nibabel
Requires-Dist: scipy
Requires-Dist: h5py
Requires-Dist: paramiko
Requires-Dist: scp
Requires-Dist: pandas
Requires-Dist: appdirs
Requires-Dist: tifffile
Provides-Extra: napari
Requires-Dist: napari>=0.4.19; extra == "napari"
Requires-Dist: magicgui>=0.6.0; extra == "napari"
Requires-Dist: PyQt5; extra == "napari"
Requires-Dist: qtpy>=2.0.0; extra == "napari"
Provides-Extra: figures
Requires-Dist: colorcet>=3; extra == "figures"
Requires-Dist: imageio>=2; extra == "figures"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]<1,>=0.27; extra == "docs"
Dynamic: license-file

# MorphoDeep

MorphoDeep segments individual cells in grayscale microscopy images of membranes. It supports 2D images and 3D volumes and returns an integer label image: `0` is background, and each positive value identifies one cell. The package provides a command-line interface, a Python API, and napari widgets for prediction and fine tuning.

## Install

MorphoDeep 0.1 supports Python 3.10 and 3.11. Install the library with:

```bash
python -m pip install morphodeep
```

To use the napari widgets, install the optional graphical dependencies:

```bash
python -m pip install 'morphodeep[napari]'
```

TensorFlow 2.15 is installed as a package dependency. GPU setup depends on the operating system and hardware; consult the [TensorFlow installation guide](https://www.tensorflow.org/install) if GPU support is needed.

## Predict cell instances

Pass a grayscale TIFF image or volume to the command-line tool:

```bash
morphodeep predict image.tif image_instances.tif --mode 2D
morphodeep predict volume.tif volume_instances.tif --mode 3D --size 128
```

The dimension can be inferred from the TIFF file. The default model size is 256 in 2D and 128 in 3D; a 256 model is also available in 3D. Predictions use overlapping patches by default. Use `--no-patches` for whole-image inference, `--weights path/to/model.h5` for custom weights, and `--overwrite` to replace an output file.

In Python:

```python
from morphodeep.napari.model import run_instance_segmentation

labels = run_instance_segmentation(image, mode="2D", net_size=256)
```

The result has the same shape as the input and contains integer instance labels.

### Pretrained weights

The three pretrained models are hosted separately in the [MorphoDeep weights dataset on Figshare](https://doi.org/10.6084/m9.figshare.34245426):

| Mode | Model | File |
| --- | --- | --- |
| 2D, size 256 | DUNNET | `DUNNET_256.13331.h5` |
| 3D, size 128 | JUNNET | `JUNNET_128.6228.h5` |
| 3D, size 256 | JUNNET | `JUNNET_256.2020.h5` |

MorphoDeep downloads the selected file on first use, verifies its SHA-256 digest, and caches it for later offline use. The weights are not included in the Python package. To use files already on disk, pass `--weights` to prediction or set `MORPHODEEP_WEIGHTS_DIR` to a directory containing the published filenames, either directly or under `2D/` and `3D/` subdirectories.

## Fine tune on your own data

Provide grayscale TIFF images and corresponding instance masks in separate directories. Files are paired by name before the extension, and images and masks must have the same shape. In each mask, `0` is background and each positive integer identifies one cell.

```bash
morphodeep finetune --images data/images --masks data/masks \
  --output runs/my_cells --mode 2D --epochs 20
```

Use `--mode 3D` for volumes. At least two image and mask pairs are required. By default, whole images are split reproducibly into training and validation sets. Related images, such as slices from the same volume, should use independent validation directories via `--validation-images` and `--validation-masks`. The best weights are written to `runs/my_cells/best.weights.h5` and can be used for prediction:

```bash
morphodeep predict image.tif image_instances.tif \
  --weights runs/my_cells/best.weights.h5
```

Fine tuning is also available through `morphodeep.training.fine_tune` and the **Fine tune model** napari widget. The **Predict instances** widget accepts the resulting file in its **Custom weights** field.

## Documentation and research code

The `docs/` directory contains installation, prediction, fine-tuning, napari, and Python API guides. From a source checkout, build the documentation with:

```bash
python -m pip install -e '.[docs]'
python -m mkdocs build --strict
```

The historical training and data preparation workflow is documented in `docs/research/legacy_training.md`. It is separate from the supported `morphodeep finetune` command and may require research-cluster resources.

## Source and issues

The [source code](https://codeberg.org/FaureEmmanuel/MorphoDeep) and [issue tracker](https://codeberg.org/FaureEmmanuel/MorphoDeep/issues) are on Codeberg. Read the [full documentation](https://faureemmanuel.codeberg.page/MorphoDeep/) for the installation guide, examples, and Python API.

## License

MorphoDeep is distributed under the [GNU LGPL v3.0 license](https://www.gnu.org/licenses/lgpl-3.0.html). The Figshare weights dataset has its own [CC BY 4.0 license](https://doi.org/10.6084/m9.figshare.34245426).
