1 # Copyright 2013 The Android Open Source Project 2 # 3 # Licensed under the Apache License, Version 2.0 (the "License"); 4 # you may not use this file except in compliance with the License. 5 # You may obtain a copy of the License at 6 # 7 # http://www.apache.org/licenses/LICENSE-2.0 8 # 9 # Unless required by applicable law or agreed to in writing, software 10 # distributed under the License is distributed on an "AS IS" BASIS, 11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 # See the License for the specific language governing permissions and 13 # limitations under the License. 14 15 16 Android Camera Imaging Test Suite (ITS) 17 ======================================= 18 19 1. Introduction 20 --------------- 21 22 The ITS is a framework for running tests on the images produced by an Android 23 camera. The general goal of each test is to configure the camera in a desired 24 manner and capture one or more shots, and then examine the shots to see if 25 they contain the expected image data. Many of the tests will require that the 26 camera is pointed at a specific target chart or be illuminated at a specific 27 intensity. 28 29 2. Setup 30 -------- 31 32 There are two components to the ITS: 33 1. The Android device running ItsService.apk. 34 2. A host machine connected to the Android device that runs Python tests. 35 36 2.1. Device setup 37 ----------------- 38 39 Build and install ItsService.apk for your device. After setting up your 40 shell for Android builds, from the pdk/apps/CameraITS directory run the 41 following commands: 42 43 cd service 44 mm 45 adb install -r <YOUR_OUTPUT_PATH>/ItsService.apk 46 47 using whatever path is appropriate to your output ItsService.apk file. 48 49 2.2. Host PC setup 50 ------------------ 51 52 The first pre-requisite is the Android SDK, as adb is used to communicate with 53 the device. 54 55 The test framework is based on Python on the host machine. It requires 56 Python 2.7 and the scipy/numpy stack, including the Python Imaging Library. 57 58 (For Ubuntu users) 59 60 sudo apt-get install python-numpy python-scipy python-matplotlib 61 62 (For other users) 63 64 All of these pieces can be installed on your host machine separately, 65 however it is highly recommended to install a bundled distribution of 66 Python that comes with these modules. Some different bundles are listed 67 here: 68 69 http://www.scipy.org/install.html 70 71 Of these, Anaconda has been verified to work with these scripts, and it is 72 available on Mac, Linux, and Windows from here: 73 74 http://continuum.io/downloads 75 76 Note that the Anaconda python executable's directory must be at the front of 77 your PATH environment variable, assuming that you are using this Python 78 distribution. The Anaconda installer may set this up for you automatically. 79 80 Once your Python installation is ready, set up the test environment. 81 82 2.2.1. Linux + Mac OS X 83 ----------------------- 84 85 On Linux or Mac OS X, run the following command (in a terminal) from the 86 pdk/apps/CameraITS directory, from a bash shell: 87 88 source build/envsetup.sh 89 90 This will do some basic sanity checks on your Python installation, and set up 91 the PYTHONPATH environment variable. 92 93 2.2.2. Windows 94 -------------- 95 96 On Windows, the bash script won't run (unless you have cygwin (which has not 97 been tested)), but all you need to do is set your PYTHONPATH environment 98 variable in your shell to point to the pdk/apps/CameraITS/pymodules directory, 99 giving an absolute path. Without this, you'll get "import" errors when running 100 the test scripts. 101 102 3. Python framework overview 103 ---------------------------- 104 105 The Python modules are under the pymodules directory, in the "its" package. 106 107 * its.device: encapsulates communication with ItsService.apk service running 108 on the device 109 * its.objects: contains a collection of functions for creating Python objects 110 corresponding to the Java objects which ItsService.apk uses 111 * its.image: contains a collection of functions (built on numpy arrays) for 112 processing captured images 113 * its.error: the exception/error class used in this framework 114 * its.target: functions to set and measure the exposure level to use for 115 manual shots in tests, to ensure that the images are exposed well for the 116 target scene 117 118 All of these module have associated unit tests; to run the unit tests, execute 119 the modules (rather than importing them). 120 121 3.1. Device control 122 ------------------- 123 124 The its.device.ItsSession class encapsulates a session with a connected device 125 under test (which is running ItsService.apk). The session is over TCP, which is 126 forwarded over adb. 127 128 As an overview, the ItsSession.do_capture() function takes a Python dictionary 129 object as an argument, converts that object to JSON, and sends it to the 130 device over tcp which then deserializes from the JSON object representation to 131 Camera2 Java objects (CaptureRequests) which are used to specify one or more 132 captures. Once the captures are complete, the resultant images are copied back 133 to the host machine (over tcp again), along with JSON representations of the 134 CaptureResult and other objects that describe the shot that was actually taken. 135 136 The Python capture request object(s) can contain key/value entries corresponding 137 to any of the Java CaptureRequest object fields. 138 139 The output surface's width, height, and format can also be specified. Currently 140 supported formats are "jpg" and "yuv", where "yuv" is YUV420 fully planar. The 141 default output surface is a full sensor YUV420 frame. 142 143 The metadata that is returned along with the captured images is also in JSON 144 format, serialized from the CaptureRequest and CaptureResult objects that were 145 passed to the capture listener, as well as the CameraProperties object. 146 147 3.2. Image processing and analysis 148 ---------------------------------- 149 150 The its.image module is a collection of Python functions, built on top of numpy 151 arrays, for manipulating captured images. Some functions of note include: 152 153 load_yuv420_to_rgb_image 154 apply_lut_to_image 155 apply_matrix_to_image 156 write_image 157 158 The scripts in the tests directory make use of these modules. 159 160 Note that it's important to do heavy image processing using the efficient numpy 161 ndarray operations, rather than writing complex loops in standard Python to 162 process pixels. Refer to online docs and examples of numpy for information on 163 this. 164 165 3.3. Tests 166 ---------- 167 168 The tests directory contains a number of self-contained test scripts. All 169 tests should pass if the tree is in a good state. 170 171 Most of the tests save various files in the current directory. To have all the 172 output files put into a separate directory, run the script from that directory, 173 for example: 174 175 mkdir out 176 cd out 177 python ../tests/test_linearity.py 178 179 Any test can be specified to reboot the camera prior to capturing any shots, by 180 adding a "reboot" or "reboot=N" command line argument, where N is the number of 181 seconds to wait after rebooting the device before sending any commands; the 182 default is 30 seconds. 183 184 python tests/test_linearity.py reboot 185 python tests/test_linearity.py reboot=20 186 187 It's possible that a test could leave the camera in a bad state, in particular 188 if there are any bugs in the HAL or the camera framework. Rebooting the device 189 can be used to get it into a known clean state again. 190 191 3.4. Target exposure 192 -------------------- 193 194 The tests/config.py script is a wrapper for the its.target module, which is 195 used to set an exposure level based on the scene that the camera is imaging. 196 The purpose of this is to be able to have tests which use hard-coded manual 197 exposure controls, while at the same time ensuring that the captured images 198 are properly exposed for the test (and aren't clamped to white or black). 199 200 If no argument is provided, the script will use the camera to measure the 201 scene to determine the exposure level. An argument can be provided to hard- 202 code the exposure level. 203 204 python tests/config.py 205 python tests/config.py 16531519962 206 207 This creates a file named its.target.cfg in the current directory, storing the 208 target exposure level. Tests that use the its.target module will be reusing 209 this value, if they are run from the same directory. 210 211 3.5. Docs 212 --------- 213 214 The pydoc tool can generate HTML docs for the ITS Python modules, using the 215 following command (run after PYTHONPATH has been set up as described above): 216 217 pydoc -w its its.device its.image its.error its.objects 218 219 There is a tutorial script in the tests folder (named tutorial.py). It 220 illustrates a number of the its.image and its.device primitives, and shows 221 how to work with image data in general using this infrastructure. (Its code 222 is commented with explanatory remarks.) 223 224 python tests/tutorial.py 225 226 4. Known issues 227 --------------- 228 229 The Python test scripts don't work if multiple devices are connected to the 230 host machine; currently, the its.device module uses a simplistic "adb -d" 231 approach to communicating with the device, assuming that there is only one 232 device connected. Fixing this is a TODO. 233 234
