Release v1.0.0b1 (tf.keras) (#162)

* Support for keras and tf.keras * Focal loss; precision and recall metrics * New losses and metrics functionality: aggregation and multiplication by factor * NCHW and NHWC support * Removed pure `tf` operations to work with other keras backends * Reduced a number of custom objects for better models serialization and deserialization
qubvel · Aug 9, 2019 · 5f40c09 · 5f40c09
1 parent b6e1d65
commit 5f40c09
Show file tree

Hide file tree

Showing 55 changed files with 4,355 additions and 2,999 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,7 @@ __pycache__/
 *.py[cod]
 *$py.class
 .idea/
+*ipynb
 
 # C extensions
 *.so

diff --git a/.travis.yml b/.travis.yml
@@ -4,16 +4,10 @@ language: python
 
 matrix:
     include:
-        # different pythons
-        - python: 3.5
-
-        # different keras versions
-        - python: 3.6
-          env: KERAS_VERSION=head
-        - python: 3.6
-          env: KERAS_VERSION=2.2.0
         - python: 3.6
           env: KERAS_VERSION=2.2.4
+        - python: 3.6
+          env: SM_FRAMEWORK='tf.keras'
 
 git:
   submodules: true
@@ -23,11 +17,7 @@ install:
   # code below is taken from http://conda.pydata.org/docs/travis.html
   # We do this conditionally because it saves us some downloading if the
   # version is the same.
-  - if [[ "$TRAVIS_PYTHON_VERSION" == "2.7" ]]; then
-      wget https://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh;
-    else
-      wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
-    fi
+  - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
   - bash miniconda.sh -b -p $HOME/miniconda
   - export PATH="$HOME/miniconda/bin:$PATH"
   - hash -r
@@ -38,31 +28,27 @@ install:
 
   - conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION pytest pandas
   - source activate test-environment
-  - pip install --only-binary=numpy,scipy numpy nose scipy matplotlib h5py theano scikit-image
+  - pip install --only-binary=numpy,scipy numpy nose scipy matplotlib h5py theano
+
+
+  # set library path
+  - export LD_LIBRARY_PATH=$HOME/miniconda/envs/test-environment/lib/:$LD_LIBRARY_PATH
+  - conda install mkl mkl-service
+
+  # install TensorFlow (CPU version).
+  - pip install tensorflow==1.14
 
   # install keras
-  - if [[ $KERAS_VERSION == "head" ]]; then
-      pip install --no-deps git+https://github.com/keras-team/keras.git;
-    elif [ -z $KERAS_VERSION ]; then
-      pip install keras;
+  - if [ -z $KERAS_VERSION ]; then
+      echo "Using tf.keras";
     else
+      echo "Using keras";
       pip install keras==$KERAS_VERSION;
     fi
 
-  - conda install mkl mkl-service
-
-  # set library path
-  - export LD_LIBRARY_PATH=$HOME/miniconda/envs/test-environment/lib/:$LD_LIBRARY_PATH
-
   # install lib in develop mode
   - pip install -e .[tests]
 
-  # install TensorFlow (CPU version).
-  - pip install tensorflow==1.9
-
-  # install pydot for visualization tests
-  - conda install pydot graphviz
-
   # detect one of markdown files is changed or not
   - export DOC_ONLY_CHANGED=False;
   - if [ $(git diff --name-only HEAD~1 | wc -l) == "1" ] && [[ "$(git diff --name-only HEAD~1)" == *"md" ]]; then
@@ -72,18 +58,17 @@ install:
 # command to run tests
 script:
   - export MKL_THREADING_LAYER="GNU"
-  - export KERAS_BACKEND="tensorflow"
-  # run keras backend init to initialize backend config
-  - python -c "import keras.backend"
-  # create models directory to avoid concurrent directory creation at runtime
-  - mkdir ~/.keras/models
+  - mkdir -p ~/.keras/models
   # set up keras backend
-  - sed -i -e 's/"backend":[[:space:]]*"[^"]*/"backend":\ "'$KERAS_BACKEND'/g' ~/.keras/keras.json;
-  - echo -e "Running tests with the following config:\n$(cat ~/.keras/keras.json)"
   - if [[ "$DOC_ONLY_CHANGED" == "False" ]]; then
-      if [[ "$TEST_MODE" == "PEP8" ]]; then
-        PYTHONPATH=$PWD:$PYTHONPATH py.test --pep8 -m pep8 -n0;
-      else
         PYTHONPATH=$PWD:$PYTHONPATH py.test tests/;
-      fi;
-    fi
+    fi
+
+deploy:
+  provider: pypi
+  user: qubvel
+  password:
+    secure: QA/UJmkXGlXy/6C8X0E/bPf4izu3rJsztaEmqIM1npxPiv2Uf4WFs43vxkMXwfHrflocdfw8SBM8bWnbunGT2SvDdo/MMCMpol7unE74T/RbODYl6aiJWVM3QKOXL8pQD0oQ+03L1YK3nCeSQdePINEPmuFmvwyO40q8Dwv8HBZIGZlEo4SK4xr8ekxfmtbezxQ7vUL3sNcvCJDXrZX/4UdXrhdRk+zYoN3dv8NmM4FmChajq/m5Am9OPdbdUBHmIYmvk7L3IpwJeMMpG5FVdGNVwYj7XNHlcy+KZ2/CKn9EpslRDPxY4650654PmhSZWDctZG7jiFWLCZBUvowiyAOPZknZNgdu5gJAfdg37XS9IP3HgTZN6Jb5Bm0by3IlKt+dTzyJQcUnRql5B1wwEI0XO3/YWQe1GQQphIO1bli9hT8n8xNDNjc49vDlu4zKyaYnQmLhqNxkyeruXSTpc8qTITuS+EGgkAUrrBj/IaFcutIg9WOzvJ3nZO8X8UG7LlyQx4AOpfHP6bynAmlT+UFccCEq66Zoh7teWLk0lUekuYST2iQJ3pwFoQGYJRCsmxsz7J0B9ayFVVT/fg+GZpZm1oTnnJ27hh8LZWv/Cr/WHOBYc3qvigWx4pDssJ+O6z7de3aWrGvzAVgXr190fRdP55a34HhNbiKZ0YWmrTs=
+  on:
+    tags: true
+  skip_existing: true
diff --git a/README.rst b/README.rst
@@ -19,21 +19,30 @@
 `Image
 Segmentation <https://en.wikipedia.org/wiki/Image_segmentation>`__ based
 on `Keras <https://keras.io>`__
-(`Tensorflow <https://www.tensorflow.org/>`__) framework.
+and `Tensorflow Keras <https://www.tensorflow.org/>`__ frameworks.
 
 **The main features** of this library are:
 
--  High level API (just two lines to create NN)
--  **4** models architectures for binary and multi class segmentation
+-  High level API (just two lines of code to create model for segmentation)
+-  **4** models architectures for binary and multi-class image segmentation
    (including legendary **Unet**)
 -  **25** available backbones for each architecture
 -  All backbones have **pre-trained** weights for faster and better
    convergence
+- Helpful segmentation losses (Jaccard, Dice, Focal) and metrics (IoU, F-score)
+
+**Important note**
+
+    Some models of version ``1.*`` are not compatible with previously trained models,
+    if you have such models and want to load them - roll back with:
+
+    $ pip install -U segmentation-models==0.2.1
 
 Table of Contents
 ~~~~~~~~~~~~~~~~~
  - `Quick start`_
  - `Simple training pipeline`_
+ - `Examples`_
  - `Models and Backbones`_
  - `Installation`_
  - `Documentation`_
@@ -43,36 +52,58 @@ Table of Contents
 
 Quick start
 ~~~~~~~~~~~
-Since the library is built on the Keras framework, created segmentaion model is just a Keras Model, which can be created as easy as:
+Library is build to work together with Keras and TensorFlow Keras frameworks
 
 .. code:: python
 
-    from segmentation_models import Unet
+    import segmentation_models as sm
+    # Segmentation Models: using `keras` framework.
+
+By default it tries to import ``keras``, if it is not installed, it will try to start with ``tensorflow.keras`` framework.
+There are several ways to choose framework:
+
+- Provide environment variable ``SM_FRAMEWORK=keras`` / ``SM_FRAMEWORK=tf.keras`` before import ``segmentation_models``
+- Change framework ``sm.set_framework('keras')`` /  ``sm.set_framework('tf.keras')``
+
+You can also specify what kind of ``image_data_format`` to use, segmentation-models works with both: ``channels_last`` and ``channels_first``.
+This can be useful for further model conversion to Nvidia TensorRT format or optimizing model for cpu/gpu computations.
+
+.. code:: python
+
+    import keras
+    # or from tensorflow import keras
+
+    keras.backend.set_image_data_format('channels_last')
+    # or keras.backend.set_image_data_format('channels_first')
+
+Created segmentaion model is just an instance of Keras Model, which can be build as easy as:
+
+.. code:: python
     
-    model = Unet()
+    model = sm.Unet()
     
 Depending on the task, you can change the network architecture by choosing backbones with fewer or more parameters and use pretrainded weights to initialize it:
 
 .. code:: python
 
-    model = Unet('resnet34', encoder_weights='imagenet')
+    model = sm.Unet('resnet34', encoder_weights='imagenet')
 
 Change number of output classes in the model (choose your case):
 
 .. code:: python
     
     # binary segmentation (this parameters are default when you call Unet('resnet34')
-    model = Unet('resnet34', classes=1, activation='sigmoid')
+    model = sm.Unet('resnet34', classes=1, activation='sigmoid')
     
 .. code:: python
     
     # multiclass segmentation with non overlapping class masks (your classes + background)
-    model = Unet('resnet34', classes=3, activation='softmax')
+    model = sm.Unet('resnet34', classes=3, activation='softmax')
     
 .. code:: python
     
     # multiclass segmentation with independent overlapping/non-overlapping class masks
-    model = Unet('resnet34', classes=3, activation='sigmoid')
+    model = sm.Unet('resnet34', classes=3, activation='sigmoid')
     
     
 Change input shape of the model:
@@ -88,39 +119,45 @@ Simple training pipeline
 
 .. code:: python
 
-   from segmentation_models import Unet
-   from segmentation_models.backbones import get_preprocessing
-   from segmentation_models.losses import bce_jaccard_loss
-   from segmentation_models.metrics import iou_score
-   
-   BACKBONE = 'resnet34'
-   preprocess_input = get_preprocessing(BACKBONE)
-   
-   # load your data
-   x_train, y_train, x_val, y_val = load_data(...)
-   
-   # preprocess input
-   x_train = preprocess_input(x_train)
-   x_val = preprocess_input(x_val)
-   
-   # define model
-   model = Unet(BACKBONE, encoder_weights='imagenet')
-   model.compile('Adam', loss=bce_jaccard_loss, metrics=[iou_score])
-   
-   # fit model
-   # if you use data generator use model.fit_generator(...) instead of model.fit(...)
-   # more about `fit_generator` here: https://keras.io/models/sequential/#fit_generator
-   model.fit(
-       x=x_train, 
-       y=y_train, 
-       batch_size=16, 
+    import segmentation_models as sm
+
+    BACKBONE = 'resnet34'
+    preprocess_input = sm.get_preprocessing(BACKBONE)
+
+    # load your data
+    x_train, y_train, x_val, y_val = load_data(...)
+
+    # preprocess input
+    x_train = preprocess_input(x_train)
+    x_val = preprocess_input(x_val)
+
+    # define model
+    model = sm.Unet(BACKBONE, encoder_weights='imagenet')
+    model.compile(
+        'Adam',
+        loss=sm.losses.bce_jaccard_loss,
+        metrics=[sm.metrics.iou_score],
+    )
+
+    # fit model
+    # if you use data generator use model.fit_generator(...) instead of model.fit(...)
+    # more about `fit_generator` here: https://keras.io/models/sequential/#fit_generator
+    model.fit(
+       x=x_train,
+       y=y_train,
+       batch_size=16,
        epochs=100,
        validation_data=(x_val, y_val),
-   )
-   
+    )
 
 Same manimulations can be done with ``Linknet``, ``PSPNet`` and ``FPN``. For more detailed information about models API and  use cases `Read the Docs <https://segmentation-models.readthedocs.io/en/latest/>`__.
 
+Examples
+~~~~~~~~
+Models training examples:
+ - [Jupyter Notebook] Binary segmentation (`cars`) on CamVid dataset `here <https://github.com/qubvel/segmentation_models/blob/master/examples/binary%20segmentation%20(camvid).ipynb>`__.
+ - [Jupyter Notebook] Multi-class segmentation (`cars`, `pedestrians`) on CamVid dataset `here <https://github.com/qubvel/segmentation_models/blob/master/examples/multiclass%20segmentation%20(camvid).ipynb>`__.
+
 Models and Backbones
 ~~~~~~~~~~~~~~~~~~~~
 **Models**
@@ -135,6 +172,7 @@ Unet          Linknet
 ============= ==============
 |unet_image|  |linknet_image|
 ============= ==============
+
 ============= ==============
 PSPNet        FPN
 ============= ==============
@@ -167,7 +205,7 @@ PSPNet        FPN
     DenseNet       ``'densenet121' 'densenet169' 'densenet201'`` 
     Inception      ``'inceptionv3' 'inceptionresnetv2'``
     MobileNet      ``'mobilenet' 'mobilenetv2'``
-    EfficientNet   ``'efficientnetb0' 'efficientnetb1' 'efficientnetb2' 'efficientnetb3'``
+    EfficientNet   ``'efficientnetb0' 'efficientnetb1' 'efficientnetb2' 'efficientnetb3' 'efficientnetb4' 'efficientnetb5' efficientnetb6' efficientnetb7'``
     =============  =====
 
 .. epigraph::
@@ -179,19 +217,25 @@ Installation
 
 **Requirements**
 
-1) Python 3.5+
-2) Keras >= 2.2.0
-3) Keras Application >= 1.0.7
-4) Image Classifiers == 0.2.0
-5) Tensorflow 1.9 (tested)
+1) python 3
+2) keras >= 2.2.0 or tensorflow >= 1.13
+3) keras-applications >= 1.0.7, <=1.0.8
+4) image-classifiers == 1.0.*
+5) efficientnet == 1.0.*
+
+**PyPI stable package**
+
+.. code:: bash
+
+    $ pip install -U segmentation-models
 
-**Pip package**
+**PyPI latest package**
 
 .. code:: bash
 
-    $ pip install segmentation-models
+    $ pip install -U --pre segmentation-models
 
-**Latest version**
+**Source latest version**
 
 .. code:: bash
 

diff --git a/docs/api.rst b/docs/api.rst
@@ -22,16 +22,18 @@ PSPNet
 
 metrics
 ~~~~~~~
-.. autofunction:: segmentation_models.metrics.iou_score
-.. autofunction:: segmentation_models.metrics.f_score
+.. autofunction:: segmentation_models.metrics.IOUScore
+.. autofunction:: segmentation_models.metrics.FScore
 
 losses
 ~~~~~~
-.. autofunction:: segmentation_models.losses.jaccard_loss
-.. autofunction:: segmentation_models.losses.dice_loss
-
+.. autofunction:: segmentation_models.losses.JaccardLoss
+.. autofunction:: segmentation_models.losses.DiceLoss
+.. autofunction:: segmentation_models.losses.BinaryCELoss
+.. autofunction:: segmentation_models.losses.CategoricalCELoss
+.. autofunction:: segmentation_models.losses.BinaryFocalLoss
+.. autofunction:: segmentation_models.losses.CategoricalFocalLoss
 
 utils
 ~~~~~
-.. autofunction:: segmentation_models.backbones.get_preprocessing
 .. autofunction:: segmentation_models.utils.set_trainable
diff --git a/docs/conf.py b/docs/conf.py
@@ -184,4 +184,11 @@
 
 # -- Extension configuration -------------------------------------------------
 
-autodoc_mock_imports = ['skimage', 'tensorflow']
+autodoc_mock_imports = [
+    'skimage',
+    'keras',
+    'tensorflow',
+    'efficientnet',
+    'classification_models',
+    'keras_applications',
+]
diff --git a/docs/install.rst b/docs/install.rst
@@ -3,11 +3,11 @@ Installation
 
 **Requirements**
 
-1) Python 3.5+
-2) Keras >= 2.2.0
-3) Keras Applications >= 1.7.0
-4) Image Classifiers == 0.2.0
-5) Tensorflow 1.9 (tested)
+1) Python 3
+2) Keras >= 2.2.0 or TensorFlow >= 1.13
+3) keras-applications >= 1.0.7, <=1.0.8
+4) image-classifiers == 1.0.0
+5) efficientnet == 1.0.0
 
 
 .. note::