Skip to content
This repository has been archived by the owner on Jun 14, 2023. It is now read-only.

Commit

Permalink
further improve toy example description
Browse files Browse the repository at this point in the history
  • Loading branch information
valentin.kozlov committed Jan 15, 2019
1 parent 8bdc72b commit b8bcc7f
Showing 1 changed file with 92 additions and 36 deletions.
128 changes: 92 additions & 36 deletions source/user/models/toy_model-dog_breeds.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,23 @@ Toy example: dog's breed detection
==================================
A toy example to identify Dog's breed, "Dogs breed detector" [*]_, images for training come from `dog dataset <https://s3-us-west-1.amazonaws.com/udacity-aind/dog-project/dogImages.zip>`_.

+----------------------------+---------------------------+
| Neural Network type | CNN |
+----------------------------+---------------------------+
| Deep Learning Framework(s) | Tensorflow, Keras |
+----------------------------+---------------------------+
| Programming language | Python |
+----------------------------+---------------------------+
| GPU version | yes |
+----------------------------+---------------------------+
| CPU version | yes |
+----------------------------+---------------------------+
| DEEPaaS API | yes |
+----------------------------+---------------------------+
| DEEP UC template | yes |
+----------------------------+---------------------------+
| DEEP Nextcloud access | yes |
+----------------------------+---------------------------+
+-----------------------------------------------------------------+---------------------+
| Neural Network type | CNN |
+-----------------------------------------------------------------+---------------------+
| Deep Learning Framework(s) | Tensorflow, Keras |
+-----------------------------------------------------------------+---------------------+
| Programming language | Python |
+-----------------------------------------------------------------+---------------------+
| GPU version | yes |
+-----------------------------------------------------------------+---------------------+
| CPU version | yes |
+-----------------------------------------------------------------+---------------------+
| `DEEPaaS API <https://deepaas.readthedocs.io/en/stable/>`_ | yes |
+-----------------------------------------------------------------+---------------------+
| :doc:`DEEP UC template <../overview/cookiecutter-template>` | yes |
+-----------------------------------------------------------------+---------------------+
| `DEEP-Nextcloud <https://nc.deep-hybrid-datacloud.eu/>`_ access | yes |
+-----------------------------------------------------------------+---------------------+


Keywords: image classification, CNN, transfer learning, Tensorflow
Expand All @@ -30,11 +30,12 @@ App source code: https://github.com/indigo-dc/dogs_breed_det
Pre-trained weights: https://nc.deep-hybrid-datacloud.eu/s/D7DLWcDsRoQmRMN



Description
-----------

The project applies `Transfer learning <https://en.wikipedia.org/wiki/Transfer_learning>`_ for dog's breed identification, implemented with Tensorflow and Keras:
From a pre-trained model (VGG16 | VGG19 | Resnet50 | InceptionV3 | Xception) the last layer is removed,
From a pre-trained model (VGG16 | VGG19 | Resnet50 | InceptionV3) the last layer is removed,
then a new Fully Connected (FC) classification layer is added, which is trained.
All images first pass through the pre-trained network and converted into the tensor with the shape of the 'before-last' layer of the pre-trained network,
into so-called 'bottleneck_features'. These bottleneck_features are used then as input for the FC classification network.
Expand All @@ -47,7 +48,8 @@ The described workflow supposes usage of downloaded from DEEP Open Catalogue Doc

**1. Workflow intro**

1) DEEPaaS API uses port 5000 for access, one therefore has to map the container and host ports, see Examples below.
1) `DEEPaaS API <https://deepaas.readthedocs.io/en/stable/>`_ uses port 5000 for access, one therefore has to map the container and host ports,
see Examples below.

2) Following two directories inside the docker container are used for input and output:

Expand All @@ -61,8 +63,8 @@ The described workflow supposes usage of downloaded from DEEP Open Catalogue Doc

If you want to perform full training, then you need to mount your data into ``/srv/dogs_breed_det/data``.

If you want only to classify images or want to keep trained weights in the persistant place, then you have to mount ``/srv/dogs_breed_det/models``
to a persistent volume. You can use either your local directories or connect your remote storage, see Examples below.
If you want to keep trained weights in the persistant place, then you have to mount ``/srv/dogs_breed_det/models``
to a persistent volume. You can either use your local directories or connect your remote storage, see Examples below.

**2. Data input**

Expand Down Expand Up @@ -92,11 +94,72 @@ Trainig labels are also created automatically based on the directory names, trun

If you want to use your own dataset then it has to follow similar structure.

**Suggested local directory structure:**
::
data/
dogImages/
raw/
models/

+------------------------+------------------------------------------+
| **Local dir to mount** | **Corresponding place in the container** |
+------------------------+------------------------------------------+
| ``LOCAL_DIR/data`` | ``/srv/dogs_breed_det/data`` |
+------------------------+------------------------------------------+
| ``LOCAL_DIR/models`` | ``/srv/dogs_breed_det/models`` |
+------------------------+------------------------------------------+

In this case, you place `dogImages.zip <https://s3-us-west-1.amazonaws.com/udacity-aind/dog-project/dogImages.zip>`_ in ``LOCAL_DIR/data/raw``,
which makes it available in ``/srv/dogs_breed_det/data/raw``.

**Necessary remote structure:**
::
/Datasets/dogs_breed/data
/Datasets/dogs_breed/data/dogImages
/Datasets/dogs_breed/data/raw
/Datasets/dogs_breed/models

In this case, you place `dogImages.zip <https://s3-us-west-1.amazonaws.com/udacity-aind/dog-project/dogImages.zip>`_ in ``/Datasets/dogs_breed/data/raw``,
which makes it available in ``/srv/dogs_breed_det/data/raw``.


**3. Accessing application**

* In a minimum case to classify images with already trained Resnet50 model, start the container as::

docker run -ti -p 5000:5000 deephdc/deep-oc-dogs_breed_det:cpu deepaas-run --listen-ip=0.0.0.0
* In more advanced cases (see Examples below) you may need to mount various directories or pass environment settings.

* Direct your web browser to http://127.0.0.1:5000

**3. Train the classifier**

**4. Test the classifier**

* Go to **/models/{model_name}/predict** , click "**Try it out**" button

* Choose an image file for dog's breed identification (N.B. "URL to retrieve data" is not (yet) implemented)

* Type **model_name**, one of the ``Dogs_Resnet50``, ``Dogs_InceptionV3``, ``Dogs_VGG16``, ``Dogs_VGG19``

* The equivalent API call is::

curl -X POST "http://127.0.0.1:5000/models/Dogs_Resnet50/predict" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "data=@YourDogImage.jpg;type=image/jpeg"

.. note:: By default only weigths for Dogs_Resnet50 are available (automatically downloaded from the shared link, see above "Pre-trained weights" URL), all other models have to be trained first!


**5. Train the classifier**

* Connect your data storage with the corresponding directory inside the container (see "Data input" above and Examples below)
* Go to **/models/{model_name}/train** , click "**Try it out**" button
* Type **model_name**, one of the ``Dogs_Resnet50``, ``Dogs_InceptionV3``, ``Dogs_VGG16``, ``Dogs_VGG19``
* Execute training
* The equivalent API call is::

curl -X PUT "http://127.0.0.1:5000/models/Dogs_Resnet50/train" -H "accept: application/json"


DEEP Pilot infrastructure submission
------------------------------------
Expand All @@ -122,30 +185,23 @@ Example 2 (CPU):
deephdc/deep-oc-dogs_breed_det:cpu deepaas-run --listen-ip=0.0.0.0


**2. Connect to remote storage by using rclone.conf from your host**
**2. Connect to a remote storage by using** ``rclone.conf`` **from your host**

`rclone <https://rclone.org/>`_ tool allows to connect to a plenty of remote storages.
The tool is already installed in the Docker image and expects your ``data/`` and ``models/`` sub-directories to be under ``deepnc:/Datasets/dogs_breed/``.
If no data found in your container, rclone attempts to connect to ``deepnc:/`` and download necessary data from there.

If you are familiar with the `rclone <https://rclone.org/>`_ tool, you probably have ``rclone.conf`` file on your host.
You can rename one of the pre-configured remote storages to ``deepnc`` and mount the host directory with the ``rclone.conf`` file into the container:
You can rename one of the pre-configured remote storages to ``deepnc``, then mount host directory with your ``rclone.conf`` file into the container:

Example 3:
Example 3: using in the container ``rclone.conf`` from your host
::

docker run -ti -p 5000:5000 -v $HOSTDIR_WITH_RCLONE_CONF:/srv/rclone \
-e RCLONE_CONFIG=/srv/rclone/rclone.conf \
deephdc/deep-oc-dogs_breed_det:cpu deepaas-run --listen-ip=0.0.0.0

On your remote storage create following directories:

* ``/Datasets/dogs_breed/data``
* ``/Datasets/dogs_breed/data/raw``
* ``/Datasets/dogs_breed/models``


put `dogImages.zip <https://s3-us-west-1.amazonaws.com/udacity-aind/dog-project/dogImages.zip>`_ file in ``/Datasets/dogs_breed/data/raw``
`dogImages.zip <https://s3-us-west-1.amazonaws.com/udacity-aind/dog-project/dogImages.zip>`_ file is expected to be in ``/Datasets/dogs_breed/data/raw``

Example 4: ``rclone.conf`` with `DEEP-Nextcloud <https://nc.deep-hybrid-datacloud.eu/>`_ configured as ``deepnc`` remote storage:
::
Expand All @@ -165,14 +221,14 @@ Example 5: ``rclone.conf`` with Google Drive configured as ``deepnc`` remote sto
token = {"access_token":"ya29.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","token_type":"Bearer","refresh_token":"1/-XXXXXXXXXXXXXXXXXXXX","expiry":"2019-01-14T20:26:13.21767343Z"}


Check `rclone <https://rclone.org/>`_ documentation on how to configure different types of remote storage.
.. note:: Check `rclone <https://rclone.org/>`_ documentation on how to configure different types of remote storage.

**3. Connect to remote storage by passing rclone configuration parameters as environment settings**
**3. Connect to a remote storage by passing rclone configuration parameters as environment settings**

It is also possible to pass necessary configuration as environment settings during instantiation of the container,
best is to create a runnable bash script:

Example 6: Connecting `DEEP-Nextcloud <https://nc.deep-hybrid-datacloud.eu/>`_ remote storage
Example 6: connecting `DEEP-Nextcloud <https://nc.deep-hybrid-datacloud.eu/>`_ remote storage

.. code-block:: bash
Expand Down

0 comments on commit b8bcc7f

Please sign in to comment.