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