License text issue in image specific model repos
[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 Browser Interaction
32 ===================
33
34 Most browsers should have no CORS or other cross-domain objections to
35 dropping the file ``face-privacy.html`` into the browser and accesing a
36 locally hosted server API, as configured in :ref:`deployment_face-privacy`.
37
38
39 Open-source hosted run
40 -----------------------
41
42 Utilizing the generous `htmlpreview function <https://htmlpreview.github.io/>`__
43 available on GitHub, you
44 can also experiment with the respository-based web resource. This
45 resource will proxy the repository ``web_demo`` directory into a live
46 resource.
47
48 Navigate to the
49 `default webhost page <http://htmlpreview.github.io/?https://github.com/acumos/face-privacy-filter/blob/master/web_demo/face-privacy.html>`__
50 and confirm that the resource load properly. The image at the bottom of
51 this guide is a good reference for correct page loading and display.
52
53 After confirming correct page load, simply replace the value in the
54 ``Transform URL`` field to point at your deployed instance. For example,
55 if you've created a dumped model locally, it might be a localhost port.
56
57
58 Local webserver run
59 -------------------
60
61 If you want to run the test locally, you can use a supplied python
62 webserver with the line below while working in the ``web_demo``
63 directory (assuming you're running python3).
64
65 ::
66
67     python simple-cors-http-server-python3.py 5000
68
69 Afterwards, just point your browser at
70 ``http://localhost:5000/face-privacy.html``.
71
72
73 Usage of protobuf binaries for testing
74 --------------------------------------
75 Binary (protobuf encoded) data can be downloaded from the web page or directly with curl.
76 Two demonstration binaries have been included in the source repository for testing.
77
78 - ``protobuf.Image.bin`` - a protobuf-encoded image of Ellen DeGeneres
79 - ``protobuf.RegionDetectionSet.bin`` - a protobuf-encoded region set from the reunion example
80
81 Within the webpage demo, simply select the correct protobuf method and then drag and
82 drop the binary file into the ``Protobuf Payload Input`` file uploader.  It will be
83 immediately uploaded through javascript to your specified ``Transform Url``.
84
85
86 Example face privacy demo (docker and protobuf)
87 ===============================================
88
89 To customize this demo, one should change either the included javascript
90 or simply update the primary classification URL on the page itself
91 during runtime. This demo utilizes the
92 `javascript protobuf library <https://github.com/dcodeIO/ProtoBuf.js/>`__ to encode
93 parameters into proto binaries in the browser.
94
95 ***NOTE*** One version of the face model's protobuf schema is
96 included with this web page, but it may change over time. If you receive
97 encoding errors or unexpected results, please verify that your target
98 model and this web page are using the same ``.proto`` file.
99
100 -  confirm that your target docker instance is configured and running
101 -  download this directory to your local machine
102
103    -  confirm the host port and classification service URL in the file
104       ``face-privacy.js``
105    -  modify the ``protoDefault`` setting to be 1
106
107       ::
108
109           urlDefault: "http://localhost:8884/model/methods/detect",
110
111 -  view the page ``face-privacy.html`` in a Crome or Firefox browser
112 -  you can switch between a few sample images or upload your own by
113    clicking on the buttons below the main image window
114
115 Compatibility
116 -------------
117 If you want to run against the Boreas model runner you must set the URL to end
118 with /model/methods/detect. The key is that in Boreas release the model runner
119 api has changed. You can see the swagger for the model if you visit the source
120 model's swagger.
121
122 If you have a model that was onboarded using Athena release you do not need
123 the /model/methods check. Use /detect instead. Another change that was made
124 in Boreas model runner was that you must send the http headers before the
125 default was protobuf. These headers will change automatically when use use
126 /model/methods/detect as the URL path.
127
128     - Content-type: application/vnd.google.protobuf
129     - Accept: application/vnd.google.protobuf
130
131
132 Special decoding example
133 ------------------------
134
135 In ``protobuf`` mode, you can also download a binary, encoded version of
136 the last image that was sent to the remote service. When available, the
137 Download Encoded Message button will be enabled and a binary file will
138 be generated in the browser.
139
140 ::
141
142     protoc --decode=HipTviKTkIkcmyuMCIAIDkeOOQQYyJne.Image model.pixelate.proto < protobuf.bin
143
144 **NOTE** The specific package name may have changed since the time of
145 writing, so be sure to check the contents of the current ``.proto``
146 file.
147
148 Example face privacy demo (HTTP parameters)
149 -------------------------------------------
150
151 To customize this demo, one should change either the included javascript
152 or simply update the primary classification URL on the page itself
153 during runtime.
154
155 -  confirm that your local instance is configured and running
156 -  download this directory to your local machine
157
158    -  confirm the host port and classification service URL in the file
159       ``face-privacy.js``
160    -  modify the ``protoDefault`` setting to be 0
161
162       ::
163
164           urlDefault: "http://localhost:8884/transform",
165
166 -  view the page ``face-privacy.html`` in a Crome or Firefox browser
167 -  you can switch between a few sample images or upload your own by
168    clicking on the buttons below the main image window
169
170 Example Interface
171 =================
172
173 An instance should first be built and downloaded and then launched
174 locally. Afterwards, the sample application found in the
175 ``web_demo`` directory uses a ``localhost`` service to classify and
176 visualize the results of image classification.
177
178 -  Commercial example (`youtube source <https://www.youtube.com/watch?v=34KfCNapnUg>`__)
179 -  Reunion face sample  `flickr source <https://flic.kr/p/bEgYbs>`__)
180 -  family face example (`pexel source <https://www.pexels.com/photo/adult-affection-beautiful-beauty-265764/>`__)
181 -  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>`__)
182 -  Schwarzenegger celebrity (`wikimedia source <https://upload.wikimedia.org/wikipedia/commons/thumb/0/0f/A._Schwarzenegger.jpg/220px-A._Schwarzenegger.jpg>`__)
183 -  DeGeneres celebrity face sample (`wikipedia source <https://en.wikipedia.org/wiki/Ellen_DeGeneres#/media/File:Ellen_DeGeneres-2009.jpg>`__)
184
185
186 .. image:: example_running.jpg
187     :alt: example web application with blurring activated
188     :width: 200
189
190
191 Reuse with object detectors
192 ---------------------------
193 This framework can be used to demonstrate other detector and manipulation models 
194 as well.  If the detect model included in this repo is used, faces can be detected
195 and illustrated as shown below.  The example below shows use of the
196 relevant endpoint and ``.proto`` file (also included in this sample).
197
198 .. _demonstration-face-privacy_running_example_obj:
199 .. image:: example_running_detect.jpg
200     :alt: example web application detecting faces
201     :width: 200
202