- scap the fancier stuff because bitbucket
[face-privacy-filter.git] / 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                                             [-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 -i image.jpg -p predict.csv
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
66
67 ## Face-based Use Cases
68 This project includes a number of face-based use cases including raw
69 detection, blurring, and other image-based modifications based on
70 detected image regions.
71
72 * **Face Detection Use-case** - This source code creates and pushes a model that processes
73 incoming images and outputs detected faces.
74
75 # Example Interface
76 An instance should first be built and downloaded and then
77 launched locally.  Afterwards, the sample application found in 
78 [web_demo](web_demo) uses a `localhost` service to classify
79 and visualize the results of image classification.
80
81 * [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))
82 * [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))
83 * [Commercial example](web_demo/images/commercial.jpg) ([youtube source](https://www.youtube.com/watch?v=34KfCNapnUg))
84
85
86 before  | after
87 ------- | -------
88 ![raw commercial](web_demo/images/commercial.jpg)  | ![pixelated commercial](web_demo/images/commercial_pixelate.jpg)
89 ![raw face](web_demo/images/face_DiCaprio.jpg)  | ![pixelated commercial](web_demo/images/face_DiCaprio_pixelate.jpg)