documentation (go to RST), prune deprecation
[face-privacy-filter.git] / docs / tutorials / demonstration.rst
1 .. ===============LICENSE_START=======================================================
2 .. Acumos CC-BY-4.0
3 .. ===================================================================================
4 .. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
5 .. ===================================================================================
6 .. This Acumos documentation file is distributed by AT&T and Tech Mahindra
7 .. under the Creative Commons Attribution 4.0 International License (the "License");
8 .. you may not use this file except in compliance with the License.
9 .. You may obtain a copy of the License at
10 ..
11 ..      http://creativecommons.org/licenses/by/4.0
12 ..
13 .. This file is distributed on an "AS IS" BASIS,
14 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 .. See the License for the specific language governing permissions and
16 .. limitations under the License.
17 .. ===============LICENSE_END=========================================================
18
19 .. _demonstration_face-privacy:
20
21 =========================================
22 Demonstrations: Tutorial for Face Privacy
23 =========================================
24
25 Web Demo
26 ========
27
28 This web page sample allows the user to submit an image to a face
29 detection and a face pixelation service in serial progression.
30
31 * ***Image Copyrights May Apply*** - the included sample videos may
32 carry additional copyright restrictions and are not meant for public resale or
33 consumption.
34
35 Browser Interaction
36 ===================
37
38 Most browsers should have no CORS or other cross-domain objections to
39 dropping the file ``face-privacy.html`` into the browser and accesing a
40 locally hosted server API, as configured in :ref:`deployment_face-privacy`.
41
42
43 Open-source hosted run
44 -----------------------
45
46 Utilizing the generous `htmlpreview function <https://htmlpreview.github.io/>`__
47 available on GitHub, you
48 can also experiment with the respository-based web resource. This
49 resource will proxy the repository ``web_demo`` directory into a live
50 resource.
51
52 Navigate to the
53 `default webhost page <http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html>`__
54 and confirm that the resource load properly. The image at the bottom of
55 this guide is a good reference for correct page loading and display.
56
57 After confirming correct page load, simply replace the value in the
58 ``Transform URL`` field to point at your deployed instance. For example,
59 if you've created a dumped model locally, it might be a localhost port.
60
61
62 Local webserver run
63 -------------------
64
65 If you want to run the test locally, you can use the built-in python
66 webserver with the line below while working in the ``web_demo``
67 directory (assuming you're running python3).
68
69 ::
70
71     python -m http.server 5000
72
73 Afterwards, just point your browser at
74 ``http://localhost:5000/face-privacy.html``.
75
76
77 Example face privacy demo (docker and protobuf)
78 ===============================================
79
80 To customize this demo, one should change either the included javascript
81 or simply update the primary classification URL on the page itself
82 during runtime. This demo utilizes the
83 `javascript protobuf library <https://github.com/dcodeIO/ProtoBuf.js/>`__ to encode
84 parameters into proto binaries in the browser.
85
86 ***NOTE*** One version of the face model's protobuf schema is
87 included with this web page, but it may change over time. If you receive
88 encoding errors or unexpected results, please verify that your target
89 model and this web page are using the same ``.proto`` file.
90
91 -  confirm that your target docker instance is configured and running
92 -  download this directory to your local machine
93
94    -  confirm the host port and classification service URL in the file
95       ``face-privacy.js``
96    -  modify the ``protoDefault`` setting to be 1
97
98       ::
99
100           urlDefault: "http://localhost:8884/transform",
101
102 -  view the page ``face-privacy.html`` in a Crome or Firefox browser
103 -  you can switch between a few sample images or upload your own by
104    clicking on the buttons below the main image window
105
106
107 Special decoding example
108 ------------------------
109
110 In ``protobuf`` mode, you can also download a binary, encoded version of
111 the last image that was sent to the remote service. When available, the
112 Download Encoded Message button will be enabled and a binary file will
113 be generated in the browser.
114
115 ::
116
117     protoc --decode=HipTviKTkIkcmyuMCIAIDkeOOQQYyJne.Image model.pixelate.proto < protobuf.bin
118
119 **NOTE** The specific package name may have changed since the time of
120 writing, so be sure to check the contents of the current ``.proto``
121 file.
122
123 Example face privacy demo (HTTP parameters)
124 -------------------------------------------
125
126 To customize this demo, one should change either the included javascript
127 or simply update the primary classification URL on the page itself
128 during runtime.
129
130 -  confirm that your local instance is configured and running
131 -  download this directory to your local machine
132
133    -  confirm the host port and classification service URL in the file
134       ``face-privacy.js``
135    -  modify the ``protoDefault`` setting to be 0
136
137       ::
138
139           urlDefault: "http://localhost:8884/transform",
140
141 -  view the page ``face-privacy.html`` in a Crome or Firefox browser
142 -  you can switch between a few sample images or upload your own by
143    clicking on the buttons below the main image window
144
145 Example Interface
146 =================
147
148 An instance should first be built and downloaded and then launched
149 locally. Afterwards, the sample application found in the
150 ``web_demo`` directory uses a ``localhost`` service to classify and
151 visualize the results of image classification.
152
153 -  Commercial example (`youtube source <https://www.youtube.com/watch?v=34KfCNapnUg>`__)
154 -  Reunion face sample  `flickr source <https://flic.kr/p/bEgYbs>`__)
155 -  family face example (`pexel source <https://www.pexels.com/photo/adult-affection-beautiful-beauty-265764/>`__)
156 -  DiCaprio celebrity face sample (`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>`__)
157 -  Schwarzenegger celebrity (`wikimedia source <https://upload.wikimedia.org/wikipedia/commons/thumb/0/0f/A._Schwarzenegger.jpg/220px-A._Schwarzenegger.jpg>`__)
158 -  DeGeneres celebrity face sample (`wikipedia source <https://en.wikipedia.org/wiki/Ellen_DeGeneres#/media/File:Ellen_DeGeneres-2009.jpg>`__)
159
160
161 .. image:: example_running.jpg
162     :alt: example web application with *awe* mood
163     :width: 200
164
165