1ce2b270f89860e1edefd41d8d796f1501225f38
[face-privacy-filter.git] / docs / tutorials / lesson2.md
1 # Application server
2 As a means of testing the API and demonstrating functionality, two
3 additional components are included in this repository:
4 a simple [swagger-based webserver](../../testing) (documented here) and
5 a [demo web page](../../web_demo) (documented in the [next tutorial](lesson3.md).
6
7 ## Swagger API
8 Using a simple [flask-based connexion server](https://github.com/zalando/connexion),
9 an API scaffold has been built to host a serialized/dumped model.
10
11 To utilized [this example app](../../testing), an instance should first be built and downloaded
12 from Acumos (or dumped to disk) and then
13 launched locally.  Afterwards, the sample application found in
14 [web_demo](web_demo) (see [the next tutorial](lesson3.md))
15 uses a `localhost` service to transform
16 and visualize the results of model operation.
17
18
19 ```
20 usage: app.py [-h] [-p PORT] [-d MODELDIR_DETECT] [-a MODELDIR_ANALYZE]
21
22 optional arguments:
23   -h, --help            show this help message and exit
24   -p PORT, --port PORT  port to launch the simple web server
25   -d MODELDIR_DETECT, --modeldir_detect MODELDIR_DETECT
26                         model directory for detection
27   -a MODELDIR_ANALYZE, --modeldir_analyze MODELDIR_ANALYZE
28                         model directory for detection
29 ```
30
31
32 Example usage may be running with a detect model that was dumped to the directory `model_detect`
33 in the main repo source directory and a pixelate model in the
34 directory `model_pix` (under the same repo source directory).
35
36 ```
37 python app.py --modeldir_detect ../model_detect --modeldir_analyze ../model_pix/
38 ```
39
40
41 ### Output formats
42 This repo provides multiple models that can be created.
43
44 * detect output - The first set, called
45 `detect` will analyze an image, detect face regions, and echo both the
46 regions and the face back to the user.  The region marked with `-1`
47 and a valid `mime_type` parameter will
48 always be the region with the original image.
49
50 ```
51 [
52     {
53         "h": 143,
54         "x": 0,
55         "y": 0,
56         "base64_data": "/9j/4AAQSkZJRgABA....",
57         "w": 2048,
58         "region": -1,
59         "image": 0,
60         "mime_type": "image/jpeg"
61     },
62     {
63         "h": 143,
64         "x": 203,
65         "y": 189,
66         "base64_data": "",
67         "w": 143,
68         "region": 0,
69         "image": 0,
70         "mime_type": ""
71     },
72     ...
73     {
74         "h": 212,
75         "x": 886,
76         "y": 409,
77         "base64_data": "",
78         "w": 212,
79         "region": 3,
80         "image": 0,
81         "mime_type": ""
82     }
83 ]
84
85 ```
86
87 * analyzed output - The second type of output produces processed
88 images as an output.  These images are base64 encoded with a decoding
89 mime type.
90 ```
91 [
92     {
93         "base64_data": "/9j/4AAQSkZJRgABAQAAAQABAAD....",
94         "mime_type": "image/jpeg"
95     }
96 ]
97
98 ```
99
100 ## Direct Evaluation
101
102 * For a graphical experience, view the swagger-generated UI at [http://localhost:8884/ui].
103 * Additionally, a simple command-line utility could be used to post an image
104 and mime type to the main interface.  Additional examples for posting base64 encoded
105 images from javascript can be [found on StackOverflow](https://stackoverflow.com/a/20285053).
106 ```
107 curl -F base64_data=@../web_demo/images/face_renion.jpg -F mime_type="image/jpeg" "http://localhost:8884/transform"
108 ```