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)