8ae2b6dc71bfb35eb3af144e9b679789f340ad6c
[face-privacy-filter.git] / docs / tutorials / lesson3.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 # Web Demo
22 This web page sample allows the user to submit an image to
23 a face detection and a face pixelation service
24 in serial progression.
25
26 ** Image Copyrights May Apply ** - the included sample videos may carry
27 additional copyrights and are not meant for public resale or consumption.
28
29 ## Browser Interaction
30 Most browsers should have no
31 CORS or other cross-domain objections to dropping the file `face-privacy.html`
32 into the browser and accesing a locally hosted server API, as configured
33 in [the previous tutorial](lesson2.md).
34
35 ### Open-source hosted run
36 Utilizing the generous [htmlpreview function](https://htmlpreview.github.io/) available on
37 GitHub, you can also experiment with the respository-based web resource.  This resource
38 will proxy the repository `web_demo` directory into a live resource.
39
40 Navigate to the [default webhost page](http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html)
41 and confirm that the resource load properly.  The image at the bottom of this guide
42 is a good reference for correct page loading and display.
43
44 After confirming correct page load, simply replace the value in the `Transform URL`
45 field to point at your deployed instance.  For example, if you've created a
46 dumped model locally, it might be a localhost port.
47
48
49 ### Local webserver run
50 If you want to run the test locally, you can use the built-in python
51 webserver with the line below while working in the `web_demo` directory
52 (assuming you're running python3).
53 ```
54 python -m http.server 5000
55 ```
56
57 Afterwards, just point your browser at `http://localhost:5000/face-privacy.html`.
58
59 ## Example face privacy demo (docker and protobuf)
60 To customize this demo, one should change either the included javascript
61 or simply update the primary classification URL on the page itself during runtime.
62 This demo utilizes the [javascript protobuf library](https://github.com/dcodeIO/ProtoBuf.js/)
63 to encode parameters into proto binaries in the browser.
64
65 ** NOTE ** One version of the face model's protobuf schema is included with
66 this web page, but it may change over time.  If you receive encoding errors
67 or unexpected results, please verify that your target model and this web page
68 are using the same `.proto` file.
69
70 * confirm that your target docker instance is configured and running
71 * download this directory to your local machine
72     * confirm the host port and classification service URL in the file `face-privacy.js`
73     * modify the `protoDefault` setting to be 1
74 ```
75 urlDefault: "http://localhost:8884/transform",
76 ```
77 * view the page `face-privacy.html` in a Crome or Firefox browser
78 * you can switch between a few sample images or upload your own by clicking on the buttons below the main image window
79
80 Example web application with blur process.
81
82 * ![example web application blurring multiple faces](example_running.jpg "Example multi-face blur")
83
84 ### Special decoding example
85 In `protobuf` mode, you can also download a binary, encoded version of the last
86 image that was sent to the remote service.  When available, the <strong>Download Encoded Message</strong>
87 button will be enabled and a binary file will be generated in the browser.
88
89 ```
90 protoc --decode=HipTviKTkIkcmyuMCIAIDkeOOQQYyJne.Image model.pixelate.proto < protobuf.bin
91 ```
92
93 **NOTE** The specific package name may have changed since the time of writing,
94 so be sure to check the contents of the current `.proto` file.
95
96
97 ## Example face privacy demo (HTTP parameters)
98 To customize this demo, one should change either the included javascript
99 or simply update the primary classification URL on the page itself during runtime.
100
101 * confirm that your local instance is configured and running
102 * download this directory to your local machine
103     * confirm the host port and classification service URL in the file `face-privacy.js`
104     * modify the `protoDefault` setting to be 0
105 ```
106 urlDefault: "http://localhost:8884/transform",
107 ```
108 * view the page `face-privacy.html` in a Crome or Firefox browser
109 * you can switch between a few sample images or upload your own by clicking on the buttons below the main image window
110
111
112 # Example Interface
113 An instance should first be built and downloaded and then
114 launched locally.  Afterwards, the sample application found in
115 [web_demo](web_demo) uses a `localhost` service to classify
116 and visualize the results of image classification.
117
118 * [Commercial example](../../web_demo/images/commercial.jpg) ([youtube source](https://www.youtube.com/watch?v=34KfCNapnUg))
119 * [Reunion face sample](../../web_demo/images/face_reunion.jpg) ([flickr source](https://flic.kr/p/bEgYbs))
120 * [family face example](../../web_demo/images/face_family.jpg) ([pexel source](https://www.pexels.com/photo/adult-affection-beautiful-beauty-265764/))
121 * [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))
122 * [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))
123 * [DeGeneres celebrity face sample](../../web_demo/images/face_DeGeneres.jpg) ([wikipedia source](https://en.wikipedia.org/wiki/Ellen_DeGeneres#/media/File:Ellen_DeGeneres-2009.jpg))
124
125
126 before  | after
127 ------- | -------
128 ![raw commercial](../../web_demo/images/commercial.jpg)  | ![pixelated commercial](../../web_demo/images/commercial_pixelate.jpg)
129 ![raw face](../../web_demo/images/face_family.jpg)  | ![pixelated commercial](../../web_demo/images/face_family_pixelate.jpg)