README.md

   1 # face-privacy-filter
   2 A model for face detection and suppression.
   3
   4 ## Image Analysis for Face-based Privacy Filtering
   5 This source code creates and pushes a model into Cognita that processes
   6 incoming images and outputs a detected faces as well as the original image
   7 input (if configured that way).  The model uses a [python interface](https://pypi.python.org/pypi/opencv-python)
   8 to the [OpenCV library](https://opencv.org/) to detect faces and perform
   9 subsequent image processing.  This module does not support training
  10 at this time and instead uses a pre-trained face cascade, which is
  11 included (from OpenCV) in this module.
  12
  13 ### Usage
  14 This package contains runable scripts for command-line evaluation,
  15 packaging of a model (both dump and posting), and simple web-test
  16 uses.   All functionality is encapsulsted in the `filter_image.py`
  17 script and has the following arguments.
  18
  19 ```
  20 usage: run_face-privacy-filter_reference.py [-h] [-p PREDICT_PATH] [-i INPUT]
  21                                             [-s] [-a PUSH_ADDRESS]
  22                                             [-d DUMP_MODEL]
  23
  24 optional arguments:
  25   -h, --help            show this help message and exit
  26   -p PREDICT_PATH, --predict_path PREDICT_PATH
  27                         save detections from model (model must be provided via
  28                         'dump_model')
  29   -i INPUT, --input INPUT
  30                         absolute path to input image (only during prediction /
  31                         dump)
  32   -s, --suppress_image  do not create an extra row for a returned image
  33   -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
  34                         server address to push the model (e.g.
  35                         http://localhost:8887/v2/models)
  36   -d DUMP_MODEL, --dump_model DUMP_MODEL
  37                         dump model to a pickle directory for local running
  38 ```
  39
  40
  41 ### Examples
  42 Example for dumping the `detect` model to disk.
  43 ```
  44 ./bin/run_local.sh -d model
  45 ```
  46
  47
  48 ## Face-based Use Cases
  49 This project includes a number of face-based use cases including raw
  50 detection, blurring, and other image-based modifications based on
  51 detected image regions.
  52
  53 * **Face Detection Use-case** - This source code creates and pushes a model that processes
  54 incoming images and outputs detected faces.
  55
  56 # Example Interface
  57 An instance should first be built and downloaded and then
  58 launched locally.  Afterwards, the sample application found in
  59 [web_demo](web_demo) uses a `localhost` service to classify
  60 and visualize the results of image classification.
  61
  62 * [DiCaprio celebrity face sample](web_demo/images/face_DiCaprio.jpg) [wikimedia source](https://en.wikipedia.org/wiki/Celebrity#/media/File:Leonardo_DiCaprio_visited_Goddard_Saturday_to_discuss_Earth_science_with_Piers_Sellers_(26105091624)_cropped.jpg)
  63 * [Schwarzenegger celebrity face sample](web_demo/images/face_Schwarzenegger.jpg) [wikimedia source](https://upload.wikimedia.org/wikipedia/commons/thumb/0/0f/A._Schwarzenegger.jpg/220px-A._Schwarzenegger.jpg)