documentation (go to RST), prune deprecation 16/2216/3
authorEric Z <ezavesky@research.att.com>
Thu, 5 Jul 2018 17:25:01 +0000 (12:25 -0500)
committerEric Z <ezavesky@research.att.com>
Thu, 5 Jul 2018 17:25:01 +0000 (12:25 -0500)
- update documents for .rst format
- prune deprecated swagger/app demo script for model runner
- add unique reference names for RST generation

Issue-ID: ACUMOS-999, ACUMOS-97

Change-Id: I8deed4beef178e8728858a5af8ab3b6603ef88b2
Signed-off-by: Eric Z <ezavesky@research.att.com>
16 files changed:
README.rst [moved from README.md with 66% similarity]
docs/face-privacy-filter.md [deleted file]
docs/face-privacy-filter.rst [new file with mode: 0644]
docs/index.rst
docs/release-notes.md [deleted file]
docs/release-notes.rst [new file with mode: 0644]
docs/tutorials/demonstration.rst [new file with mode: 0644]
docs/tutorials/deployment.rst [new file with mode: 0644]
docs/tutorials/index.rst
docs/tutorials/lesson1.md [deleted file]
docs/tutorials/lesson2.md [deleted file]
docs/tutorials/lesson3.md [deleted file]
face_privacy_filter/_version.py
testing/README.rst [moved from testing/README.md with 78% similarity]
testing/app.py [deleted file]
testing/swagger.yaml [deleted file]

similarity index 66%
rename from README.md
rename to README.rst
index 13b822a..1ae789f 100644 (file)
--- a/README.md
@@ -1,4 +1,3 @@
-<!---
 .. ===============LICENSE_START=======================================================
 .. Acumos CC-BY-4.0
 .. ===================================================================================
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 .. ===============LICENSE_END=========================================================
--->
 
-# face-privacy-filter
+|Build Status|
+
+face-privacy-filter
+===================
+
 A model for face detection and suppression.
 
-* [Overall Documentation](docs/face-privacy-filter.md)
-* [Release Notes](docs/release-notes.md)
-* Tutorials
-    * [Deployment and Running](docs/tutorials/lesson1.md),
-    * [Swagger API server](docs/tutorials/lesson2.md), and
-    * [Web Application](docs/tutorials/lesson3.md)
+-  `Overall Documentation <docs/face-privacy-filter.rst>`__
+-  `Release Notes <docs/release-notes.rst>`__
+-  `Tutorials <docs/tutorials/index.rst>`__
+
+   -  `Deployment and Running <docs/tutorials/deployment.rst>`__,
+   -  `Web Application <docs/tutorials/demonstration.rst>`__
+
 
+.. |Build Status| image:: https://jenkins.acumos.org/buildStatus/icon?job=face-privacy-filter-tox-verify-master
+   :target: https://jenkins.acumos.org/job/face-privacy-filter-tox-verify-master/
 
diff --git a/docs/face-privacy-filter.md b/docs/face-privacy-filter.md
deleted file mode 100644 (file)
index 8cc661f..0000000
+++ /dev/null
@@ -1,204 +0,0 @@
-<!---
-.. ===============LICENSE_START=======================================================
-.. Acumos CC-BY-4.0
-.. ===================================================================================
-.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-.. ===================================================================================
-.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
-.. under the Creative Commons Attribution 4.0 International License (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-..      http://creativecommons.org/licenses/by/4.0
-..
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
--->
-
-# Face Privacy Filter Guide
-This model contains the capability to generate two submodels:
-one for face detection and oen for face suppression through pixelation.
-
-# Face Detection Model Guide
-A model example for face detection from images within Acumos.
-
-## Background
-This model analyzes static images to detect frontal faces.  It utilizes a
-frontal face cascade from the
-[OpenCV](https://opencv.org/) image processing library.
-Model load time is optimized by creating and maintaining the fixed cascade
-in memory while operating.  Demonstrating the capability of custom classes
-and requisite member variables, the cascade is serialized with the model as
-a string asset which is deserialized and loaded from disk upon startup.
-
-## Usage
-Input to the model is an array of one or more tuples of image binary data
-and a binary mime type.  The position of the image within the array is utilized
-in the output signature as a zero-based index.  For example if three images
-were sent, the output probabilities would have 0, 1, and 2 as index values.
-The output from this model is a repeated array of detected regions for each
-face in each input image.  So that image data can be cascaded to other models,
-the original image and mime type are also embedded with the special
-region code `-1` within the output.
-
-A web demo is included with the source code, available via the
-[Acumos Gerrit repository](https://gerrit.acumos.org/r/gitweb?p=face-privacy-filter.git;a=summary)
-or the mirrored [Acumos Github repository](https://github.com/acumos/face-privacy-filter).
-It utilizes a protobuf javascript library and processes
-input images to detect all faces within an image.
-
-Once deployed, you can quickly jump to the
-[default webhost page](http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html)
-and point to your model for a demo; see [tutorial lesson 3](tutorials/lesson3.md) for more details.
-
-## Performance
-As this model wraps a preexisting cascade, no formal testing evaluation
-was performed.  However, experimental usage indicates the following highlights.
-
-* Faces that are too small can easily be missed.
-* Frontal faces perform best, with some tolerance of about 5-10 degrees off-plane rotation.
-* Detection is fairly sensitive to rotation in plane, so try not to let subject faces rotate more than 15 degrees.
-* Dark or low contrast images generally do not perform well for detection.
-
-## More Information
-As this model uses a generic cascade from OpenCV, readers can easily
-substituted or update those models with no change in API endpoint required.
-Additionally, secondary verification methods using pixel validation (e.g.
-sub-part verification, symmetry tests, or more advanced parts-based
-verifications) may dramatically improve the false alarm rate, although
-the current model was tuned for precision (instead of recall) already.
-
-
-
-# Face Pixelation Model Guide
-A model example to anonymize faces from images via pixelation within Acumos.
-
-## Background
-This model accepts detected faces and their source image and produces
-pixelated image results.  It utilizes simple image manipulation methods
-from the [OpenCV](https://opencv.org/) image processing library.
-This model is a demonstration of a
-transform operation: there is neither state nor static model data
-utilized and all data comes from the upstream input.
-
-
-## Usage
-Input to the model is an array of one or more tuples of detected face regions
-as well as the original image binary data and a binary mime type.  The row or
-sample containing the original image is specially marked by a region code
-of ‘-1’.  The output from this model is an array of images (one for each
-unique image input) with the detected face regions blurred via pixelation.
-
-A web demo is included with the source code, available via the
-[Acumos Gerrit repository](https://gerrit.acumos.org/r/gitweb?p=face-privacy-filter.git;a=summary).
-It utilizes a protobuf javascript library and processes
-input images to detect all faces within an image.
-
-## Performance
-As this model is a data transform example that flattens detected image regions into images.
-
-* Faces not included in the detected regions are ignored.
-* Faces whose images do not exist in the input (e.g. region and image indices
-  are provided, but no original image) are ignored.
-* The mime type for the output image is constructed to mimic the input image and mime type.
-
-## More Information
-This model uses processing methods from OpenCV, so any number of additional
-privacy methods could be employed, like blurring, substitution, etc. More
-advanced techniques that still allow some information processing (e.g.
-demographics but not recognition) may also be easily employed with this
-system, should the right method arise.
-
-
-# Source Installation
-This section is useful for source-based installations and is not generally intended
-for catalog documentation.
-
-## Image Analysis for Face-based Privacy Filtering
-This source code creates and pushes a model into Acumos that processes
-incoming images and outputs a detected faces as well as the original image
-input (if configured that way).  The model uses a [python interface](https://pypi.python.org/pypi/opencv-python)
-to the [OpenCV library](https://opencv.org/) to detect faces and perform
-subsequent image processing.  This module does not support training
-at this time and instead uses a pre-trained face cascade, which is
-included (from OpenCV) in this module.
-
-## Package dependencies
-Package dependencies for the core code and testing have been flattened into a
-single file for convenience. Instead of installing this package into your
-your local environment, execute the command below.
-
-**Note:** If you are using an [anaconda-based environment](https://anaconda.org),
-you may want to try installing with conda first and then pip.
-to mixing mixing package stores.
-```
-conda install --yes --file requirements.txt  # suggested first step if you're using conda
-```
-
-Installation of the package requirements for a new environment.
-```
-pip install -r requirements.txt
-```
-
-
-### Usage
-This package contains runable scripts for command-line evaluation,
-packaging of a model (both dump and posting), and simple web-test
-uses.   All functionality is encapsulsted in the `filter_image.py`
-script and has the following arguments.
-
-```
-usage: filter_image.py [-h] [-p PREDICT_PATH] [-i INPUT] [-c]
-                       [-f {detect,pixelate}] [-s] [-a PUSH_ADDRESS]
-                       [-A AUTH_ADDRESS] [-d DUMP_MODEL]
-
-optional arguments:
-  -h, --help            show this help message and exit
-
-main execution and evaluation functionality:
-  -p PREDICT_PATH, --predict_path PREDICT_PATH
-                        save detections from model (model must be provided via
-                        'dump_model')
-  -i INPUT, --input INPUT
-                        absolute path to input data (image or csv, only during
-                        prediction / dump)
-  -c, --csv_input       input as CSV format not an image
-  -f {detect,pixelate}, --function {detect,pixelate}
-                        which type of model to generate
-  -s, --suppress_image  do not create an extra row for a returned image
-
-model creation and configuration options:
-  -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
-                        server address to push the model (e.g.
-                        http://localhost:8887/v2/models)
-  -A AUTH_ADDRESS, --auth_address AUTH_ADDRESS
-                        server address for login and push of the model (e.g.
-                        http://localhost:8887/v2/auth)
-  -d DUMP_MODEL, --dump_model DUMP_MODEL
-                        dump model to a pickle directory for local running
-```
-
-
-
-# Example Usages
-Please consult the [tutorials](tutorials) dirctory for usage examples
-including an in-place [web page demonstration](tutorials/lesson3.md).
-
-## Face-based Use Cases
-This project includes a number of face-based use cases including raw
-detection, blurring, and other image-based modifications based on
-detected image regions.
-
-* **Face Detection Use-case** - This source code creates and pushes a model that processes
-incoming images and outputs detected faces.
-
-# Release Notes
-The [release notes](release-notes.md) catalog additions and modifications
-over various version changes.
-
-# Metadata Examples
-* [example detect catalog image](catalog_image_detect.png) - [url source](https://flic.kr/p/xqw25C)
-* [example blur catalog image](catalog_image_blur.png)  - [url source](https://flic.kr/p/bEgYbs)
diff --git a/docs/face-privacy-filter.rst b/docs/face-privacy-filter.rst
new file mode 100644 (file)
index 0000000..cd49b1f
--- /dev/null
@@ -0,0 +1,202 @@
+.. ===============LICENSE_START=======================================================
+.. Acumos CC-BY-4.0
+.. ===================================================================================
+.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
+.. ===================================================================================
+.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
+.. under the Creative Commons Attribution 4.0 International License (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..      http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+.. _face_privacy:
+
+|Build Status|
+
+=========================
+Face Privacy Filter Guide
+=========================
+
+This model contains the capability to generate two submodels: one for
+face detection and one for face suppression through pixelation.
+
+A model example for face detection from images within Acumos.
+
+.. image:: catalog_image_blur.png
+    :alt: Sample image with detection and pixelation/blur filter
+    :width: 200
+
+Background
+==========
+
+This model analyzes static images to detect frontal faces. It utilizes a
+frontal face cascade from the `OpenCV <https://opencv.org/>`__ image
+processing library. Model load time is optimized by creating and
+maintaining the fixed cascade in memory while operating. Demonstrating
+the capability of custom classes and requisite member variables, the
+cascade is serialized with the model as a string asset which is
+deserialized and loaded from disk upon startup.
+
+.. _face_privacy_usage:
+
+Usage
+-----
+
+Input to the model is an array of one or more tuples of image binary
+data and a binary mime type. The position of the image within the array
+is utilized in the output signature as a zero-based index. For example
+if three images were sent, the output probabilities would have 0, 1, and
+2 as index values. The output from this model is a repeated array of
+detected regions for each face in each input image. So that image data
+can be cascaded to other models, the original image and mime type are
+also embedded with the special region code ``-1`` within the output.
+
+A web demo is included with the source code, available via the
+`Acumos Gerrit repository <https://gerrit.acumos.org/r/gitweb?p=face-privacy-filter.git;a=summary>`__
+or the mirrored `Acumos Github repository <https://github.com/acumos/face-privacy-filter>`__. It
+utilizes a protobuf javascript library and processes input images to
+detect all faces within an image.
+
+Once deployed, you can quickly jump to the
+`default webhost page <http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html>`__
+and point to your model for a demo; see :ref:`demonstration_face-privacy` for more details.
+
+Performance
+-----------
+
+As this model wraps a preexisting cascade, no formal testing evaluation
+was performed. However, experimental usage indicates the following
+highlights.
+
+-  Faces that are too small can easily be missed.
+-  Frontal faces perform best, with some tolerance of about 5-10 degrees
+   off-plane rotation.
+-  Detection is fairly sensitive to rotation in plane, so try not to let
+   subject faces rotate more than 15 degrees.
+-  Dark or low contrast images generally do not perform well for
+   detection.
+
+More Information
+----------------
+
+As this model uses a generic cascade from OpenCV, readers can easily
+substituted or update those models with no change in API endpoint
+required. Additionally, secondary verification methods using pixel
+validation (e.g. sub-part verification, symmetry tests, or more advanced
+parts-based verifications) may dramatically improve the false alarm
+rate, although the current model was tuned for precision (instead of
+recall) already.
+
+
+Source Installation
+===================
+
+This section is useful for source-based installations and is not
+generally intended for catalog documentation.
+
+Image Analysis for Face-based Privacy Filtering
+-----------------------------------------------
+
+This source code creates and pushes a model into Acumos that processes
+incoming images and outputs a detected faces as well as the original
+image input (if configured that way). The model uses a
+`python interface <https://pypi.python.org/pypi/opencv-python>`__ to the
+`OpenCV library <https://opencv.org/>`__ to detect faces and perform subsequent
+image processing. This module does not support training at this time and
+instead uses a pre-trained face cascade, which is included (from OpenCV)
+in this module.
+
+Package dependencies
+--------------------
+
+Package dependencies for the core code and testing have been flattened
+into a single file for convenience. Instead of installing this package
+into your your local environment, execute the command below.
+
+**Note:** If you are using an
+`anaconda-based environment <https://anaconda.org>`__, you may want to try installing
+with conda first and then pip.
+
+::
+
+    conda install --yes --file requirements.txt  # suggested first step if you're using conda
+
+Installation of the package requirements for a new environment.
+
+::
+
+    pip install -r requirements.txt
+
+Usage
+-----
+
+This package contains runable scripts for command-line evaluation,
+packaging of a model (both dump and posting), and simple web-test uses.
+All functionality is encapsulsted in the ``filter_image.py`` script and
+has the following arguments.
+
+::
+
+    usage: filter_image.py [-h] [-p PREDICT_PATH] [-i INPUT] [-c]
+                           [-f {detect,pixelate}] [-s] [-a PUSH_ADDRESS]
+                           [-A AUTH_ADDRESS] [-d DUMP_MODEL]
+
+    optional arguments:
+      -h, --help            show this help message and exit
+
+    main execution and evaluation functionality:
+      -p PREDICT_PATH, --predict_path PREDICT_PATH
+                            save detections from model (model must be provided via
+                            'dump_model')
+      -i INPUT, --input INPUT
+                            absolute path to input data (image or csv, only during
+                            prediction / dump)
+      -c, --csv_input       input as CSV format not an image
+      -f {detect,pixelate}, --function {detect,pixelate}
+                            which type of model to generate
+      -s, --suppress_image  do not create an extra row for a returned image
+
+    model creation and configuration options:
+      -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
+                            server address to push the model (e.g.
+                            http://localhost:8887/v2/models)
+      -A AUTH_ADDRESS, --auth_address AUTH_ADDRESS
+                            server address for login and push of the model (e.g.
+                            http://localhost:8887/v2/auth)
+      -d DUMP_MODEL, --dump_model DUMP_MODEL
+                            dump model to a pickle directory for local running
+
+Example Usages
+==============
+
+Please consult the :ref:`tutorials_face-privacy` dirctory for usage examples
+including an in-place :ref:`demonstration_face-privacy`.
+
+Face-based Use Cases
+--------------------
+
+This project includes a number of face-based use cases including raw
+detection, blurring, and other image-based modifications based on
+detected image regions.
+
+-  **Face Detection Use-case** - This source code creates and pushes a
+   model that processes incoming images and outputs detected faces.
+
+Metadata Examples
+=================
+
+-  example detect catalog image - `url source <https://flic.kr/p/xqw25C>`__
+-  example blur catalog image - `url source <https://flic.kr/p/bEgYbs>`__
+
+
+
+.. |Build Status| image:: https://jenkins.acumos.org/buildStatus/icon?job=face-privacy-filter-tox-verify-master
+   :target: https://jenkins.acumos.org/job/face-privacy-filter-tox-verify-master/
+
index 9407b4e..8bfa4e7 100644 (file)
@@ -23,6 +23,6 @@ Face Privacy Filter
 .. toctree::
        :maxdepth: 2
 
-       release-notes
        face-privacy-filter
-       tutorials/index
\ No newline at end of file
+       tutorials/index
+       release-notes
diff --git a/docs/release-notes.md b/docs/release-notes.md
deleted file mode 100644 (file)
index afa75c5..0000000
+++ /dev/null
@@ -1,67 +0,0 @@
-<!---
-.. ===============LICENSE_START=======================================================
-.. Acumos CC-BY-4.0
-.. ===================================================================================
-.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-.. ===================================================================================
-.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
-.. under the Creative Commons Attribution 4.0 International License (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-..      http://creativecommons.org/licenses/by/4.0
-..
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
--->
-
-# Face Privacy Filter Release Notes
-## 0.3
-### 0.3.3
-* Clean up documentation for install and parameter descriptions
-* Add documentation and functionality for environment variables in push request
-
-### 0.3.2
-* Minor updates to web JS demo pages for pending recognition model
-* *Type Change* rename input and output types to **region** monikers to better reflect target
-
-### 0.3.1
-* Update model to use single image as input type
-* Update javascript demo to run with better CORS behavior (github htmlpreview)
-* Additional documentation for environmental variables
-* Simplify operation for active prediction to use created model (no save+load required)
-
-### 0.3.0
-* Documentation (lesson1) updated with model runner examples.  Deprecation notice
-  in using explicit proto- and swagger-based serves.
-* Update the structure of the protobuf input and output to use flattened (row-based)
-  structure instead of columnar data for all i/o channels.  This should allow
-  other inspecting applications to more easily understand and reuse implementations
-  for image data.
-* Update the demonstration HTML pages for similar modifications.
-
-## 0.2
-### 0.2.3
-* Documentation and package update to use install instructions instead of installing
-  this package directly into a user's environment.
-* License addition
-
-### 0.2.2
-* Refactor documentation into sections and tutorials.
-* Create this release notes document for better version understanding.
-
-### 0.2.1
-* Refactor to remote the demo `bin` scripts and rewire for direct call of the
-  script `filter_image.py` as the primary interaction mechanism.
-
-### 0.2.0
-* Refactor for compliant dataframe usage following primary client library
-  examples for repeated columns (e.g. dataframes) instead of custom types
-  that parsed rows individually.
-* Refactor web, api, main model wrapper code for corresponding changes.
-* Migration from previous library structure to new acumos client library
-* Refactor to not need **this** library as a runtime/installed dependency
-
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
new file mode 100644 (file)
index 0000000..4690dc5
--- /dev/null
@@ -0,0 +1,95 @@
+.. ===============LICENSE_START=======================================================
+.. Acumos CC-BY-4.0
+.. ===================================================================================
+.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
+.. ===================================================================================
+.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
+.. under the Creative Commons Attribution 4.0 International License (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..      http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+.. _release_notes_face-privacy:
+
+=================================
+Face Privacy Filter Release Notes
+=================================
+
+0.3.4
+=====
+
+-  Clean up tutorial documentation naming and remove deprecated swagger demo app
+
+0.3.3
+=====
+
+-  Clean up documentation for install and parameter descriptions
+-  Add documentation and functionality for environment variables in push
+   request
+
+0.3.2
+=====
+
+-  Minor updates to web JS demo pages for pending recognition model
+-  *Type Change* rename input and output types to **region** monikers to
+   better reflect target
+
+0.3.1
+=====
+
+-  Update model to use single image as input type
+-  Update javascript demo to run with better CORS behavior (github
+   htmlpreview)
+-  Additional documentation for environmental variables
+-  Simplify operation for active prediction to use created model (no
+   save+load required)
+
+0.3.0
+=====
+
+-  Documentation (lesson1) updated with model runner examples.
+   Deprecation notice in using explicit proto- and swagger-based serves.
+-  Update the structure of the protobuf input and output to use
+   flattened (row-based) structure instead of columnar data for all i/o
+   channels. This should allow other inspecting applications to more
+   easily understand and reuse implementations for image data.
+-  Update the demonstration HTML pages for similar modifications.
+
+0.2.3
+=====
+
+-  Documentation and package update to use install instructions instead
+   of installing this package directly into a user's environment.
+-  License addition
+
+0.2.2
+=====
+
+-  Refactor documentation into sections and tutorials.
+-  Create this release notes document for better version understanding.
+
+0.2.1
+=====
+
+-  Refactor to remote the demo ``bin`` scripts and rewire for direct
+   call of the script ``filter_image.py`` as the primary interaction
+   mechanism.
+
+0.2.0
+=====
+
+-  Refactor for compliant dataframe usage following primary client
+   library examples for repeated columns (e.g. dataframes) instead of
+   custom types that parsed rows individually.
+-  Refactor web, api, main model wrapper code for corresponding changes.
+-  Migration from previous library structure to new acumos client
+   library
+-  Refactor to not need **this** library as a runtime/installed
+   dependency
diff --git a/docs/tutorials/demonstration.rst b/docs/tutorials/demonstration.rst
new file mode 100644 (file)
index 0000000..a511be0
--- /dev/null
@@ -0,0 +1,165 @@
+.. ===============LICENSE_START=======================================================
+.. Acumos CC-BY-4.0
+.. ===================================================================================
+.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
+.. ===================================================================================
+.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
+.. under the Creative Commons Attribution 4.0 International License (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..      http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+.. _demonstration_face-privacy:
+
+=========================================
+Demonstrations: Tutorial for Face Privacy
+=========================================
+
+Web Demo
+========
+
+This web page sample allows the user to submit an image to a face
+detection and a face pixelation service in serial progression.
+
+* ***Image Copyrights May Apply*** - the included sample videos may
+carry additional copyright restrictions and are not meant for public resale or
+consumption.
+
+Browser Interaction
+===================
+
+Most browsers should have no CORS or other cross-domain objections to
+dropping the file ``face-privacy.html`` into the browser and accesing a
+locally hosted server API, as configured in :ref:`deployment_face-privacy`.
+
+
+Open-source hosted run
+-----------------------
+
+Utilizing the generous `htmlpreview function <https://htmlpreview.github.io/>`__
+available on GitHub, you
+can also experiment with the respository-based web resource. This
+resource will proxy the repository ``web_demo`` directory into a live
+resource.
+
+Navigate to the
+`default webhost page <http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html>`__
+and confirm that the resource load properly. The image at the bottom of
+this guide is a good reference for correct page loading and display.
+
+After confirming correct page load, simply replace the value in the
+``Transform URL`` field to point at your deployed instance. For example,
+if you've created a dumped model locally, it might be a localhost port.
+
+
+Local webserver run
+-------------------
+
+If you want to run the test locally, you can use the built-in python
+webserver with the line below while working in the ``web_demo``
+directory (assuming you're running python3).
+
+::
+
+    python -m http.server 5000
+
+Afterwards, just point your browser at
+``http://localhost:5000/face-privacy.html``.
+
+
+Example face privacy demo (docker and protobuf)
+===============================================
+
+To customize this demo, one should change either the included javascript
+or simply update the primary classification URL on the page itself
+during runtime. This demo utilizes the
+`javascript protobuf library <https://github.com/dcodeIO/ProtoBuf.js/>`__ to encode
+parameters into proto binaries in the browser.
+
+***NOTE*** One version of the face model's protobuf schema is
+included with this web page, but it may change over time. If you receive
+encoding errors or unexpected results, please verify that your target
+model and this web page are using the same ``.proto`` file.
+
+-  confirm that your target docker instance is configured and running
+-  download this directory to your local machine
+
+   -  confirm the host port and classification service URL in the file
+      ``face-privacy.js``
+   -  modify the ``protoDefault`` setting to be 1
+
+      ::
+
+          urlDefault: "http://localhost:8884/transform",
+
+-  view the page ``face-privacy.html`` in a Crome or Firefox browser
+-  you can switch between a few sample images or upload your own by
+   clicking on the buttons below the main image window
+
+
+Special decoding example
+------------------------
+
+In ``protobuf`` mode, you can also download a binary, encoded version of
+the last image that was sent to the remote service. When available, the
+Download Encoded Message button will be enabled and a binary file will
+be generated in the browser.
+
+::
+
+    protoc --decode=HipTviKTkIkcmyuMCIAIDkeOOQQYyJne.Image model.pixelate.proto < protobuf.bin
+
+**NOTE** The specific package name may have changed since the time of
+writing, so be sure to check the contents of the current ``.proto``
+file.
+
+Example face privacy demo (HTTP parameters)
+-------------------------------------------
+
+To customize this demo, one should change either the included javascript
+or simply update the primary classification URL on the page itself
+during runtime.
+
+-  confirm that your local instance is configured and running
+-  download this directory to your local machine
+
+   -  confirm the host port and classification service URL in the file
+      ``face-privacy.js``
+   -  modify the ``protoDefault`` setting to be 0
+
+      ::
+
+          urlDefault: "http://localhost:8884/transform",
+
+-  view the page ``face-privacy.html`` in a Crome or Firefox browser
+-  you can switch between a few sample images or upload your own by
+   clicking on the buttons below the main image window
+
+Example Interface
+=================
+
+An instance should first be built and downloaded and then launched
+locally. Afterwards, the sample application found in the
+``web_demo`` directory uses a ``localhost`` service to classify and
+visualize the results of image classification.
+
+-  Commercial example (`youtube source <https://www.youtube.com/watch?v=34KfCNapnUg>`__)
+-  Reunion face sample  `flickr source <https://flic.kr/p/bEgYbs>`__)
+-  family face example (`pexel source <https://www.pexels.com/photo/adult-affection-beautiful-beauty-265764/>`__)
+-  DiCaprio celebrity face sample (`wikimedia source <https://en.wikipedia.org/wiki/Celebrity#/media/File:Leonardo_DiCaprio_visited_Goddard_Saturday_to_discuss_Earth_science_with_Piers_Sellers_(26105091624)_cropped.jpg>`__)
+-  Schwarzenegger celebrity (`wikimedia source <https://upload.wikimedia.org/wikipedia/commons/thumb/0/0f/A._Schwarzenegger.jpg/220px-A._Schwarzenegger.jpg>`__)
+-  DeGeneres celebrity face sample (`wikipedia source <https://en.wikipedia.org/wiki/Ellen_DeGeneres#/media/File:Ellen_DeGeneres-2009.jpg>`__)
+
+
+.. image:: example_running.jpg
+    :alt: example web application with *awe* mood
+    :width: 200
+
+
diff --git a/docs/tutorials/deployment.rst b/docs/tutorials/deployment.rst
new file mode 100644 (file)
index 0000000..20fa7c3
--- /dev/null
@@ -0,0 +1,163 @@
+.. ===============LICENSE_START=======================================================
+.. Acumos CC-BY-4.0
+.. ===================================================================================
+.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
+.. ===================================================================================
+.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
+.. under the Creative Commons Attribution 4.0 International License (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..      http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+.. _deployment_face-privacy:
+
+======================================================
+Deployment: Wrapping and Executing Face Privacy Models
+======================================================
+
+To utilize this transformer model set, it first creates a detect
+transformer and then a pixelate transformer. Continue to the
+:ref:`demonstration_face-privacy`  to see how to utilize these models with a
+simple demo API server.
+
+
+Model Deployment
+----------------
+
+Following similar use pattens described by the main client library,
+there are two primary modes to export and deploy the generated
+classifier: by dumping it to disk or by pushing it to an onboarding
+server. Please consult the :ref:`face_privacy_usage` for more specific arguments
+but the examples below demonstrate basic capabilities.
+
+This single repo has a number of different models that can be composed
+together for operation.
+
+-  Dump the ``detect`` model to disk.
+
+   ::
+
+       python face_privacy_filter/filter_image.py -f detect  -d model_detect
+
+-  Dump the ``pixelate`` model to disk.
+
+   ::
+
+       python face_privacy_filter/filter_image.py -f pixelate -d model_pix
+
+Below is an extended for training a model, dumping it to disk, and
+pushing that model. **(recommended)**
+
+::
+
+    export ACUMOS_USERNAME="user"; \
+    export ACUMOS_PASSWORD="password";
+    or
+    export ACUMOS_TOKEN="a_very_long_token";
+
+    export ACUMOS_PUSH="https://acumos-challenge.org/onboarding-app/v2/models"; \
+    export ACUMOS_AUTH="https://acumos-challenge.org/onboarding-app/v2/auth"; \
+    python face_privacy_filter/filter_image.py -f detect
+
+
+In-place Evaluation
+-------------------
+
+In-place evaluation **will utilize** a serialized version of the model
+and load it into memory for use in-place. This mode is handy for quick
+evaluation of images or image sets for use in other classifiers.
+
+-  Evaluate the ``detect`` model from disk and a previously produced
+   detect object
+
+   ::
+
+       python face_privacy_filter/filter_image.py -d model_detect -p output.csv -i web_demo/images/face_DiCaprio.jpg
+
+-  Example for evaluating the ``pixelate`` model from disk and a
+   previously produced detect object
+
+   ::
+
+       python face_privacy_filter/filter_image.py -d model_pix -i detect.csv -p output.jpg --csv_input
+
+
+Using the client model runner
+-----------------------------
+
+Getting even closer to what it looks like in a deployed model, you can
+also use the model runner code to run your full cascade (detection +
+pixelate) transform locally. *(added v0.3.0)*
+
+1. First, decide the ports to run your detection and pixelate models. In
+   the example below, detection runs on port ``8884`` and pixelation
+   runs on port ``8885``. For the runner to properly forward requests
+   for you, provide a simple JSON file example called ``runtime.json``
+   in the working directory that you run the model runner.
+
+::
+
+    # cat runtime.json
+    {downstream": ["http://127.0.0.1:8885/pixelate"]}
+
+2. Second, dump and launch the face detection model. If you modify the
+   ports to run the models, please change them accordingly. This command
+   example assumes that you have cloned the client library in a relative
+   path of ``../acumos-python-client``. The first line removes any prior
+   model directory, the second dumps the detect model to disk, and the
+   third runs the model.
+
+::
+
+    rm -rf model_detect/;  \
+        python face_privacy_filter/filter_image.py -d model_detect -f detect; \
+        python ../acumos-python-client/testing/wrap/runner.py --port 8884 --modeldir model_detect/face_privacy_filter_detect
+
+3. Finally, dump and launch the face pixelation model. Again, if you
+   modify the ports to run the models, please change them accordingly.
+   Aside from the model and port, the main difference between the above
+   line is that the model runner is instructed to *ignore* the
+   downstream forward (``runtime.json``) file so that it doesn't attempt
+   to forward the request to itself.
+
+::
+
+    rm -rf model_pix;  \
+        python face_privacy_filter/filter_image.py -d model_pix -f pixelate; \
+        python ../acumos-python-client/testing/wrap/runner.py --port 8885 --modeldir model_pix/face_privacy_filter_pixelate  --no_downstream
+
+Installation Troubleshoting
+===========================
+
+Using some environment-based versions of python (e.g. conda), one
+problem seemed to come up with the installation of the dependent package
+``opencv-python``. If you launch your python instance and see an error
+like the one below, keep reading.
+
+::
+
+    >>> import cv2
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    ImportError: dynamic module does not define module export function (PyInit_cv2)
+    >>>
+
+This is likely because your ``PYTHONPATH`` is not correctly configured
+to point to the additional installed libraries.
+
+-  From the `simple example
+   here <https://stackoverflow.com/a/42160595>`__ you can check your
+   environment with ``echo $PYTHONPATH``. If it does not contain the
+   directory that you installed to, then you have a problem.
+-  Please check your installation by running
+   ``python -v -v; import cv2`` and checking that the last loaded
+   library is in the right location.
+-  In some instances, this variable needed to be blank to work properly
+   (i.e. ``export PYTHONPATH=``) run at some time during start up.
index f2ad5e2..63ac5b6 100644 (file)
@@ -8,7 +8,7 @@
 .. you may not use this file except in compliance with the License.
 .. You may obtain a copy of the License at
 ..
-..      http://creativecommons.org/licenses/by/4.0
+.. http://creativecommons.org/licenses/by/4.0
 ..
 .. This file is distributed on an "AS IS" BASIS,
 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 .. limitations under the License.
 .. ===============LICENSE_END=========================================================
 
-========
+.. _tutorials_face-privacy:
+
 Tutorial
-========
+--------
 
 .. toctree::
        :maxdepth: 2
 
-       lesson1
-       lesson2
-       lesson3
+       deployment
+       demonstration
diff --git a/docs/tutorials/lesson1.md b/docs/tutorials/lesson1.md
deleted file mode 100644 (file)
index 38c6ff2..0000000
+++ /dev/null
@@ -1,139 +0,0 @@
-<!---
-.. ===============LICENSE_START=======================================================
-.. Acumos CC-BY-4.0
-.. ===================================================================================
-.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-.. ===================================================================================
-.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
-.. under the Creative Commons Attribution 4.0 International License (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-..      http://creativecommons.org/licenses/by/4.0
-..
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
--->
-
-# Wrapping Models for Deployment
-To utilize this transformer model set, it first creates a detect transformer
-and then a pixelate transformer.
-Continue to the [next tutorial](lesson2.md)
-to see how to utilize these models with a simple demo API server.
-
-
-## Model Deployment
-Following similar use pattens described by the main client library, there are
-two primary modes to export and deploy the generated classifier: by dumping
-it to disk or by pushing it to an onboarding server.  Please consult the
-[reference manual](../image-classification.md#usage) for more specific arguments
-but the examples below demonstrate basic capabilities.
-
-This single repo has a number of different models that can be
-composed together for operation.
-
-* Dump the `detect` model to disk.
-```
-python face_privacy_filter/filter_image.py -f detect  -d model_detect
-```
-* Dump the `pixelate` model to disk.
-```
-python face_privacy_filter/filter_image.py -f pixelate -d model_pix
-```
-
-Below is an extended for training a model, dumping it to disk, and pushing that model. **(recommended)**
-```
-export ACUMOS_USERNAME="user"; \
-export ACUMOS_PASSWORD="password";
-or
-export ACUMOS_TOKEN="a_very_long_token";
-
-export ACUMOS_PUSH="https://acumos-challenge.org/onboarding-app/v2/models"; \
-export ACUMOS_AUTH="https://acumos-challenge.org/onboarding-app/v2/auth"; \
-python face_privacy_filter/filter_image.py -f detect
-```
-
-
-## In-place Evaluation
-In-place evaluation **will utilize** a serialized version of the model and load
-it into memory for use in-place.  This mode is handy for quick
-evaluation of images or image sets for use in other classifiers.
-
-* Evaluate the `detect` model from disk and a previously produced detect object
-```
-python face_privacy_filter/filter_image.py -d model_detect -p output.csv -i web_demo/images/face_DiCaprio.jpg
-```
-* Example for evaluating the `pixelate` model from disk and a previously produced detect object
-```
-python face_privacy_filter/filter_image.py -d model_pix -i detect.csv -p output.jpg --csv_input
-```
-
-## Using the client model runner
-Getting even closer to what it looks like in a deployed model, you can also use
-the model runner code to run your full cascade (detection + pixelate) transform
-locally. *(added v0.3.0)*
-
-1. First, decide the ports to run your detection and pixelate models. In the example
-below, detection runs on port `8884` and pixelation runs on port `8885`.  For the
-runner to properly forward requests for you, provide a simple JSON file example
-called `runtime.json` in the working directory that you run the model runner.
-
-```
-# cat runtime.json
-{downstream": ["http://127.0.0.1:8885/pixelate"]}
-```
-
-2. Second, dump and launch the face detection model. If you modify the ports to
-run the models, please change them accordingly.  This command example assumes
-that you have cloned the client library in a relative path of `../acumos-python-client`.
-The first line removes any prior model directory, the second dumps the detect
-model to disk, and the third runs the model.
-
-```
-rm -rf model_detect/;  \
-    python face_privacy_filter/filter_image.py -d model_detect -f detect; \
-    python ../acumos-python-client/testing/wrap/runner.py --port 8884 --modeldir model_detect/face_privacy_filter_detect
-
-```
-
-3. Finally, dump and launch the face pixelation model. Again, if you modify the ports to
-run the models, please change them accordingly.  Aside from the model and port,
-the main difference between the above line is that the model runner is instructed
-to *ignore* the downstream forward (`runtime.json`) file so that it doesn't attempt
-to forward the request to itself.
-
-```
-rm -rf model_pix;  \
-    python face_privacy_filter/filter_image.py -d model_pix -f pixelate; \
-    python ../acumos-python-client/testing/wrap/runner.py --port 8885 --modeldir model_pix/face_privacy_filter_pixelate  --no_downstream
-```
-
-
-# Installation Troubleshoting
-Using some environment-based versions of python (e.g. conda),
-one problem seemed to come up with the installation of the dependent
-package `opencv-python`.  If you launch your python instance and see
-an error like the one below, keep reading.
-
-```
->>> import cv2
-Traceback (most recent call last):
-  File "<stdin>", line 1, in <module>
-ImportError: dynamic module does not define module export function (PyInit_cv2)
->>>
-```
-
-This is likely because your `PYTHONPATH` is not correctly configured to
-point to the additional installed libraries.
-
-* From the [simple example here](https://stackoverflow.com/a/42160595)
-you can check your environment with `echo $PYTHONPATH`.  If it does not
-contain the directory that you installed to, then you have a problem.
-* Please check your installation by running `python -v -v; import cv2` and checking
-that the last loaded library is in the right location.
-* In some instances, this variable needed to be blank to work properly (i.e.
-`export PYTHONPATH=`) run at some time during start up.
-
diff --git a/docs/tutorials/lesson2.md b/docs/tutorials/lesson2.md
deleted file mode 100644 (file)
index bea69ef..0000000
+++ /dev/null
@@ -1,159 +0,0 @@
-<!---
-.. ===============LICENSE_START=======================================================
-.. Acumos CC-BY-4.0
-.. ===================================================================================
-.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-.. ===================================================================================
-.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
-.. under the Creative Commons Attribution 4.0 International License (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-..      http://creativecommons.org/licenses/by/4.0
-..
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
--->
-
-# Application server
-As a means of testing the API and demonstrating functionality, two
-additional components are included in this repository:
-a simple [swagger-based webserver](../../testing) (documented here) and
-a [demo web page](../../web_demo) (documented in the [next tutorial](lesson3.md).
-
-**NOTE: These steps are now deprecated and a direct protobuf interface from
-web page to the model (the next tutorial) is the preferred operational step.
-*(added v0.2.3)* **
-
-## Swagger API
-Using a simple [flask-based connexion server](https://github.com/zalando/connexion),
-an API scaffold has been built to host a serialized/dumped model.
-
-To utilized [this example app](../../testing), an instance should first be built and downloaded
-from Acumos (or dumped to disk) and then
-launched locally.  Afterwards, the sample application found in
-[web_demo](web_demo) (see [the next tutorial](lesson3.md))
-uses a `localhost` service to transform
-and visualize the results of model operation.
-
-
-```
-usage: app.py [-h] [-p PORT] [-d MODELDIR_DETECT] [-a MODELDIR_ANALYZE]
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -p PORT, --port PORT  port to launch the simple web server
-  -d MODELDIR_DETECT, --modeldir_detect MODELDIR_DETECT
-                        model directory for detection
-  -a MODELDIR_ANALYZE, --modeldir_analyze MODELDIR_ANALYZE
-                        model directory for detection
-```
-
-
-Example usage may be running with a detect model that was dumped to the directory `model_detect`
-in the main repo source directory and a pixelate model in the
-directory `model_pix` (under the same repo source directory).
-
-```
-python app.py --modeldir_detect ../model_detect --modeldir_analyze ../model_pix/
-```
-
-
-### Output formats
-This repo provides multiple models that can be created.
-
-* detect output - The first set, called
-`detect` will analyze an image, detect face regions, and echo both the
-regions and the face back to the user.  The region marked with `-1`
-and a valid `mime_type` parameter will
-always be the region with the original image.
-
-
-```
-[
-    {
-        "h": 143,
-        "x": 0,
-        "y": 0,
-        "base64_data": "/9j/4AAQSkZJRgABA....",
-        "w": 2048,
-        "region": -1,
-        "image": 0,
-        "mime_type": "image/jpeg"
-    },
-    {
-        "h": 143,
-        "x": 203,
-        "y": 189,
-        "base64_data": "",
-        "w": 143,
-        "region": 0,
-        "image": 0,
-        "mime_type": ""
-    },
-    ...
-    {
-        "h": 212,
-        "x": 886,
-        "y": 409,
-        "base64_data": "",
-        "w": 212,
-        "region": 3,
-        "image": 0,
-        "mime_type": ""
-    }
-]
-
-```
-
-* analyzed output - The second type of output produces processed
-images as an output.  These images are base64 encoded with a decoding
-mime type.
-
-```
-[
-    {
-        "base64_data": "/9j/4AAQSkZJRgABAQAAAQABAAD....",
-        "mime_type": "image/jpeg"
-    }
-]
-
-```
-
-### Direct use of the model-runner
-
-Another testing mode is to simualate the output of an Acumos model runner.
-This model runner can be locally duplicated by using the primary python library
-`acumos-python-client`.  This execution usage is experimental, but the APIs should
-be consistent for use.
-
-```
-python acumos-python-client/testing/wrap/runner.py  --port 8884 --modeldir model_detect/
-```
-
-The above command uses the testing-based model runner to launch a singular model
-that responds on a single port in native `protobuf` format.
-
-
-
-## Direct Evaluation
-
-* For a graphical experience, view the swagger-generated UI at [http://localhost:8884/ui].
-* Additionally, a simple command-line utility could be used to post an image
-and mime type to the main interface.  Additional examples for posting base64 encoded
-images from javascript can be [found on StackOverflow](https://stackoverflow.com/a/20285053).
-
-```
-curl -F base64_data=@../web_demo/images/face_renion.jpg -F mime_type="image/jpeg" "http://localhost:8884/transform"
-```
-
-## Sample Images
-Sample images are provided in the `testing` directory and were originally sourced
-from the URLs below.
-
-* [multi-face_pexels.jpg](https://www.pexels.com/photo/family-generation-father-mother-8509/)
-* [single-face_pexels.jpg](https://www.pexels.com/photo/adult-beard-boy-casual-220453/)
-
diff --git a/docs/tutorials/lesson3.md b/docs/tutorials/lesson3.md
deleted file mode 100644 (file)
index 8ae2b6d..0000000
+++ /dev/null
@@ -1,129 +0,0 @@
-<!---
-.. ===============LICENSE_START=======================================================
-.. Acumos CC-BY-4.0
-.. ===================================================================================
-.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-.. ===================================================================================
-.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
-.. under the Creative Commons Attribution 4.0 International License (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-..      http://creativecommons.org/licenses/by/4.0
-..
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
--->
-
-# Web Demo
-This web page sample allows the user to submit an image to
-a face detection and a face pixelation service
-in serial progression.
-
-** Image Copyrights May Apply ** - the included sample videos may carry
-additional copyrights and are not meant for public resale or consumption.
-
-## Browser Interaction
-Most browsers should have no
-CORS or other cross-domain objections to dropping the file `face-privacy.html`
-into the browser and accesing a locally hosted server API, as configured
-in [the previous tutorial](lesson2.md).
-
-### Open-source hosted run
-Utilizing the generous [htmlpreview function](https://htmlpreview.github.io/) available on
-GitHub, you can also experiment with the respository-based web resource.  This resource
-will proxy the repository `web_demo` directory into a live resource.
-
-Navigate to the [default webhost page](http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html)
-and confirm that the resource load properly.  The image at the bottom of this guide
-is a good reference for correct page loading and display.
-
-After confirming correct page load, simply replace the value in the `Transform URL`
-field to point at your deployed instance.  For example, if you've created a
-dumped model locally, it might be a localhost port.
-
-
-### Local webserver run
-If you want to run the test locally, you can use the built-in python
-webserver with the line below while working in the `web_demo` directory
-(assuming you're running python3).
-```
-python -m http.server 5000
-```
-
-Afterwards, just point your browser at `http://localhost:5000/face-privacy.html`.
-
-## Example face privacy demo (docker and protobuf)
-To customize this demo, one should change either the included javascript
-or simply update the primary classification URL on the page itself during runtime.
-This demo utilizes the [javascript protobuf library](https://github.com/dcodeIO/ProtoBuf.js/)
-to encode parameters into proto binaries in the browser.
-
-** NOTE ** One version of the face model's protobuf schema is included with
-this web page, but it may change over time.  If you receive encoding errors
-or unexpected results, please verify that your target model and this web page
-are using the same `.proto` file.
-
-* confirm that your target docker instance is configured and running
-* download this directory to your local machine
-    * confirm the host port and classification service URL in the file `face-privacy.js`
-    * modify the `protoDefault` setting to be 1
-```
-urlDefault: "http://localhost:8884/transform",
-```
-* view the page `face-privacy.html` in a Crome or Firefox browser
-* you can switch between a few sample images or upload your own by clicking on the buttons below the main image window
-
-Example web application with blur process.
-
-* ![example web application blurring multiple faces](example_running.jpg "Example multi-face blur")
-
-### Special decoding example
-In `protobuf` mode, you can also download a binary, encoded version of the last
-image that was sent to the remote service.  When available, the <strong>Download Encoded Message</strong>
-button will be enabled and a binary file will be generated in the browser.
-
-```
-protoc --decode=HipTviKTkIkcmyuMCIAIDkeOOQQYyJne.Image model.pixelate.proto < protobuf.bin
-```
-
-**NOTE** The specific package name may have changed since the time of writing,
-so be sure to check the contents of the current `.proto` file.
-
-
-## Example face privacy demo (HTTP parameters)
-To customize this demo, one should change either the included javascript
-or simply update the primary classification URL on the page itself during runtime.
-
-* confirm that your local instance is configured and running
-* download this directory to your local machine
-    * confirm the host port and classification service URL in the file `face-privacy.js`
-    * modify the `protoDefault` setting to be 0
-```
-urlDefault: "http://localhost:8884/transform",
-```
-* view the page `face-privacy.html` in a Crome or Firefox browser
-* you can switch between a few sample images or upload your own by clicking on the buttons below the main image window
-
-
-# Example Interface
-An instance should first be built and downloaded and then
-launched locally.  Afterwards, the sample application found in
-[web_demo](web_demo) uses a `localhost` service to classify
-and visualize the results of image classification.
-
-* [Commercial example](../../web_demo/images/commercial.jpg) ([youtube source](https://www.youtube.com/watch?v=34KfCNapnUg))
-* [Reunion face sample](../../web_demo/images/face_reunion.jpg) ([flickr source](https://flic.kr/p/bEgYbs))
-* [family face example](../../web_demo/images/face_family.jpg) ([pexel source](https://www.pexels.com/photo/adult-affection-beautiful-beauty-265764/))
-* [DiCaprio celebrity face sample](../../web_demo/images/face_DiCaprio.jpg) ([wikimedia source](https://en.wikipedia.org/wiki/Celebrity#/media/File:Leonardo_DiCaprio_visited_Goddard_Saturday_to_discuss_Earth_science_with_Piers_Sellers_(26105091624)_cropped.jpg))
-* [Schwarzenegger celebrity face sample](../../web_demo/images/face_Schwarzenegger.jpg) ([wikimedia source](https://upload.wikimedia.org/wikipedia/commons/thumb/0/0f/A._Schwarzenegger.jpg/220px-A._Schwarzenegger.jpg))
-* [DeGeneres celebrity face sample](../../web_demo/images/face_DeGeneres.jpg) ([wikipedia source](https://en.wikipedia.org/wiki/Ellen_DeGeneres#/media/File:Ellen_DeGeneres-2009.jpg))
-
-
-before  | after
-------- | -------
-![raw commercial](../../web_demo/images/commercial.jpg)  | ![pixelated commercial](../../web_demo/images/commercial_pixelate.jpg)
-![raw face](../../web_demo/images/face_family.jpg)  | ![pixelated commercial](../../web_demo/images/face_family_pixelate.jpg)
index 7269653..e5d64b4 100644 (file)
@@ -1,3 +1,3 @@
 # -*- coding: utf-8 -*-
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 MODEL_NAME = 'face_privacy_filter'
similarity index 78%
rename from testing/README.md
rename to testing/README.rst
index 104fafb..7664c96 100644 (file)
@@ -1,4 +1,3 @@
-<!---
 .. ===============LICENSE_START=======================================================
 .. Acumos CC-BY-4.0
 .. ===================================================================================
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 .. ===============LICENSE_END=========================================================
--->
 
-# testing
-This directory provides a simple web server for demonstrating an image-based classifier example.
-This web demo will launch an application with a swagger page.
+.. _testing:
 
-Please consult the [tutorial documentation](../docs/tutorials/lesson2.md) for more information.
+=======
+Testing
+=======
+This directory provides in-place testing. Please consult the
+`main documentation <../docs/image-mood-classifier.rst>`__ for more information.
\ No newline at end of file
diff --git a/testing/app.py b/testing/app.py
deleted file mode 100755 (executable)
index 999f8cb..0000000
+++ /dev/null
@@ -1,109 +0,0 @@
-# -*- coding: utf-8 -*-
-# ===============LICENSE_START=======================================================
-# Acumos Apache-2.0
-# ===================================================================================
-# Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-# ===================================================================================
-# This Acumos software file is distributed by AT&T and Tech Mahindra
-# under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# This file is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-# ===============LICENSE_END=========================================================
-import connexion
-import logging
-
-import argparse
-import json
-import time
-import os
-
-from flask import current_app, make_response
-
-import pandas as pd
-import numpy as np
-
-from acumos.wrapped import load_model
-import base64
-
-
-def generate_image_df(path_image="", bin_stream=b""):
-    # munge stream and mimetype into input sample
-    if path_image and os.path.exists(path_image):
-        bin_stream = open(path_image, 'rb').read()
-    # bin_stream = base64.b64encode(bin_stream)
-    # if type(bin_stream) == bytes:
-    #     bin_stream = bin_stream.decode()
-    return pd.DataFrame([['image/jpeg', bin_stream]], columns=["mime_type", "image_binary"])
-
-
-def transform(mime_type, image_binary):
-    app = current_app
-    time_start = time.clock()
-    image_read = image_binary.stream.read()
-    X = generate_image_df(bin_stream=image_read)
-
-    pred_out = None
-    if app.model_detect is not None:    # first translate to input type
-        type_in = app.model_detect.transform._input_type
-        detect_in = type_in(*tuple(col for col in X.values.T))
-        pred_out = app.model_detect.transform.from_wrapped(detect_in)
-    if app.model_proc is not None and pred_out is not None:  # then transform to output type
-        pred_out = app.model_proc.transform.from_pb_msg(pred_out.as_pb_msg()).as_wrapped()
-    time_stop = time.clock()-time_start
-
-    pred = None
-    if pred_out is not None:
-        pred = pd.DataFrame(list(zip(*pred_out)), columns=pred_out._fields)
-        pred['image_binary'] = pred['image_binary'].apply(lambda x: base64.b64encode(x).decode())
-    retStr = json.dumps(pred.to_dict(orient='records'), indent=4)
-
-    # formulate response
-    resp = make_response((retStr, 200, {}))
-    # allow 'localhost' from 'file' or other;
-    # NOTE: DO NOT USE IN PRODUCTION!!!
-    resp.headers['Access-Control-Allow-Origin'] = '*'
-    print(retStr[:min(200, len(retStr))])
-    # print(pred)
-    return resp
-
-
-if __name__ == '__main__':
-    parser = argparse.ArgumentParser()
-    parser.add_argument('-p', "--port", type=int, default=8884, help='port to launch the simple web server')
-    parser.add_argument('-d', "--modeldir_detect", type=str, default='../model_detect', help='model directory for detection')
-    parser.add_argument('-a', "--modeldir_analyze", type=str, default='../model_pix', help='model directory for detection')
-    pargs = parser.parse_args()
-
-    print("Configuring local application... {:}".format(__name__))
-    logging.basicConfig(level=logging.INFO)
-    app = connexion.App(__name__)
-    app.add_api('swagger.yaml')
-    # example usage:
-    #     curl -F image_binary=@test.jpg -F mime_type="image/jpeg" "http://localhost:8885/transform"
-
-    app.app.model_detect = None
-    if pargs.modeldir_detect:
-        if not os.path.exists(pargs.modeldir_detect):
-            print("Failed loading of detect model '{:}' even though it was specified...".format(pargs.modeldir_detect))
-        else:
-            print("Loading detect model... {:}".format(pargs.modeldir_detect))
-            app.app.model_detect = load_model(pargs.modeldir_detect)
-
-    app.app.model_proc = None
-    if pargs.modeldir_analyze:
-        if not os.path.exists(pargs.modeldir_analyze):
-            print("Failed loading of processing model '{:}' even though it was specified...".format(
-                pargs.modeldir_analyze))
-        else:
-            print("Loading processing model... {:}".format(pargs.modeldir_analyze))
-            app.app.model_proc = load_model(pargs.modeldir_analyze)
-
-    # run our standalone gevent server
-    app.run(port=pargs.port) #, server='gevent')
diff --git a/testing/swagger.yaml b/testing/swagger.yaml
deleted file mode 100644 (file)
index 832e311..0000000
+++ /dev/null
@@ -1,36 +0,0 @@
-swagger: '2.0'
-info:
-  title: Face Privacy Filter Example
-  version: "0.2"
-consumes:
-  - application/json
-produces:
-  - application/json
-paths:
-  /transform:
-    post:
-      operationId: app.transform
-      summary: Post an image for processing
-      parameters:
-        - $ref: '#/parameters/mime_type'
-        - $ref: '#/parameters/image_binary'
-      responses:
-        200:
-          description: Image processed
-
-parameters:
-  mime_type:
-    name: mime_type
-    description: Image MimeType
-    in: formData
-    type: string
-    required: true
-    default: 'image/jpeg'
-    # pattern: "^[a-zA-Z0-9-]+$"
-  image_binary:
-    name: image_binary
-    description: Binary image blob
-    in: formData
-    type: file
-    format: base64
-    required: true