Use "face privacy" in headings
[face-privacy-filter.git] / docs / tutorials / lesson2.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 # Application server
22 As a means of testing the API and demonstrating functionality, two
23 additional components are included in this repository:
24 a simple [swagger-based webserver](../../testing) (documented here) and
25 a [demo web page](../../web_demo) (documented in the [next tutorial](lesson3.md).
26
27 **NOTE: These steps are now deprecated and a direct protobuf interface from
28 web page to the model (the next tutorial) is the preferred operational step.
29 *(added v0.2.3)* **
30
31 ## Swagger API
32 Using a simple [flask-based connexion server](https://github.com/zalando/connexion),
33 an API scaffold has been built to host a serialized/dumped model.
34
35 To utilized [this example app](../../testing), an instance should first be built and downloaded
36 from Acumos (or dumped to disk) and then
37 launched locally.  Afterwards, the sample application found in
38 [web_demo](web_demo) (see [the next tutorial](lesson3.md))
39 uses a `localhost` service to transform
40 and visualize the results of model operation.
41
42
43 ```
44 usage: app.py [-h] [-p PORT] [-d MODELDIR_DETECT] [-a MODELDIR_ANALYZE]
45
46 optional arguments:
47   -h, --help            show this help message and exit
48   -p PORT, --port PORT  port to launch the simple web server
49   -d MODELDIR_DETECT, --modeldir_detect MODELDIR_DETECT
50                         model directory for detection
51   -a MODELDIR_ANALYZE, --modeldir_analyze MODELDIR_ANALYZE
52                         model directory for detection
53 ```
54
55
56 Example usage may be running with a detect model that was dumped to the directory `model_detect`
57 in the main repo source directory and a pixelate model in the
58 directory `model_pix` (under the same repo source directory).
59
60 ```
61 python app.py --modeldir_detect ../model_detect --modeldir_analyze ../model_pix/
62 ```
63
64
65 ### Output formats
66 This repo provides multiple models that can be created.
67
68 * detect output - The first set, called
69 `detect` will analyze an image, detect face regions, and echo both the
70 regions and the face back to the user.  The region marked with `-1`
71 and a valid `mime_type` parameter will
72 always be the region with the original image.
73
74
75 ```
76 [
77     {
78         "h": 143,
79         "x": 0,
80         "y": 0,
81         "base64_data": "/9j/4AAQSkZJRgABA....",
82         "w": 2048,
83         "region": -1,
84         "image": 0,
85         "mime_type": "image/jpeg"
86     },
87     {
88         "h": 143,
89         "x": 203,
90         "y": 189,
91         "base64_data": "",
92         "w": 143,
93         "region": 0,
94         "image": 0,
95         "mime_type": ""
96     },
97     ...
98     {
99         "h": 212,
100         "x": 886,
101         "y": 409,
102         "base64_data": "",
103         "w": 212,
104         "region": 3,
105         "image": 0,
106         "mime_type": ""
107     }
108 ]
109
110 ```
111
112 * analyzed output - The second type of output produces processed
113 images as an output.  These images are base64 encoded with a decoding
114 mime type.
115
116 ```
117 [
118     {
119         "base64_data": "/9j/4AAQSkZJRgABAQAAAQABAAD....",
120         "mime_type": "image/jpeg"
121     }
122 ]
123
124 ```
125
126 ### Direct use of the model-runner
127
128 Another testing mode is to simualate the output of an Acumos model runner.
129 This model runner can be locally duplicated by using the primary python library
130 `acumos-python-client`.  This execution usage is experimental, but the APIs should
131 be consistent for use.
132
133 ```
134 python acumos-python-client/testing/wrap/runner.py  --port 8884 --modeldir model_detect/
135 ```
136
137 The above command uses the testing-based model runner to launch a singular model
138 that responds on a single port in native `protobuf` format.
139
140
141
142 ## Direct Evaluation
143
144 * For a graphical experience, view the swagger-generated UI at [http://localhost:8884/ui].
145 * Additionally, a simple command-line utility could be used to post an image
146 and mime type to the main interface.  Additional examples for posting base64 encoded
147 images from javascript can be [found on StackOverflow](https://stackoverflow.com/a/20285053).
148
149 ```
150 curl -F base64_data=@../web_demo/images/face_renion.jpg -F mime_type="image/jpeg" "http://localhost:8884/transform"
151 ```
152
153 ## Sample Images
154 Sample images are provided in the `testing` directory and were originally sourced
155 from the URLs below.
156
157 * [multi-face_pexels.jpg](https://www.pexels.com/photo/family-generation-father-mother-8509/)
158 * [single-face_pexels.jpg](https://www.pexels.com/photo/adult-beard-boy-casual-220453/)
159