improve documentation and command line usage
[face-privacy-filter.git] / docs / face-privacy-filter.md
1 <!---
2 .. ===============LICENSE_START=======================================================
3 .. Acumos CC-BY-4.0
4 .. ===================================================================================
5 .. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
6 .. ===================================================================================
7 .. This Acumos documentation file is distributed by AT&T and Tech Mahindra
8 .. under the Creative Commons Attribution 4.0 International License (the "License");
9 .. you may not use this file except in compliance with the License.
10 .. You may obtain a copy of the License at
11 ..
12 ..      http://creativecommons.org/licenses/by/4.0
13 ..
14 .. This file is distributed on an "AS IS" BASIS,
15 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 .. See the License for the specific language governing permissions and
17 .. limitations under the License.
18 .. ===============LICENSE_END=========================================================
19 -->
20
21 # Face Privacy Filter Guide
22 This model contains the capability to generate two submodels:
23 one for face detection and oen for face suppression through pixelation.
24
25 # Face Detection Model Guide
26 A model example for face detection from images within Acumos.
27
28 ## Background
29 This model analyzes static images to detect frontal faces.  It utilizes a
30 frontal face cascade from the
31 [OpenCV](https://opencv.org/) image processing library.
32 Model load time is optimized by creating and maintaining the fixed cascade
33 in memory while operating.  Demonstrating the capability of custom classes
34 and requisite member variables, the cascade is serialized with the model as
35 a string asset which is deserialized and loaded from disk upon startup.
36
37 ## Usage
38 Input to the model is an array of one or more tuples of image binary data
39 and a binary mime type.  The position of the image within the array is utilized
40 in the output signature as a zero-based index.  For example if three images
41 were sent, the output probabilities would have 0, 1, and 2 as index values.
42 The output from this model is a repeated array of detected regions for each
43 face in each input image.  So that image data can be cascaded to other models,
44 the original image and mime type are also embedded with the special
45 region code `-1` within the output.
46
47 A web demo is included with the source code, available via the
48 [Acumos Gerrit repository](https://gerrit.acumos.org/r/gitweb?p=face-privacy-filter.git;a=summary)
49 or the mirrored [Acumos Github repository](https://github.com/acumos/face-privacy-filter).
50 It utilizes a protobuf javascript library and processes
51 input images to detect all faces within an image.
52
53 Once deployed, you can quickly jump to the
54 [default webhost page](http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html)
55 and point to your model for a demo; see [tutorial lesson 3](tutorials/lesson3.md) for more details.
56
57 ## Performance
58 As this model wraps a preexisting cascade, no formal testing evaluation
59 was performed.  However, experimental usage indicates the following highlights.
60
61 * Faces that are too small can easily be missed.
62 * Frontal faces perform best, with some tolerance of about 5-10 degrees off-plane rotation.
63 * Detection is fairly sensitive to rotation in plane, so try not to let subject faces rotate more than 15 degrees.
64 * Dark or low contrast images generally do not perform well for detection.
65
66 ## More Information
67 As this model uses a generic cascade from OpenCV, readers can easily
68 substituted or update those models with no change in API endpoint required.
69 Additionally, secondary verification methods using pixel validation (e.g.
70 sub-part verification, symmetry tests, or more advanced parts-based
71 verifications) may dramatically improve the false alarm rate, although
72 the current model was tuned for precision (instead of recall) already.
73
74
75
76 # Face Pixelation Model Guide
77 A model example to anonymize faces from images via pixelation within Acumos.
78
79 ## Background
80 This model accepts detected faces and their source image and produces
81 pixelated image results.  It utilizes simple image manipulation methods
82 from the [OpenCV](https://opencv.org/) image processing library.
83 This model is a demonstration of a
84 transform operation: there is neither state nor static model data
85 utilized and all data comes from the upstream input.
86
87
88 ## Usage
89 Input to the model is an array of one or more tuples of detected face regions
90 as well as the original image binary data and a binary mime type.  The row or
91 sample containing the original image is specially marked by a region code
92 of ‘-1’.  The output from this model is an array of images (one for each
93 unique image input) with the detected face regions blurred via pixelation.
94
95 A web demo is included with the source code, available via the
96 [Acumos Gerrit repository](https://gerrit.acumos.org/r/gitweb?p=face-privacy-filter.git;a=summary).
97 It utilizes a protobuf javascript library and processes
98 input images to detect all faces within an image.
99
100 ## Performance
101 As this model is a data transform example that flattens detected image regions into images.
102
103 * Faces not included in the detected regions are ignored.
104 * Faces whose images do not exist in the input (e.g. region and image indices
105   are provided, but no original image) are ignored.
106 * The mime type for the output image is constructed to mimic the input image and mime type.
107
108 ## More Information
109 This model uses processing methods from OpenCV, so any number of additional
110 privacy methods could be employed, like blurring, substitution, etc. More
111 advanced techniques that still allow some information processing (e.g.
112 demographics but not recognition) may also be easily employed with this
113 system, should the right method arise.
114
115
116 # Source Installation
117 This section is useful for source-based installations and is not generally intended
118 for catalog documentation.
119
120 ## Image Analysis for Face-based Privacy Filtering
121 This source code creates and pushes a model into Acumos that processes
122 incoming images and outputs a detected faces as well as the original image
123 input (if configured that way).  The model uses a [python interface](https://pypi.python.org/pypi/opencv-python)
124 to the [OpenCV library](https://opencv.org/) to detect faces and perform
125 subsequent image processing.  This module does not support training
126 at this time and instead uses a pre-trained face cascade, which is
127 included (from OpenCV) in this module.
128
129 ## Package dependencies
130 Package dependencies for the core code and testing have been flattened into a
131 single file for convenience. Instead of installing this package into your
132 your local environment, execute the command below.
133
134 **Note:** If you are using an [anaconda-based environment](https://anaconda.org),
135 you may want to try installing with conda first and then pip.
136 to mixing mixing package stores.
137 ```
138 conda install --yes --file requirements.txt  # suggested first step if you're using conda
139 ```
140
141 Installation of the package requirements for a new environment.
142 ```
143 pip install -r requirements.txt
144 ```
145
146
147 ### Usage
148 This package contains runable scripts for command-line evaluation,
149 packaging of a model (both dump and posting), and simple web-test
150 uses.   All functionality is encapsulsted in the `filter_image.py`
151 script and has the following arguments.
152
153 ```
154 usage: filter_image.py [-h] [-p PREDICT_PATH] [-i INPUT] [-c]
155                        [-f {detect,pixelate}] [-s] [-a PUSH_ADDRESS]
156                        [-A AUTH_ADDRESS] [-d DUMP_MODEL]
157
158 optional arguments:
159   -h, --help            show this help message and exit
160
161 main execution and evaluation functionality:
162   -p PREDICT_PATH, --predict_path PREDICT_PATH
163                         save detections from model (model must be provided via
164                         'dump_model')
165   -i INPUT, --input INPUT
166                         absolute path to input data (image or csv, only during
167                         prediction / dump)
168   -c, --csv_input       input as CSV format not an image
169   -f {detect,pixelate}, --function {detect,pixelate}
170                         which type of model to generate
171   -s, --suppress_image  do not create an extra row for a returned image
172
173 model creation and configuration options:
174   -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
175                         server address to push the model (e.g.
176                         http://localhost:8887/v2/models)
177   -A AUTH_ADDRESS, --auth_address AUTH_ADDRESS
178                         server address for login and push of the model (e.g.
179                         http://localhost:8887/v2/auth)
180   -d DUMP_MODEL, --dump_model DUMP_MODEL
181                         dump model to a pickle directory for local running
182 ```
183
184
185
186 # Example Usages
187 Please consult the [tutorials](tutorials) dirctory for usage examples
188 including an in-place [web page demonstration](tutorials/lesson3.md).
189
190 ## Face-based Use Cases
191 This project includes a number of face-based use cases including raw
192 detection, blurring, and other image-based modifications based on
193 detected image regions.
194
195 * **Face Detection Use-case** - This source code creates and pushes a model that processes
196 incoming images and outputs detected faces.
197
198 # Release Notes
199 The [release notes](release-notes.md) catalog additions and modifications
200 over various version changes.
201
202 # Metadata Examples
203 * [example detect catalog image](catalog_image_detect.png) - [url source](https://flic.kr/p/xqw25C)
204 * [example blur catalog image](catalog_image_blur.png)  - [url source](https://flic.kr/p/bEgYbs)