docs/face-privacy-filter.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 ### Package dependencies
  14 Package dependencies for the core code and testing have been flattened into a
  15 single file for convenience. Instead of installing this package into your
  16 your local environment, execute the command below.
  17
  18 ```
  19 pip install -r requirments.txt
  20 ```
  21
  22 **Note:** If you are using an [anaconda-based environment](https://anaconda.org),
  23 you may want to try
  24 installing these packages [directly](https://docs.anaconda.com/anaconda-repository/user-guide/tasks/pkgs/download-install-pkg).
  25 to avoid mixing of `pip` and `conda` package stores.
  26
  27 ### Usage
  28 This package contains runable scripts for command-line evaluation,
  29 packaging of a model (both dump and posting), and simple web-test
  30 uses.   All functionality is encapsulsted in the `filter_image.py`
  31 script and has the following arguments.
  32
  33 ```
  34 usage: filter_image.py [-h] [-p PREDICT_PATH] [-i INPUT]
  35                        [-c] [-s] [-f {detect,pixelate}]
  36                        [-a PUSH_ADDRESS] [-d DUMP_MODEL]
  37
  38 optional arguments:
  39   -h, --help            show this help message and exit
  40   -p PREDICT_PATH, --predict_path PREDICT_PATH
  41                         save detections from model (model must be provided via
  42                         'dump_model')
  43   -i INPUT, --input INPUT
  44                         absolute path to input data (image or csv, only during
  45                         prediction / dump)
  46   -c, --csv_input       input as CSV format not an image
  47   -s, --suppress_image  do not create an extra row for a returned image
  48   -f {detect,pixelate}, --function {detect,pixelate}
  49                         which type of model to generate
  50   -a PUSH_ADDRESS, --push_address PUSH_ADDRESS
  51                         server address to push the model (e.g.
  52                         http://localhost:8887/v2/models)
  53   -d DUMP_MODEL, --dump_model DUMP_MODEL
  54                         dump model to a pickle directory for local running
  55 ```
  56
  57
  58
  59 # Example Usages
  60 Please consult the [tutorials](tutorials) dirctory for usage examples
  61 including an in-place [web page demonstration](tutorials/lesson3.md).
  62
  63 ## Face-based Use Cases
  64 This project includes a number of face-based use cases including raw
  65 detection, blurring, and other image-based modifications based on
  66 detected image regions.
  67
  68 * **Face Detection Use-case** - This source code creates and pushes a model that processes
  69 incoming images and outputs detected faces.
  70
  71 # Release Notes
  72 The [release notes](release-notes.md) catalog additions and modifications
  73 over various version changes.
  74