38c6ff2b45901a7a7d84f43918b4d40da19dfe3a
[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 Below is an extended for training a model, dumping it to disk, and pushing that model. **(recommended)**
48 ```
49 export ACUMOS_USERNAME="user"; \
50 export ACUMOS_PASSWORD="password";
51 or
52 export ACUMOS_TOKEN="a_very_long_token";
53
54 export ACUMOS_PUSH="https://acumos-challenge.org/onboarding-app/v2/models"; \
55 export ACUMOS_AUTH="https://acumos-challenge.org/onboarding-app/v2/auth"; \
56 python face_privacy_filter/filter_image.py -f detect
57 ```
58
59
60 ## In-place Evaluation
61 In-place evaluation **will utilize** a serialized version of the model and load
62 it into memory for use in-place.  This mode is handy for quick
63 evaluation of images or image sets for use in other classifiers.
64
65 * Evaluate the `detect` model from disk and a previously produced detect object
66 ```
67 python face_privacy_filter/filter_image.py -d model_detect -p output.csv -i web_demo/images/face_DiCaprio.jpg
68 ```
69 * Example for evaluating the `pixelate` model from disk and a previously produced detect object
70 ```
71 python face_privacy_filter/filter_image.py -d model_pix -i detect.csv -p output.jpg --csv_input
72 ```
73
74 ## Using the client model runner
75 Getting even closer to what it looks like in a deployed model, you can also use
76 the model runner code to run your full cascade (detection + pixelate) transform
77 locally. *(added v0.3.0)*
78
79 1. First, decide the ports to run your detection and pixelate models. In the example
80 below, detection runs on port `8884` and pixelation runs on port `8885`.  For the
81 runner to properly forward requests for you, provide a simple JSON file example
82 called `runtime.json` in the working directory that you run the model runner.
83
84 ```
85 # cat runtime.json
86 {downstream": ["http://127.0.0.1:8885/pixelate"]}
87 ```
88
89 2. Second, dump and launch the face detection model. If you modify the ports to
90 run the models, please change them accordingly.  This command example assumes
91 that you have cloned the client library in a relative path of `../acumos-python-client`.
92 The first line removes any prior model directory, the second dumps the detect
93 model to disk, and the third runs the model.
94
95 ```
96 rm -rf model_detect/;  \
97     python face_privacy_filter/filter_image.py -d model_detect -f detect; \
98     python ../acumos-python-client/testing/wrap/runner.py --port 8884 --modeldir model_detect/face_privacy_filter_detect
99
100 ```
101
102 3. Finally, dump and launch the face pixelation model. Again, if you modify the ports to
103 run the models, please change them accordingly.  Aside from the model and port,
104 the main difference between the above line is that the model runner is instructed
105 to *ignore* the downstream forward (`runtime.json`) file so that it doesn't attempt
106 to forward the request to itself.
107
108 ```
109 rm -rf model_pix;  \
110     python face_privacy_filter/filter_image.py -d model_pix -f pixelate; \
111     python ../acumos-python-client/testing/wrap/runner.py --port 8885 --modeldir model_pix/face_privacy_filter_pixelate  --no_downstream
112 ```
113
114
115 # Installation Troubleshoting
116 Using some environment-based versions of python (e.g. conda),
117 one problem seemed to come up with the installation of the dependent
118 package `opencv-python`.  If you launch your python instance and see
119 an error like the one below, keep reading.
120
121 ```
122 >>> import cv2
123 Traceback (most recent call last):
124   File "<stdin>", line 1, in <module>
125 ImportError: dynamic module does not define module export function (PyInit_cv2)
126 >>>
127 ```
128
129 This is likely because your `PYTHONPATH` is not correctly configured to
130 point to the additional installed libraries.
131
132 * From the [simple example here](https://stackoverflow.com/a/42160595)
133 you can check your environment with `echo $PYTHONPATH`.  If it does not
134 contain the directory that you installed to, then you have a problem.
135 * Please check your installation by running `python -v -v; import cv2` and checking
136 that the last loaded library is in the right location.
137 * In some instances, this variable needed to be blank to work properly (i.e.
138 `export PYTHONPATH=`) run at some time during start up.
139