Resolve "Update docs according to Project Review"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 EPAM Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,45 +1,171 @@
-<div align="center"><img src="https://es.wiki.elvenar.com/images/0/04/Glossy_Garden.png" width="50%"/></div>
+![Model Prototyping Sequence Diagram](docs/images/screen_model_garden_gallery.png)
 
-<div align="center"><h2>🏷️ Model Garden</h2></div>
+<div align="center"><h2>Model Garden</h2></div>
 
+## Goals and Prerequisites
 
-**‍🖌️ Material Design**: **Intuitive** UI based on the world's most widespread design language.
+**Project Goal**: Provide convenient tool for management of
+ [Computer Vision](www.wikipedia.org/wiki/Computer_vision)
+ [datasets](www.wikipedia.org/wiki/Data_set) within projects providing numerous
+ experiments with visual images.
 
-**🏃 Single Page Application**: Fast, responsive ux to get what you need done without waiting for fullscreen refreshes.
+**Solved Problem**: [Computer Vision](www.wikipedia.org/wiki/Computer_vision)
+ projects providing numerous experiments with the image data usually needs
+ collaborative sharing of these data and supporting wide range of
+ [datasets](www.wikipedia.org/wiki/Data_set) formats.
+
+Among popular image dataset annotation tools
+ <a href="www.github.com/opencv/cvat">github.com/opencv/cvat</a> has so far a
+ largest number of supported formats ([Pascal VOC](host.robots.ox.ac.uk/pascal/VOC),
+ YOLO, [COCO](www.cocodataset.org), etc., see the table
+ [below](#existing-solutions)).
+
+<a href="www.github.com/opencv/cvat">Computer Vision Annotation Tool (CVAT)/a>
+ open-sourced by <a href="Intel.com">Intel</a> just lucking the support of such
+ clouds like [AWS](www.aws.amazon.com). CVAT team has shared a
+ <a href="www.github.com/opencv/cvat/issues/863">post</a> saying that the AWS
+ "issue in backlog at the moment till we have resources to cover it".
+
+The Model Garden tool is an addition to CVAT providing the following functionality:
+ * store in [S3](www.wikipedia.org/wiki/Amazon_S3), reuse and modify image
+  datasets using CVAT tool
+ * collaborative usage of datasets through web interface
+ * prevent labeling tool crash consequences
+
+### Top Existing Solutions
+
+<table style="width:100%">
+  <tr>
+    <th style="text-align:center">Usage Order</th>
+    <th style="text-align:center">Tool</th>
+    <th style="text-align:center">Publisher</th>
+    <th style="text-align:center">Web</th>
+    <th style="text-align:center">Cloud</th>
+    <th style="text-align:center">Pascal VOC</th>
+    <th style="text-align:center">YOLO</th>
+    <th style="text-align:center">COCO</th>
+    <th style="text-align:center">MASK</th>
+    <th style="text-align:center">TFRecord</th>
+    <th style="text-align:center">MOT</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td><a href="www.github.com/tzutalin/labelImg">ithub.com/tzutalin/labelImg</a></td>
+    <td><a href="tzutalin.github.io"><i>private</i></a></td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">Y</td>
+    <td style="text-align:center">Y</td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">N</td>
+  </tr>
+  <tr>
+    <td>2</td>
+    <td><a href="www.github.com/opencv/cvat">github.com/opencv/cvat</a></td>
+    <td><a href="Intel.com">Intel</a></td>
+    <td style="text-align:center"><b>Y</b></td>
+    <td style="text-align:center"><a href="www.github.com/opencv/cvat/issues/863">N</a></td>
+    <td style="text-align:center"><b>Y</b></td>
+    <td style="text-align:center"><b>Y</b></td>
+    <td style="text-align:center"><b>Y</b></td>
+    <td style="text-align:center"><b>Y</b></td>
+    <td style="text-align:center"><b>Y</b></td>
+    <td style="text-align:center"><b>Y</b></td>
+  </tr>
+  <tr>
+    <td>3</td>
+    <td><a href="www.github.com/microsoft/VoTT">github.com/microsoft/VoTT</a></td>
+    <td><a href="Microsoft.com">Microsoft</a></td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">Y</td>
+    <td style="text-align:center">Y</td>
+    <td style="text-align:center"><a href="www.github.com/microsoft/VoTT/issues/803">N</a></td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">N</td>
+    <td style="text-align:center">N</td>
+  </tr>
+</table>
+
+## Project Support
+
+Model Garden was started as [EPAM Systems](www.epam.com) internal initiative to
+support EPAM Computer Vision teams (e.g. 
+[Vudoku Accelerator](www.epam.com/careers/blog/vudoku-smart-tv-an-innovative-solution-for-video-content-rotation)). 
+
+The project is open sourced with the support of [epam.github.io](epam.github.io).
+
+## Technical Features
+
+**‍🖌️ Material Design**: **Intuitive** UI based on the world's most widespread
+design language.
+
+**🏃 Single Page Application**: Fast, responsive ux to get what you need done
+without waiting for full-screen refreshes.
 
 **🐍 Python Django and Postgres**
 
-## Installation
+**🏷 AWS S3 DataSet Gallery**
+![Model Garden DataSet Galery](docs/images/screen_model_garden_dataset.png)
+![Model Garden DataSet Saved in S3](docs/images/screen_model_garden_dataset_s3.png)
 
-- [CVAT Installation Guide](cvat/README.md)
-- [Installation guide for Backend developer](backend/README.md)
-- [Installation guide for Frontend developer](frontend/README.md)
+## Use Cases
+
+### Model Prototyping
 
-## Run Application with Docker Compose
-```
-$ docker-compose up -d
+Model Garden supports case when with only one data scientist works on the
+ project (does labeling and ML training). This can be useful for experimental
+ projects.
 
-Creating network "model_garden_default" with the default driver
-...
-Creating model_garden_postgres_1 ... done
-Creating model_garden_backend_1  ... done
-Creating model_garden_frontend_1 ... done
-```
+![Model Prototyping Sequence Diagram](docs/images/use_case_model_prototyping.png)
+
+### Collaborative DataSet Labeling
+
+Model Garden supports the case of Massive parallel labeling when a manager has a
+ lot of images and a list of labels. In this case, the manager can upload
+ DataSet, create a list of labels, and assign certain DataSet parts to different
+ labelers, and next control their work.
+
+![Model Prototyping Sequence Diagram](docs/images/use_case_collaborative_dataset_labeling.png)
+
+## DataFlow
+
+Material Garden is a mediator between CVat (one of the most popular open-source
+ annotation tool for computer vision) and Amazon S3 (object storage service).
+
+Status Worker is part of Material Garden. This worker checks event updates from
+ CVAT asynchronously.
+
+![Model Prototyping Sequence Diagram](docs/images/architecture/architecture_model_garden_dataflow.png)
+
+## CI/CD
+
+The example of [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment)
+ to the cloud container registry as well as the cloud update is set with help of
+ [GitLab CI/CD](docs.gitlab.com/ee/ci/) [.gitlab-ci.yml](.gitlab-ci.yml) file.
+
+
+## Installation
+
+### Installation Specifications
+- [CVAT Installation Guide](cvat/README.md)
+- See installation steps for backend developers in
+ [<model_garden_root>/backend/README.md](backend/README.md)
+- See installation steps for frontend developers in
+ [<model_garden_root>/frontend/README.md](frontend/README.md)
 
-### Check Running Docker Containers
-```
-$ docker-compose ps
+### Deployment
 
-         Name                        Command               State           Ports         
------------------------------------------------------------------------------------------
-model_garden_backend_1    bash -c ./manage.py migrat ...   Up      0.0.0.0:9000->9000/tcp
-model_garden_frontend_1   /bin/sh -c nginx -g 'daemo ...   Up      0.0.0.0:80->80/tcp    
-model_garden_postgres_1   docker-entrypoint.sh postgres    Up      0.0.0.0:5444->5432/tcp
-```
+See all the details in the [<model_garden_root>/deploy/README.md](deploy/README.md).
 
-## Deployment
+If [CI/CD](https://en.wikipedia.org/wiki/CI/CD) is set via
+ [.gitlab-ci.yml](.gitlab-ci.yml) the build pipeline is started automatically
+ after commits to **master** and **develop** branches
 
 
-- [Deployment guide](deploy/README.md)
+### Contacts
 
-  The build pipeline is started automatically after commits to **master** and **develop** branches
+* <a href="mailto:[email protected]">Model Garden Initiative DL</a>
+* <a href="mailto:[email protected]">EPAM Open Source Community</a> 

backend/README.md

@@ -3,8 +3,28 @@
 ## Database (not recommended - use docker)
 www.postgresql.org/download (the current ver. 12.3)
 
-See the recommended password in
-[EPAM Model Garden - PostgresSQL](https://kb.epam.com/display/EPMEMRDMGA/EPAM+Model+Garden+-+PostgresSQL).
+<table style="width:100%">
+  <tr>
+    <th style="text-align:center">Name</th>
+    <th style="text-align:center">Value</th>
+  </tr>
+  <tr>
+    <td>Host name/Address</td>
+    <td>model-garden-db-prod-1.<id>.eu-central-1.rds.amazonaws.com</td>
+  </tr>
+  <tr>
+    <td>Username</td>
+    <td>postgres</td>
+  </tr>
+  <tr>
+    <td>Password</td>
+    <td>******</td>
+  </tr>
+  <tr>
+    <td>Port</td>
+    <td>5432</td>
+  </tr>
+</table>
 
 Also update the password in `DATABASES = {...}` dict in settings.py
 
@@ -17,8 +37,22 @@ See in [<model_garden_root>/backend/.env](.env) file.
 Follow all the steps in [CVAT Installation Guide](../cvat/README.md).
 
 ### Add Backend .env File
-Create [<model_garden_root>/backend/.env](.env). Ask colleagues to share this
-file content.
+Create [<model_garden_root>/backend/.env](.env).
+
+```
+AWS_ACCESS_KEY_ID='<ABCDEFGHIJKLMNOPQRST>*'
+AWS_SECRET_KEY='<abcdefghijklmnopqrstuvwxyz0123456789-+/>*'
+
+CVAT_HOST='localhost'
+CVAT_PORT=8080
+CVAT_ROOT_USER_NAME='<cvat_super_user>*'
+CVAT_ROOT_USER_PASSWORD='<cvat_super_user_password>*'
+
+DJANGO_DB_HOST='localhost'
+DJANGO_DB_PORT=5444
+```
+
+<sup>* - environment specific values</sup>
 
 ### Make sure you have Python 3.8 installed
 ```

cvat/README.md

@@ -1,15 +1,15 @@
-# EPAM github.com/opencv/cvat Fork
+# Computer Vision Annotation Tool (CVAT)
 
-## EPAM Repo
+## Source Code
 
-https://git.epam.com/epmc-mlcv/cvat
+* [Official CVAT Repo](github.com/opencv/cvat)
 
 ## Installation
 
 ### Install CVAT Locally
 #### Build Docker
-See instructions in 
-https://git.epam.com/epmc-mlcv/cvat/-/blob/master/cvat/apps/documentation/installation.md#windows-10
+See instructions in [Windows 10 CVAT Installation](github.com/opencv/cvat/blob/develop/cvat/apps/documentation/installation.md#windows-10)
+ or in [its internal fork](git.epam.com/epm-emrd/cvat/-/blob/master/cvat/apps/documentation/installation.md#windows-10).
 
 Remember the superuser name and admin to access CVAT admin console.