convert protobuf i/o to flat,row-like data
[face-privacy-filter.git] / docs / tutorials / lesson1.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 # Wrapping Models for Deployment
22 To utilize this transformer model set, it first creates a detect transformer
23 and then a pixelate transformer.
24 Continue to the [next tutorial](lesson2.md)
25 to see how to utilize these models with a simple demo API server.
26
27
28 ## Model Deployment
29 Following similar use pattens described by the main client library, there are
30 two primary modes to export and deploy the generated classifier: by dumping
31 it to disk or by pushing it to an onboarding server.  Please consult the
32 [reference manual](../image-classification.md#usage) for more specific arguments
33 but the examples below demonstrate basic capabilities.
34
35 This single repo has a number of different models that can be
36 composed together for operation.
37
38 * Dump the `detect` model to disk.
39 ```
40 python face_privacy_filter/filter_image.py -f detect  -d model_detect
41 ```
42 * Dump the `pixelate` model to disk.
43 ```
44 python face_privacy_filter/filter_image.py -f pixelate -d model_pix
45 ```
46
47
48 ## In-place Evaluation
49 In-place evaluation **will utilize** a serialized version of the model and load
50 it into memory for use in-place.  This mode is handy for quick
51 evaluation of images or image sets for use in other classifiers.
52
53 * Evaluate the `detect` model from disk and a previously produced detect object
54 ```
55 python face_privacy_filter/filter_image.py -d model_detect -p output.csv -i web_demo/images/face_DiCaprio.jpg
56 ```
57 * Example for evaluating the `pixelate` model from disk and a previously produced detect object
58 ```
59 python face_privacy_filter/filter_image.py -d model_pix -i detect.csv -p output.jpg --csv_input
60 ```
61
62 ## Using the client model runner
63 Getting even closer to what it looks like in a deployed model, you can also use
64 the model runner code to run your full cascade (detection + pixelate) transform
65 locally. *(added v0.3.0)*
66
67 1. First, decide the ports to run your detection and pixelate models. In the example
68 below, detection runs on port `8884` and pixelation runs on port `8885`.  For the
69 runner to properly forward requests for you, provide a simple JSON file example
70 called `runtime.json` in the working directory that you run the model runner.
71
72 ```
73 # cat runtime.json
74 {downstream": ["http://127.0.0.1:8885/pixelate"]}
75 ```
76
77 2. Second, dump and launch the face detection model. If you modify the ports to
78 run the models, please change them accordingly.  This command example assumes
79 that you have cloned the client library in a relative path of `../acumos-python-client`.
80 The first line removes any prior model directory, the second dumps the detect
81 model to disk, and the third runs the model.
82
83 ```
84 rm -rf model_detect/;  \
85     python face_privacy_filter/filter_image.py -d model_detect -f detect; \
86     python ../acumos-python-client/testing/wrap/runner.py --port 8884 --modeldir model_detect/face_privacy_filter_detect
87
88 ```
89
90 3. Finally, dump and launch the face pixelation model. Again, if you modify the ports to
91 run the models, please change them accordingly.  Aside from the model and port,
92 the main difference between the above line is that the model runner is instructed
93 to *ignore* the downstream forward (`runtime.json`) file so that it doesn't attempt
94 to forward the request to itself.
95
96 ```
97 rm -rf model_pix;  \
98     python face_privacy_filter/filter_image.py -d model_pix -f pixelate; \
99     python ../acumos-python-client/testing/wrap/runner.py --port 8885 --modeldir model_pix/face_privacy_filter_pixelate  --no_downstream
100 ```
101
102
103 # Installation Troubleshoting
104 Using some environment-based versions of python (e.g. conda),
105 one problem seemed to come up with the installation of the dependent
106 package `opencv-python`.  If you launch your python instance and see
107 an error like the one below, keep reading.
108
109 ```
110 >>> import cv2
111 Traceback (most recent call last):
112   File "<stdin>", line 1, in <module>
113 ImportError: dynamic module does not define module export function (PyInit_cv2)
114 >>>
115 ```
116
117 This is likely because your `PYTHONPATH` is not correctly configured to
118 point to the additional installed libraries.
119
120 * From the [simple example here](https://stackoverflow.com/a/42160595)
121 you can check your environment with `echo $PYTHONPATH`.  If it does not
122 contain the directory that you installed to, then you have a problem.
123 * Please check your installation by running `python -v -v; import cv2` and checking
124 that the last loaded library is in the right location.
125 * In some instances, this variable needed to be blank to work properly (i.e.
126 `export PYTHONPATH=`) run at some time during start up.
127