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