b2535f66ad1fc738e7ec1a843ee27e0f1c88f203
[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         "h": 143,
74         "x": 0,
75         "y": 0,
76         "base64_data": "/9j/4AAQSkZJRgABA....",
77         "w": 2048,
78         "region": -1,
79         "image": 0,
80         "mime_type": "image/jpeg"
81     },
82     {
83         "h": 143,
84         "x": 203,
85         "y": 189,
86         "base64_data": "",
87         "w": 143,
88         "region": 0,
89         "image": 0,
90         "mime_type": ""
91     },
92     ...
93     {
94         "h": 212,
95         "x": 886,
96         "y": 409,
97         "base64_data": "",
98         "w": 212,
99         "region": 3,
100         "image": 0,
101         "mime_type": ""
102     }
103 ]
104
105 ```
106
107 * analyzed output - The second type of output produces processed
108 images as an output.  These images are base64 encoded with a decoding
109 mime type.
110 ```
111 [
112     {
113         "base64_data": "/9j/4AAQSkZJRgABAQAAAQABAAD....",
114         "mime_type": "image/jpeg"
115     }
116 ]
117
118 ```
119
120 ### Direct use of the model-runner
121
122 Another testing mode is to simualate the output of an Acumos model runner.
123 This model runner can be locally duplicated by using the primary python library
124 `acumos-python-client`.  This execution usage is experimental, but the APIs should
125 be consistent for use.
126
127 ```
128 python acumos-python-client/testing/wrap/runner.py  --port 8884 --modeldir model_detect/
129 ```
130
131 The above command uses the testing-based model runner to launch a singular model
132 that responds on a single port in native `protobuf` format.
133
134
135
136 ## Direct Evaluation
137
138 * For a graphical experience, view the swagger-generated UI at [http://localhost:8884/ui].
139 * Additionally, a simple command-line utility could be used to post an image
140 and mime type to the main interface.  Additional examples for posting base64 encoded
141 images from javascript can be [found on StackOverflow](https://stackoverflow.com/a/20285053).
142 ```
143 curl -F base64_data=@../web_demo/images/face_renion.jpg -F mime_type="image/jpeg" "http://localhost:8884/transform"
144 ```
145
146 ## Sample Inages
147 Sample images are provided in the `testing` directory and were originally sourced
148 from the URLs below.
149
150 * [multi-face_pexels.jpg](https://www.pexels.com/photo/family-generation-father-mother-8509/)
151 * [single-face_pexels.jpg](https://www.pexels.com/photo/adult-beard-boy-casual-220453/)
152