improve documentation and command line usage 90/2090/1
authorEric Z <ezavesky@research.att.com>
Fri, 15 Jun 2018 19:01:37 +0000 (14:01 -0500)
committerEric Z <ezavesky@research.att.com>
Fri, 15 Jun 2018 19:01:37 +0000 (14:01 -0500)
- organize CLI options via structure, simplify defaults
- update documentation for some simplified usage
- update with environment arguments for documentation

Issue-ID: ACUMOS-943

Change-Id: Ib28c42778966929b52dbd9ccbb204d8ad7d1dc91
Signed-off-by: Eric Z <ezavesky@research.att.com>
docs/face-privacy-filter.md
docs/release-notes.md
docs/tutorials/lesson1.md
face_privacy_filter/_version.py
face_privacy_filter/filter_image.py

index cdf439d..8cc661f 100644 (file)
@@ -50,6 +50,10 @@ or the mirrored [Acumos Github repository](https://github.com/acumos/face-privac
 It utilizes a protobuf javascript library and processes
 input images to detect all faces within an image.
 
 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.
 ## Performance
 As this model wraps a preexisting cascade, no formal testing evaluation
 was performed.  However, experimental usage indicates the following highlights.
@@ -109,7 +113,6 @@ demographics but not recognition) may also be easily employed with this
 system, should the right method arise.
 
 
 system, should the right method arise.
 
 
-
 # Source Installation
 This section is useful for source-based installations and is not generally intended
 for catalog documentation.
 # Source Installation
 This section is useful for source-based installations and is not generally intended
 for catalog documentation.
@@ -123,19 +126,23 @@ 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.
 
 at this time and instead uses a pre-trained face cascade, which is
 included (from OpenCV) in this module.
 
-### Package dependencies
+## 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.
 
 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.
 ```
 ```
-pip install -r requirments.txt
+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
 ```
 
 ```
 
-**Note:** If you are using an [anaconda-based environment](https://anaconda.org),
-you may want to try
-installing these packages [directly](https://docs.anaconda.com/anaconda-repository/user-guide/tasks/pkgs/download-install-pkg).
-to avoid mixing of `pip` and `conda` package stores.
 
 ### Usage
 This package contains runable scripts for command-line evaluation,
 
 ### Usage
 This package contains runable scripts for command-line evaluation,
@@ -144,12 +151,14 @@ uses.   All functionality is encapsulsted in the `filter_image.py`
 script and has the following arguments.
 
 ```
 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]
+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
 
 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')
   -p PREDICT_PATH, --predict_path PREDICT_PATH
                         save detections from model (model must be provided via
                         'dump_model')
@@ -157,12 +166,17 @@ optional arguments:
                         absolute path to input data (image or csv, only during
                         prediction / dump)
   -c, --csv_input       input as CSV format not an image
                         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
   -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 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
 ```
   -d DUMP_MODEL, --dump_model DUMP_MODEL
                         dump model to a pickle directory for local running
 ```
index 3995a46..afa75c5 100644 (file)
 
 # Face Privacy Filter Release Notes
 ## 0.3
 
 # 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.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
index b854c4c..38c6ff2 100644 (file)
@@ -44,6 +44,18 @@ python face_privacy_filter/filter_image.py -f detect  -d model_detect
 python face_privacy_filter/filter_image.py -f pixelate -d model_pix
 ```
 
 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
 
 ## In-place Evaluation
 In-place evaluation **will utilize** a serialized version of the model and load
index d5fad04..7269653 100644 (file)
@@ -1,3 +1,3 @@
 # -*- coding: utf-8 -*-
 # -*- coding: utf-8 -*-
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 MODEL_NAME = 'face_privacy_filter'
 MODEL_NAME = 'face_privacy_filter'
index 2015e31..149f703 100644 (file)
@@ -96,14 +96,16 @@ def main(config={}):
     from face_privacy_filter._version import MODEL_NAME
     import argparse
     parser = argparse.ArgumentParser()
     from face_privacy_filter._version import MODEL_NAME
     import argparse
     parser = argparse.ArgumentParser()
-    parser.add_argument('-p', '--predict_path', type=str, default='', help="save detections from model (model must be provided via 'dump_model')")
-    parser.add_argument('-i', '--input', type=str, default='', help='absolute path to input data (image or csv, only during prediction / dump)')
-    parser.add_argument('-c', '--csv_input', dest='csv_input', action='store_true', default=False, help='input as CSV format not an image')
-    parser.add_argument('-s', '--suppress_image', dest='suppress_image', action='store_true', default=False, help='do not create an extra row for a returned image')
-    parser.add_argument('-f', '--function', type=str, default='detect', help='which type of model to generate', choices=['detect', 'pixelate'])
-    parser.add_argument('-a', '--push_address', help='server address to push the model (e.g. http://localhost:8887/v2/models)', default=os.getenv('ACUMOS_PUSH', ""))
-    parser.add_argument('-A', '--auth_address', help='server address for login and push of the model (e.g. http://localhost:8887/v2/auth)', default=os.getenv('ACUMOS_AUTH', ""))
-    parser.add_argument('-d', '--dump_model', help='dump model to a pickle directory for local running', default='')
+    submain = parser.add_argument_group('main execution and evaluation functionality')
+    submain.add_argument('-p', '--predict_path', type=str, default='', help="save detections from model (model must be provided via 'dump_model')")
+    submain.add_argument('-i', '--input', type=str, default='', help='absolute path to input data (image or csv, only during prediction / dump)')
+    submain.add_argument('-c', '--csv_input', dest='csv_input', action='store_true', default=False, help='input as CSV format not an image')
+    submain.add_argument('-f', '--function', type=str, default='detect', help='which type of model to generate', choices=['detect', 'pixelate'])
+    submain.add_argument('-s', '--suppress_image', dest='suppress_image', action='store_true', default=False, help='do not create an extra row for a returned image')
+    subopts = parser.add_argument_group('model creation and configuration options')
+    subopts.add_argument('-a', '--push_address', help='server address to push the model (e.g. http://localhost:8887/v2/models)', default=os.getenv('ACUMOS_PUSH', ""))
+    subopts.add_argument('-A', '--auth_address', help='server address for login and push of the model (e.g. http://localhost:8887/v2/auth)', default=os.getenv('ACUMOS_AUTH', ""))
+    subopts.add_argument('-d', '--dump_model', help='dump model to a pickle directory for local running', default='')
     config.update(vars(parser.parse_args()))     # pargs, unparsed = parser.parse_known_args()
 
     if not config['predict_path']:
     config.update(vars(parser.parse_args()))     # pargs, unparsed = parser.parse_known_args()
 
     if not config['predict_path']:
@@ -126,7 +128,7 @@ def main(config={}):
 
     # formulate the pipeline to be used
     model_name = MODEL_NAME + "_" + config['function']
 
     # formulate the pipeline to be used
     model_name = MODEL_NAME + "_" + config['function']
-    if config['push_address']:
+    if config['push_address'] and config['auth_address']:
         from acumos.session import AcumosSession
         print("Pushing new model to '{:}'...".format(config['push_address']))
         session = AcumosSession(push_api=config['push_address'], auth_api=config['auth_address'])
         from acumos.session import AcumosSession
         print("Pushing new model to '{:}'...".format(config['push_address']))
         session = AcumosSession(push_api=config['push_address'], auth_api=config['auth_address'])