Skip to content

Commit 5f40c09

Browse files
authored
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
1 parent b6e1d65 commit 5f40c09

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+4355
-2999
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ __pycache__/
33
*.py[cod]
44
*$py.class
55
.idea/
6+
*ipynb
67

78
# C extensions
89
*.so

.travis.yml

Lines changed: 26 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,10 @@ language: python
44

55
matrix:
66
include:
7-
# different pythons
8-
- python: 3.5
9-
10-
# different keras versions
11-
- python: 3.6
12-
env: KERAS_VERSION=head
13-
- python: 3.6
14-
env: KERAS_VERSION=2.2.0
157
- python: 3.6
168
env: KERAS_VERSION=2.2.4
9+
- python: 3.6
10+
env: SM_FRAMEWORK='tf.keras'
1711

1812
git:
1913
submodules: true
@@ -23,11 +17,7 @@ install:
2317
# code below is taken from http://conda.pydata.org/docs/travis.html
2418
# We do this conditionally because it saves us some downloading if the
2519
# version is the same.
26-
- if [[ "$TRAVIS_PYTHON_VERSION" == "2.7" ]]; then
27-
wget https://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh;
28-
else
29-
wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
30-
fi
20+
- wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
3121
- bash miniconda.sh -b -p $HOME/miniconda
3222
- export PATH="$HOME/miniconda/bin:$PATH"
3323
- hash -r
@@ -38,31 +28,27 @@ install:
3828

3929
- conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION pytest pandas
4030
- source activate test-environment
41-
- pip install --only-binary=numpy,scipy numpy nose scipy matplotlib h5py theano scikit-image
31+
- pip install --only-binary=numpy,scipy numpy nose scipy matplotlib h5py theano
32+
33+
34+
# set library path
35+
- export LD_LIBRARY_PATH=$HOME/miniconda/envs/test-environment/lib/:$LD_LIBRARY_PATH
36+
- conda install mkl mkl-service
37+
38+
# install TensorFlow (CPU version).
39+
- pip install tensorflow==1.14
4240

4341
# install keras
44-
- if [[ $KERAS_VERSION == "head" ]]; then
45-
pip install --no-deps git+https://github.com/keras-team/keras.git;
46-
elif [ -z $KERAS_VERSION ]; then
47-
pip install keras;
42+
- if [ -z $KERAS_VERSION ]; then
43+
echo "Using tf.keras";
4844
else
45+
echo "Using keras";
4946
pip install keras==$KERAS_VERSION;
5047
fi
5148

52-
- conda install mkl mkl-service
53-
54-
# set library path
55-
- export LD_LIBRARY_PATH=$HOME/miniconda/envs/test-environment/lib/:$LD_LIBRARY_PATH
56-
5749
# install lib in develop mode
5850
- pip install -e .[tests]
5951

60-
# install TensorFlow (CPU version).
61-
- pip install tensorflow==1.9
62-
63-
# install pydot for visualization tests
64-
- conda install pydot graphviz
65-
6652
# detect one of markdown files is changed or not
6753
- export DOC_ONLY_CHANGED=False;
6854
- if [ $(git diff --name-only HEAD~1 | wc -l) == "1" ] && [[ "$(git diff --name-only HEAD~1)" == *"md" ]]; then
@@ -72,18 +58,17 @@ install:
7258
# command to run tests
7359
script:
7460
- export MKL_THREADING_LAYER="GNU"
75-
- export KERAS_BACKEND="tensorflow"
76-
# run keras backend init to initialize backend config
77-
- python -c "import keras.backend"
78-
# create models directory to avoid concurrent directory creation at runtime
79-
- mkdir ~/.keras/models
61+
- mkdir -p ~/.keras/models
8062
# set up keras backend
81-
- sed -i -e 's/"backend":[[:space:]]*"[^"]*/"backend":\ "'$KERAS_BACKEND'/g' ~/.keras/keras.json;
82-
- echo -e "Running tests with the following config:\n$(cat ~/.keras/keras.json)"
8363
- if [[ "$DOC_ONLY_CHANGED" == "False" ]]; then
84-
if [[ "$TEST_MODE" == "PEP8" ]]; then
85-
PYTHONPATH=$PWD:$PYTHONPATH py.test --pep8 -m pep8 -n0;
86-
else
8764
PYTHONPATH=$PWD:$PYTHONPATH py.test tests/;
88-
fi;
89-
fi
65+
fi
66+
67+
deploy:
68+
provider: pypi
69+
user: qubvel
70+
password:
71+
secure: QA/UJmkXGlXy/6C8X0E/bPf4izu3rJsztaEmqIM1npxPiv2Uf4WFs43vxkMXwfHrflocdfw8SBM8bWnbunGT2SvDdo/MMCMpol7unE74T/RbODYl6aiJWVM3QKOXL8pQD0oQ+03L1YK3nCeSQdePINEPmuFmvwyO40q8Dwv8HBZIGZlEo4SK4xr8ekxfmtbezxQ7vUL3sNcvCJDXrZX/4UdXrhdRk+zYoN3dv8NmM4FmChajq/m5Am9OPdbdUBHmIYmvk7L3IpwJeMMpG5FVdGNVwYj7XNHlcy+KZ2/CKn9EpslRDPxY4650654PmhSZWDctZG7jiFWLCZBUvowiyAOPZknZNgdu5gJAfdg37XS9IP3HgTZN6Jb5Bm0by3IlKt+dTzyJQcUnRql5B1wwEI0XO3/YWQe1GQQphIO1bli9hT8n8xNDNjc49vDlu4zKyaYnQmLhqNxkyeruXSTpc8qTITuS+EGgkAUrrBj/IaFcutIg9WOzvJ3nZO8X8UG7LlyQx4AOpfHP6bynAmlT+UFccCEq66Zoh7teWLk0lUekuYST2iQJ3pwFoQGYJRCsmxsz7J0B9ayFVVT/fg+GZpZm1oTnnJ27hh8LZWv/Cr/WHOBYc3qvigWx4pDssJ+O6z7de3aWrGvzAVgXr190fRdP55a34HhNbiKZ0YWmrTs=
72+
on:
73+
tags: true
74+
skip_existing: true

README.rst

Lines changed: 91 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,30 @@
1919
`Image
2020
Segmentation <https://en.wikipedia.org/wiki/Image_segmentation>`__ based
2121
on `Keras <https://keras.io>`__
22-
(`Tensorflow <https://www.tensorflow.org/>`__) framework.
22+
and `Tensorflow Keras <https://www.tensorflow.org/>`__ frameworks.
2323

2424
**The main features** of this library are:
2525

26-
- High level API (just two lines to create NN)
27-
- **4** models architectures for binary and multi class segmentation
26+
- High level API (just two lines of code to create model for segmentation)
27+
- **4** models architectures for binary and multi-class image segmentation
2828
(including legendary **Unet**)
2929
- **25** available backbones for each architecture
3030
- All backbones have **pre-trained** weights for faster and better
3131
convergence
32+
- Helpful segmentation losses (Jaccard, Dice, Focal) and metrics (IoU, F-score)
33+
34+
**Important note**
35+
36+
Some models of version ``1.*`` are not compatible with previously trained models,
37+
if you have such models and want to load them - roll back with:
38+
39+
$ pip install -U segmentation-models==0.2.1
3240

3341
Table of Contents
3442
~~~~~~~~~~~~~~~~~
3543
- `Quick start`_
3644
- `Simple training pipeline`_
45+
- `Examples`_
3746
- `Models and Backbones`_
3847
- `Installation`_
3948
- `Documentation`_
@@ -43,36 +52,58 @@ Table of Contents
4352

4453
Quick start
4554
~~~~~~~~~~~
46-
Since the library is built on the Keras framework, created segmentaion model is just a Keras Model, which can be created as easy as:
55+
Library is build to work together with Keras and TensorFlow Keras frameworks
4756

4857
.. code:: python
4958
50-
from segmentation_models import Unet
59+
import segmentation_models as sm
60+
# Segmentation Models: using `keras` framework.
61+
62+
By default it tries to import ``keras``, if it is not installed, it will try to start with ``tensorflow.keras`` framework.
63+
There are several ways to choose framework:
64+
65+
- Provide environment variable ``SM_FRAMEWORK=keras`` / ``SM_FRAMEWORK=tf.keras`` before import ``segmentation_models``
66+
- Change framework ``sm.set_framework('keras')`` / ``sm.set_framework('tf.keras')``
67+
68+
You can also specify what kind of ``image_data_format`` to use, segmentation-models works with both: ``channels_last`` and ``channels_first``.
69+
This can be useful for further model conversion to Nvidia TensorRT format or optimizing model for cpu/gpu computations.
70+
71+
.. code:: python
72+
73+
import keras
74+
# or from tensorflow import keras
75+
76+
keras.backend.set_image_data_format('channels_last')
77+
# or keras.backend.set_image_data_format('channels_first')
78+
79+
Created segmentaion model is just an instance of Keras Model, which can be build as easy as:
80+
81+
.. code:: python
5182
52-
model = Unet()
83+
model = sm.Unet()
5384
5485
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:
5586

5687
.. code:: python
5788
58-
model = Unet('resnet34', encoder_weights='imagenet')
89+
model = sm.Unet('resnet34', encoder_weights='imagenet')
5990
6091
Change number of output classes in the model (choose your case):
6192

6293
.. code:: python
6394
6495
# binary segmentation (this parameters are default when you call Unet('resnet34')
65-
model = Unet('resnet34', classes=1, activation='sigmoid')
96+
model = sm.Unet('resnet34', classes=1, activation='sigmoid')
6697
6798
.. code:: python
6899
69100
# multiclass segmentation with non overlapping class masks (your classes + background)
70-
model = Unet('resnet34', classes=3, activation='softmax')
101+
model = sm.Unet('resnet34', classes=3, activation='softmax')
71102
72103
.. code:: python
73104
74105
# multiclass segmentation with independent overlapping/non-overlapping class masks
75-
model = Unet('resnet34', classes=3, activation='sigmoid')
106+
model = sm.Unet('resnet34', classes=3, activation='sigmoid')
76107
77108
78109
Change input shape of the model:
@@ -88,39 +119,45 @@ Simple training pipeline
88119

89120
.. code:: python
90121
91-
from segmentation_models import Unet
92-
from segmentation_models.backbones import get_preprocessing
93-
from segmentation_models.losses import bce_jaccard_loss
94-
from segmentation_models.metrics import iou_score
95-
96-
BACKBONE = 'resnet34'
97-
preprocess_input = get_preprocessing(BACKBONE)
98-
99-
# load your data
100-
x_train, y_train, x_val, y_val = load_data(...)
101-
102-
# preprocess input
103-
x_train = preprocess_input(x_train)
104-
x_val = preprocess_input(x_val)
105-
106-
# define model
107-
model = Unet(BACKBONE, encoder_weights='imagenet')
108-
model.compile('Adam', loss=bce_jaccard_loss, metrics=[iou_score])
109-
110-
# fit model
111-
# if you use data generator use model.fit_generator(...) instead of model.fit(...)
112-
# more about `fit_generator` here: https://keras.io/models/sequential/#fit_generator
113-
model.fit(
114-
x=x_train,
115-
y=y_train,
116-
batch_size=16,
122+
import segmentation_models as sm
123+
124+
BACKBONE = 'resnet34'
125+
preprocess_input = sm.get_preprocessing(BACKBONE)
126+
127+
# load your data
128+
x_train, y_train, x_val, y_val = load_data(...)
129+
130+
# preprocess input
131+
x_train = preprocess_input(x_train)
132+
x_val = preprocess_input(x_val)
133+
134+
# define model
135+
model = sm.Unet(BACKBONE, encoder_weights='imagenet')
136+
model.compile(
137+
'Adam',
138+
loss=sm.losses.bce_jaccard_loss,
139+
metrics=[sm.metrics.iou_score],
140+
)
141+
142+
# fit model
143+
# if you use data generator use model.fit_generator(...) instead of model.fit(...)
144+
# more about `fit_generator` here: https://keras.io/models/sequential/#fit_generator
145+
model.fit(
146+
x=x_train,
147+
y=y_train,
148+
batch_size=16,
117149
epochs=100,
118150
validation_data=(x_val, y_val),
119-
)
120-
151+
)
121152
122153
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/>`__.
123154

155+
Examples
156+
~~~~~~~~
157+
Models training examples:
158+
- [Jupyter Notebook] Binary segmentation (`cars`) on CamVid dataset `here <https://github.com/qubvel/segmentation_models/blob/master/examples/binary%20segmentation%20(camvid).ipynb>`__.
159+
- [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>`__.
160+
124161
Models and Backbones
125162
~~~~~~~~~~~~~~~~~~~~
126163
**Models**
@@ -135,6 +172,7 @@ Unet Linknet
135172
============= ==============
136173
|unet_image| |linknet_image|
137174
============= ==============
175+
138176
============= ==============
139177
PSPNet FPN
140178
============= ==============
@@ -167,7 +205,7 @@ PSPNet FPN
167205
DenseNet ``'densenet121' 'densenet169' 'densenet201'``
168206
Inception ``'inceptionv3' 'inceptionresnetv2'``
169207
MobileNet ``'mobilenet' 'mobilenetv2'``
170-
EfficientNet ``'efficientnetb0' 'efficientnetb1' 'efficientnetb2' 'efficientnetb3'``
208+
EfficientNet ``'efficientnetb0' 'efficientnetb1' 'efficientnetb2' 'efficientnetb3' 'efficientnetb4' 'efficientnetb5' efficientnetb6' efficientnetb7'``
171209
============= =====
172210

173211
.. epigraph::
@@ -179,19 +217,25 @@ Installation
179217

180218
**Requirements**
181219

182-
1) Python 3.5+
183-
2) Keras >= 2.2.0
184-
3) Keras Application >= 1.0.7
185-
4) Image Classifiers == 0.2.0
186-
5) Tensorflow 1.9 (tested)
220+
1) python 3
221+
2) keras >= 2.2.0 or tensorflow >= 1.13
222+
3) keras-applications >= 1.0.7, <=1.0.8
223+
4) image-classifiers == 1.0.*
224+
5) efficientnet == 1.0.*
225+
226+
**PyPI stable package**
227+
228+
.. code:: bash
229+
230+
$ pip install -U segmentation-models
187231
188-
**Pip package**
232+
**PyPI latest package**
189233

190234
.. code:: bash
191235
192-
$ pip install segmentation-models
236+
$ pip install -U --pre segmentation-models
193237
194-
**Latest version**
238+
**Source latest version**
195239

196240
.. code:: bash
197241

docs/api.rst

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,18 @@ PSPNet
2222

2323
metrics
2424
~~~~~~~
25-
.. autofunction:: segmentation_models.metrics.iou_score
26-
.. autofunction:: segmentation_models.metrics.f_score
25+
.. autofunction:: segmentation_models.metrics.IOUScore
26+
.. autofunction:: segmentation_models.metrics.FScore
2727

2828
losses
2929
~~~~~~
30-
.. autofunction:: segmentation_models.losses.jaccard_loss
31-
.. autofunction:: segmentation_models.losses.dice_loss
32-
30+
.. autofunction:: segmentation_models.losses.JaccardLoss
31+
.. autofunction:: segmentation_models.losses.DiceLoss
32+
.. autofunction:: segmentation_models.losses.BinaryCELoss
33+
.. autofunction:: segmentation_models.losses.CategoricalCELoss
34+
.. autofunction:: segmentation_models.losses.BinaryFocalLoss
35+
.. autofunction:: segmentation_models.losses.CategoricalFocalLoss
3336

3437
utils
3538
~~~~~
36-
.. autofunction:: segmentation_models.backbones.get_preprocessing
3739
.. autofunction:: segmentation_models.utils.set_trainable

docs/conf.py

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -184,4 +184,11 @@
184184

185185
# -- Extension configuration -------------------------------------------------
186186

187-
autodoc_mock_imports = ['skimage', 'tensorflow']
187+
autodoc_mock_imports = [
188+
'skimage',
189+
'keras',
190+
'tensorflow',
191+
'efficientnet',
192+
'classification_models',
193+
'keras_applications',
194+
]

docs/install.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@ Installation
33

44
**Requirements**
55

6-
1) Python 3.5+
7-
2) Keras >= 2.2.0
8-
3) Keras Applications >= 1.7.0
9-
4) Image Classifiers == 0.2.0
10-
5) Tensorflow 1.9 (tested)
6+
1) Python 3
7+
2) Keras >= 2.2.0 or TensorFlow >= 1.13
8+
3) keras-applications >= 1.0.7, <=1.0.8
9+
4) image-classifiers == 1.0.0
10+
5) efficientnet == 1.0.0
1111

1212

1313
.. note::

0 commit comments

Comments
 (0)