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 Acumos 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                                             [-c] [-s] [-f {detect,pixelate}]
  22                                             [-a PUSH_ADDRESS] [-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 data (image or csv, only during
  31                         prediction / dump)
  32   -c, --csv_input       input as CSV format not an image
  33   -s, --suppress_image  do not create an extra row for a returned image
  34   -f {detect,pixelate}, --function {detect,pixelate}
  35                         which type of model to generate
  36   -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
  37                         server address to push the model (e.g.
  38                         http://localhost:8887/v2/models)
  39   -d DUMP_MODEL, --dump_model DUMP_MODEL
  40                         dump model to a pickle directory for local running
  41 ```
  42
  43
  44 ### Examples
  45 This single repo has a number of different models that can be
  46 composed together for operation.
  47
  48 * Dump the `detect` model to disk.
  49 ```
  50 ./bin/run_local.sh -d model_detect -f detect
  51 ```
  52 * Dump the `pixelate` model to disk.
  53 ```
  54 ./bin/run_local.sh -d model_pix -f pixelate
  55 ```
  56 * Evaluate the `detect` model from disk and a previously produced detect object
  57 ```
  58 ./bin/run_local.sh -d model_detect -p output.csv -i web_demo/images/face_DiCaprio.jpg
  59 ```
  60 * Example for evaluating the `pixelate` model from disk and a previously produced detect object
  61 ```
  62 ./bin/run_local.sh -d model_pix -i detect.csv -p output.jpg --csv_input
  63 ```
  64
  65 ### Installation Troubleshoting
  66 Using some environment-based versions of python (e.g. conda),
  67 one problem seemed to come up with the installation of the dependent
  68 package `opencv-python`.  If you launch your python instance and see
  69 an error like the one below, keep reading.
  70
  71 ```
  72 >>> import cv2
  73 Traceback (most recent call last):
  74   File "<stdin>", line 1, in <module>
  75 ImportError: dynamic module does not define module export function (PyInit_cv2)
  76 >>>
  77 ```
  78
  79 This is likely because your `PYTHONPATH` is not correctly configured to
  80 point to the additional installed libraries.
  81
  82 * From the [simple example here](https://stackoverflow.com/a/42160595)
  83 you can check your environment with `echo $PYTHONPATH`.  If it does not
  84 contain the directory that you installed to, then you have a problem.
  85 * Please check your installation by running `python -v -v; import cv2` and checking
  86 that the last loaded library is in the right location.
  87 * In some instances, this variable needed to be blank to work properly (i.e.
  88 `export PYTHONPATH=`) run at some time during start up.
  89
  90 ## Face-based Use Cases
  91 This project includes a number of face-based use cases including raw
  92 detection, blurring, and other image-based modifications based on
  93 detected image regions.
  94
  95 * **Face Detection Use-case** - This source code creates and pushes a model that processes
  96 incoming images and outputs detected faces.
  97
  98 # Example Interface
  99 An instance should first be built and downloaded and then
 100 launched locally.  Afterwards, the sample application found in
 101 [web_demo](web_demo) uses a `localhost` service to classify
 102 and visualize the results of image classification.
 103
 104 * [Commercial example](web_demo/images/commercial.jpg) ([youtube source](https://www.youtube.com/watch?v=34KfCNapnUg))
 105 * [Reunion face sample](web_demo/images/face_reunion.jpg) ([flickr source](https://flic.kr/p/bEgYbs))
 106 * [family face example](web_demo/images/face_family.jpg) ([pexel source](https://www.pexels.com/photo/adult-affection-beautiful-beauty-265764/))
 107 * [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))
 108 * [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))
 109
 110
 111 before  | after
 112 ------- | -------
 113 ![raw commercial](web_demo/images/commercial.jpg)  | ![pixelated commercial](web_demo/images/commercial_pixelate.jpg)
 114 ![raw face](web_demo/images/face_family.jpg)  | ![pixelated commercial](web_demo/images/face_family_pixelate.jpg)