Finds and counts stomata in microscopic images of leaves. This is code for developers who intend to build their own web service or train their own models. If you just want to evaluate images, you can use our existing service running at http://www.stomata.science/

Download the latest version of the code:

mkdir ~/epidermal
git clone https://github.com/SvenTwo/epidermal.git ~/epidermal/
cd ~/epidermal

The project is python2.7-based using caffe for the CNN processing. First install caffe http://caffe.berkeleyvision.org/installation.html and remember to also install the python bindings (make pycaffe if you compile yourself). For all basic python dependencies (you may want to enter a virtualenv to install all dependencies in usermode if desired first):

for req in $(cat requirements.txt); do pip install $req; done 

pyIMQ for image quality measures is also required and can be found here: https://github.com/danielsnider/PyImageQualityRanking - if pyimq is not installed, the service should run but image quality measures will not be available.

If you prefer to not use the web service, a script can be used for batch processing locally. It can be used to input a set of images and output CSV file with stomata counts, and optionally create heatmaps of each processed image.

Download the pre-trained model weights from here [Download] and unzip the two files (sc_feb2019.caffemodel and sc_feb2019.prototxt).

The processing command allows tweaking various settings such as the input scale and detection threshold. The interface is:

python2.7 process_images.py [-h] --weights-filename WEIGHTS_FILENAME
                     --proto-filename PROTO_FILENAME
                     [--gpu-index GPU_INDEX]
                     [--cnn-top-layer-name CNN_TOP_LAYER_NAME]
                     [--scale SCALE]
                     [--heatmap-output-path HEATMAP_OUTPUT_PATH]
                     [--plot-contours] [--plot-no-peaks]
                     [--prob-threshold PROB_THRESHOLD]
                     [--prob-area-threshold PROB_AREA_THRESHOLD]
                     --csv-output-filename CSV_OUTPUT_FILENAME
                     [--output-fields {count,image_filename,imq_entropy,imq_hf_entropy,imq_hf_kurtosis,imq_hf_mean,imq_hf_power,imq_hf_skewness,imq_hf_std,imq_hf_threshfreq,margin,positions,scale} [{count,image_filename,imq_entropy,imq_hf_entropy,imq_hf_kurtosis,imq_hf_mean,imq_hf_power,imq_hf_skewness,imq_hf_std,imq_hf_threshfreq,margin,positions,scale} ...]]
                     [--verbose]
                     image-paths [image-paths ...]

From the downloaded model, pass the .caffemodel as --weights-filename and the .prototxt as --proto-filename. For example:

TODO

The project consists of three different services that communicate via a MongoDb and a locally mounted filesystem:

1. The web service is a python flask-based service that serves the web page, allows uploads and issues processing and training requests via the database.

2. The processing worker is a python-based worker service that listens for images to be processed on the database and processes them as needed. It uses a GPU if available. Multiple processing workers can be run in parallel to allow faster throughput, although that feature hasn't been tested extensively.

3. The training worker is a python-based worker service that listens for training requests issued by the admin interface of the web service. It has to run on a GPU. The training worker is not required to run the service. It would typically run on the same GPU as the processing worker.

All services share a configuration file from the home path of the current user (~/.epidermal). To create a file with default values, either run one of the services or just run from the command line:

python2.7 config.py

Following is the meaning of the fields. Remember to configure an admin password and security cookies before the first start:

The web service is located in webapp.py, which can simply be run to serve directly from flask. However, it is recommended to use a more powerful standalone web server to allow multiple processes. The app is available in wsgi.py. To launch e.g. via gunicorn (http://docs.gunicorn.org/en/stable/install.html):

gunicorn --timeout 1200 --workers 3 --bind 0.0.0.0:8000 wsgi

This would launch the service on port 8000. You can then open a browser on http://localhost:8000/ to test if things work. If you want to host publicly, I recommend to forward port 80 to 8000 instead of hosting directly on the low port, so that the app can be run without root privileges. Annotation and custom model training can be done via the admin interface on the web service.

When images are uploaded, the web service puts worker jobs into a MongoDB. The actual computation is handled by a separate process which can be launched as:

 python2.7 apply_worker.py

Note that the apply worker needs to have a model saved in the database (either trained via annotations from the web interface or imported from another service).

The service can be run without extra training if only inference should be done. If you want to improve the model using annotated images, launch a train worker using:

 python2.7 train_worker.py

As with inference, training jobs can be launched via the web interface.