- refactor docs following other model examples
authorEric Zavesky <ezavesky@research.att.com>
Sat, 18 Nov 2017 06:34:19 +0000 (00:34 -0600)
committerEric Zavesky <ezavesky@research.att.com>
Sat, 18 Nov 2017 06:34:19 +0000 (00:34 -0600)
README.md
docs/face-privacy-filter.md [changed from symlink to file mode: 0644]
docs/release-notes.md
docs/tutorials/example_running.jpg [moved from web_demo/example_running.jpg with 100% similarity]
docs/tutorials/lesson1.md [new file with mode: 0644]
docs/tutorials/lesson2.md [new file with mode: 0644]
docs/tutorials/lesson3.md [new file with mode: 0644]
face_privacy_filter/_version.py
testing/README.md
web_demo/README.md

index efb5076..27d0431 100644 (file)
--- a/README.md
+++ b/README.md
 # face-privacy-filter
 A model for face detection and suppression.
 
-## 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.
+* [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)
 
-### 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: run_face-privacy-filter_reference.py [-h] [-p PREDICT_PATH] [-i INPUT]
-                                            [-c] [-s] [-f {detect,pixelate}]
-                                            [-a PUSH_ADDRESS] [-d DUMP_MODEL]
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -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
-  -s, --suppress_image  do not create an extra row for a returned image
-  -f {detect,pixelate}, --function {detect,pixelate}
-                        which type of model to generate
-  -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
-                        server address to push the model (e.g.
-                        http://localhost:8887/v2/models)
-  -d DUMP_MODEL, --dump_model DUMP_MODEL
-                        dump model to a pickle directory for local running
-```
-
-
-### Examples
-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 -d model_detect -f detect
-```
-* Dump the `pixelate` model to disk.
-```
-python face_privacy_filter/filter_image.py -d model_pix -f pixelate
-```
-* 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
-```
-
-### 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.
-
-## 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.
-
-# 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))
-
-
-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)
deleted file mode 120000 (symlink)
index 32d46ee883b58d6a383eed06eb98f33aa6530ded..0000000000000000000000000000000000000000
+++ /dev/null
@@ -1 +0,0 @@
-../README.md
\ No newline at end of file
new file mode 100644 (file)
index 0000000000000000000000000000000000000000..18a34907a876d3c0e19f048960cd9c301c4b308f
--- /dev/null
@@ -0,0 +1,60 @@
+# face-privacy-filter
+A model for face detection and suppression.
+
+## 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.
+
+### 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] [-s] [-f {detect,pixelate}]
+                       [-a PUSH_ADDRESS] [-d DUMP_MODEL]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -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
+  -s, --suppress_image  do not create an extra row for a returned image
+  -f {detect,pixelate}, --function {detect,pixelate}
+                        which type of model to generate
+  -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
+                        server address to push the model (e.g.
+                        http://localhost:8887/v2/models)
+  -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.
+
index abf7bde..e361d4c 100644 (file)
@@ -1 +1,18 @@
-# Release Notes
\ No newline at end of file
+# Release Notes
+## 0.2
+### 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 `classify_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/lesson1.md b/docs/tutorials/lesson1.md
new file mode 100644 (file)
index 0000000..243b18a
--- /dev/null
@@ -0,0 +1,67 @@
+# 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 -d model_detect -f detect
+```
+* Dump the `pixelate` model to disk.
+```
+python face_privacy_filter/filter_image.py -d model_pix -f pixelate
+```
+
+
+## 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
+```
+
+
+# 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
new file mode 100644 (file)
index 0000000..1ce2b27
--- /dev/null
@@ -0,0 +1,108 @@
+# 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).
+
+## 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 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"
+```
diff --git a/docs/tutorials/lesson3.md b/docs/tutorials/lesson3.md
new file mode 100644 (file)
index 0000000..044f2c4
--- /dev/null
@@ -0,0 +1,50 @@
+# Web Demo
+This web page sample allows the user to submit an image to
+an image classification and image mood classification 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).
+
+## Example mood classification demo
+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`
+```
+classificationServer: "http://localhost:8884/transform",
+```
+* view the page `face-privacy.html` in a Crome or Firefox browser
+* probabilities will be updated on the right side fo the screen
+* 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 *awe* mood classification
+
+* ![example web application blurring multiple facs](example_running.jpg "Example multi-face blur")
+
+
+# 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))
+
+
+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 5d54d20..a5103e2 100644 (file)
@@ -1,3 +1,3 @@
 # -*- coding: utf-8 -*-
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 MODEL_NAME = 'face_privacy_filter'
index 1120161..06d337f 100644 (file)
@@ -1,89 +1,5 @@
-# web_test
-This directory provides a simple web server for demonstrating a face-privacy filter example.
+# 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.
 
-## Example usage
-This repo provides multiple models that can be created.  Thanks to the
-generic transform i/o specifications, you can run either one or two
-models in composition together.
-
-```
-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
-```
-
-### 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"
-    }
-]
-
-```
-
-## Face Privacy Filtering
-
-* 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"
-```
+Please consult the [tutorial documentation](../docs/tutorials/lesson2.md) for more information.
index e39fc09..a96a9d1 100644 (file)
@@ -1,24 +1,5 @@
-# Face Privacy Example Example
-This web page sample allows the user to submit an image to
-an face detect and process task.
+# web_demo
+This directory provides a simple web page and demo content for
+the image-based classifier demo.
 
-**Image Copyrights May Apply** - the included sample videos may carry
-additional copyrights and are not meant for public resale or consumption.
-
-## Example mood classification demo
-To utilize this demo...
-
-* confirm that your local instance is configured and running
-* download this directory to your local machine
-  * confirm the host port and analysis service URL in the file `face-privacy.js`
-```
-classificationServer: "http://localhost:8884/transform",
-```
-  * alternatively, the parameter can be set from a url argument `url-image`
-* view the page `face-privacy.html` in a Chrome or Firefox browser
-* results will come back from detect and processing steps
-* 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 face detection and blurring.
-
-* ![example web application with face detection and blurring](example_running.jpg "Example web application classifying tigers video")
+Please consult the [tutorial documentation](../docs/tutorials/lesson3.md) for more information.