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 ```
 109
 110 ## Sample Inages
 111 Sample images are provided in the `testing` directory and were originally sourced
 112 from the URLs below.
 113
 114 * [multi-face_pexels.jpg](https://www.pexels.com/photo/family-generation-father-mother-8509/)
 115 * [single-face_pexels.jpg](https://www.pexels.com/photo/adult-beard-boy-casual-220453/)
 116