Update doc titles for display
[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 A model for face detection and suppression.
23
24 ## Image Analysis for Face-based Privacy Filtering
25 This source code creates and pushes a model into Acumos that processes
26 incoming images and outputs a detected faces as well as the original image
27 input (if configured that way).  The model uses a [python interface](https://pypi.python.org/pypi/opencv-python)
28 to the [OpenCV library](https://opencv.org/) to detect faces and perform
29 subsequent image processing.  This module does not support training
30 at this time and instead uses a pre-trained face cascade, which is
31 included (from OpenCV) in this module.
32
33 ### Package dependencies
34 Package dependencies for the core code and testing have been flattened into a
35 single file for convenience. Instead of installing this package into your 
36 your local environment, execute the command below.
37
38 ```
39 pip install -r requirments.txt
40 ```
41
42 **Note:** If you are using an [anaconda-based environment](https://anaconda.org), 
43 you may want to try 
44 installing these packages [directly](https://docs.anaconda.com/anaconda-repository/user-guide/tasks/pkgs/download-install-pkg).
45 to avoid mixing of `pip` and `conda` package stores. 
46
47 ### Usage
48 This package contains runable scripts for command-line evaluation,
49 packaging of a model (both dump and posting), and simple web-test
50 uses.   All functionality is encapsulsted in the `filter_image.py`
51 script and has the following arguments.
52
53 ```
54 usage: filter_image.py [-h] [-p PREDICT_PATH] [-i INPUT]
55                        [-c] [-s] [-f {detect,pixelate}]
56                        [-a PUSH_ADDRESS] [-d DUMP_MODEL]
57
58 optional arguments:
59   -h, --help            show this help message and exit
60   -p PREDICT_PATH, --predict_path PREDICT_PATH
61                         save detections from model (model must be provided via
62                         'dump_model')
63   -i INPUT, --input INPUT
64                         absolute path to input data (image or csv, only during
65                         prediction / dump)
66   -c, --csv_input       input as CSV format not an image
67   -s, --suppress_image  do not create an extra row for a returned image
68   -f {detect,pixelate}, --function {detect,pixelate}
69                         which type of model to generate
70   -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
71                         server address to push the model (e.g.
72                         http://localhost:8887/v2/models)
73   -d DUMP_MODEL, --dump_model DUMP_MODEL
74                         dump model to a pickle directory for local running
75 ```
76
77
78
79 # Example Usages
80 Please consult the [tutorials](tutorials) dirctory for usage examples
81 including an in-place [web page demonstration](tutorials/lesson3.md).
82
83 ## Face-based Use Cases
84 This project includes a number of face-based use cases including raw
85 detection, blurring, and other image-based modifications based on
86 detected image regions.
87
88 * **Face Detection Use-case** - This source code creates and pushes a model that processes
89 incoming images and outputs detected faces.
90
91 # Release Notes
92 The [release notes](release-notes.md) catalog additions and modifications
93 over various version changes.
94
95 # Metadata Examples
96 * [example detect catalog image](catalog_image_detect.png) - [url source](https://flic.kr/p/xqw25C)
97 * [example blur catalog image](catalog_image_blur.png)  - [url source](https://flic.kr/p/bEgYbs)