Metadata-Version: 2.1
Name: pydeepimagej
Version: 1.0.0
Summary: Python package to export TensorFlow models as DeepImageJ bundled models
Home-page: https://deepimagej.github.io/deepimagej/
Author: C. Garcia-Lopez-de-Haro, E. Gomez-de-Mariscal, L. Donati, M. Unser, A. Munoz-Barrutia, D. Sage.
Author-email: esgomezm@pa.uc3m.com, daniel.sage@epfl.ch, mamunozb@ing.uc3m.es
License: BSD 2-Clause License
Download-URL: https://github.com/deepimagej/pydeepimagej/archive/v1.0.0.tar.gz
Keywords: Fiji,ImageJ,DeepImageJ,Deep Learning,Image processing
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.0
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scikit-image

# PyDeepImageJ

[![GitHub](https://img.shields.io/github/license/deepimagej/pydeepimagej)](https://raw.githubusercontent.com/deepimagej/pydeepimagej/master/LICENSE)
[![minimal Python version](https://img.shields.io/badge/Python-3-6666ff.svg)](https://www.anaconda.com/distribution/)

Python code to export trained models and read them in Fiji & ImageJ using DeepImageJ plugin
  - Create a configuration class in python with all the information about the trained model, needed for its correct use in Fiji & ImageJ.
  - Include the metadata of an example image.
  - Include all expected results and needed pre / post-processing routines.
  - See [DeepImageJ webpage](https://deepimagej.github.io/deepimagej/) for more information. 

### Installation
**Requirements**
- PyDeepImageJ requires Python 3 to run. 
- TensorFlow: It runs using the local installation of TensorFlow, i.e. the one corresponding to the trained model. However, DeepImageJ is only compatible with TensorFlow versions <= 2.2.1.

To install PyDeepImageJ either clone this repository or use PyPi via `pip`:

```sh
$ pip install pydeepimagej
```
or
```sh
$ git clone https://github.com/deepimagej/pydeepimagej.git
$ cd pydeepimagej
$ python setup.py install
```

### Example of how to use it

Let `model` be a Keras or TensorFlow trained model. Initialize the configuration class with the trained model `model`
````
dij_config = DeepImageJConfig(model)
````
Update model information
````
dij_config.Name = 'My trained model v0.1'
dij_config.Authors = 'First author; Secon Author; Third Author'
dij_config.Credits = 'Institution 1; Institution 2; Institution 3'
dij_config.URL        = 'https://github.com/user/your_model'
dij_config.Version    = '0.1'
dij_config.References = 'C. GarcÃ­a-LÃ³pez-de-Haro et al., bioRxiv 2019'
dij_config.Date       = 'September-2020'
````
**Prepare an ImageJ pre/post-processing macro.** 
You may need to preprocess the input image before the inference. Some ImageJ macro routines can be downloaded from [here](https://github.com/deepimagej/imagej-macros/) and included in the model specifications. Note that ImageJ macros are text files so it is easy to modify them inside a Python script ([see an example](https://github.com/deepimagej/pydeepimagej/blob/master/README.md#additional-commands)):
````
path_preprocessing = "PercentileNormalization.ijm"`
# Download the macro file
urllib.request.urlretrieve("https://raw.githubusercontent.com/deepimagej/imagej-macros/master/PercentileNormalization.ijm", path_preprocessing )
# Include it in the configuration class
dij_config.add_preprocessing(path_preprocessing, "preprocessing")
````
The same holds for the postprocessing.
````
path_postprocessing = "8bitBinarize.ijm"
urllib.request.urlretrieve("https://raw.githubusercontent.com/deepimagej/imagej-macros/master/8bitBinarize.ijm", path_postprocessing )
# Include the info about the postprocessing 
dij_config.add_postprocessing(path_postprocessing,"postprocessing")
````
It is even possible to include different pre/post-processing routines in the same model as long as their names always start with "preprocessing" or "postprocessing" respectively: 
````
path_second_postprocessing = "./folder/another_macro.ijm"
dij_config.add_postprocessing(path_second_postprocessing, "postprocessing_2")
````

**Add information about the example image.**
Let `test_img` be an example image to test the model inference and `test_prediction` be the resulting image after the post-processing. It is possible to export the trained model with these two, so an end user can see an example. 
`PixelSize` should be given in microns (Âµm). 
````
dij_config.add_test_info(test_img, test_prediction, PixelSize)
````

**EXPORT THE MODEL**
````
deepimagej_model_path = './my_trained_model_deepimagej'
dij_config.export_model(model, deepimagej_model_path)
`````
### Additional commands
**Change one line in an ImageJ macro**
````
# Download the macro file
path_postprocessing = "8bitBinarize.ijm"
urllib.request.urlretrieve("https://raw.githubusercontent.com/deepimagej/imagej-macros/master/8bitBinarize.ijm", path_postprocessing )
# Modify the threshold in the macro to the chosen threshold
ijmacro = open(path_postprocessing,"r")  
list_of_lines = ijmacro. readlines()
# Line 21 is the one corresponding to the optimal threshold
list_of_lines[21] = "optimalThreshold = {}\n".format(128)
ijmacro.close()
ijmacro = open(path_postprocessing,"w")  
ijmacro. writelines(list_of_lines)
ijmacro. close()
````
**Estimation of the step size for the shape of the input image.**
If the model is an encoder-decoder with skip connections, and the input shape of your trained model is not fixed (i.e. `[None, None, 1]` ), the input shape still needs to fit some requirements. You can caluculate it knowing the number of poolings in the encoder path of the network:
````
import numpy as np
pooling_steps = 0
for keras_layer in model.layers:
    if keras_layer.name.startswith('max') or "pool" in keras_layer.name:
      pooling_steps += 1
dij_config.MinimumSize = np.str(2**(pooling_steps))
````
### Todo list

 - Write bioimage.IO config.yaml class

Reference: 
----
E. Gomez-de-Mariscal, C. Garcia-Lopez-de-Haro, L. Donati, M. Unser, A. Munoz-Barrutia, D. Sage. 
*DeepImageJ: A user-friendly plugin to run deep learning models in ImageJ*, bioRxiv 2019
DOI: [https://doi.org/10.1101/799270](https://doi.org/10.1101/799270)
- Bioengineering and Aerospace Engineering Department, Universidad Carlos III de Madrid, Spain
- Biomedical Imaging Group, Ecole polytechnique federale de Lausanne (EPFL), Switzerland

Corresponding authors: mamunozb@ing.uc3m.es, daniel.sage@epfl.ch
Copyright Â© 2019. Universidad Carlos III, Madrid; Spain and EPFL, Lausanne, Switzerland.

License
----
[BSD 2-Clause License](https://raw.githubusercontent.com/deepimagej/pydeepimagej/master/LICENSE)


