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