• Home
Name
Date
Size
#Lines
LOC

..--

build/03-May-2024-4619

pymodules/its/03-May-2024-2,1071,533

service/03-May-2024-2,4352,012

tests/03-May-2024-4,1172,481

tools/03-May-2024-310184

.gitignoreD03-May-2024134 129

Android.mkD03-May-2024699 221

READMED03-May-202410.9 KiB287209

README

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
16Android Camera Imaging Test Suite (ITS)
17=======================================
18
191. Introduction
20---------------
21
22The ITS is a framework for running tests on the images produced by an Android
23camera. The general goal of each test is to configure the camera in a desired
24manner and capture one or more shots, and then examine the shots to see if
25they contain the expected image data. Many of the tests will require that the
26camera is pointed at a specific target chart or be illuminated at a specific
27intensity.
28
292. Setup
30--------
31
32There are two components to the ITS:
331. The Android device running ItsService.apk.
342. A host machine connected to the Android device that runs Python tests.
35
362.1. Device setup
37-----------------
38
39Build and install ItsService.apk for your device. After setting up your
40shell for Android builds, from the pdk/apps/CameraITS directory run the
41following commands:
42
43    cd service
44    mma -j32
45    adb install -r <YOUR_OUTPUT_PATH>/ItsService.apk
46
47using whatever path is appropriate to your output ItsService.apk file.
48
492.2. Host PC setup
50------------------
51
52The first pre-requisite is the Android SDK, as adb is used to communicate with
53the device.
54
55The test framework is based on Python on the host machine. It requires
56Python 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
64All of these pieces can be installed on your host machine separately,
65however it is highly recommended to install a bundled distribution of
66Python that comes with these modules. Some different bundles are listed
67here:
68
69    http://www.scipy.org/install.html
70
71Of these, Anaconda has been verified to work with these scripts, and it is
72available on Mac, Linux, and Windows from here:
73
74    http://continuum.io/downloads
75
76Note that the Anaconda python executable's directory must be at the front of
77your PATH environment variable, assuming that you are using this Python
78distribution. The Anaconda installer may set this up for you automatically.
79
80Once your Python installation is ready, set up the test environment.
81
822.2.1. Linux + Mac OS X
83-----------------------
84
85On Linux or Mac OS X, run the following command (in a terminal) from the
86pdk/apps/CameraITS directory, from a bash shell:
87
88    source build/envsetup.sh
89
90This will do some basic sanity checks on your Python installation, and set up
91the PYTHONPATH environment variable.
92
932.2.2. Windows
94--------------
95
96On Windows, the bash script won't run (unless you have cygwin (which has not
97been tested)), but all you need to do is set your PYTHONPATH environment
98variable in your shell to point to the pdk/apps/CameraITS/pymodules directory,
99giving an absolute path. Without this, you'll get "import" errors when running
100the test scripts.
101
1023. Python framework overview
103----------------------------
104
105The 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* its.dng: functions to work with DNG metadata
118
119All of these module have associated unit tests; to run the unit tests, execute
120the modules (rather than importing them).
121
1223.1. Device control
123-------------------
124
125The its.device.ItsSession class encapsulates a session with a connected device
126under test (which is running ItsService.apk). The session is over TCP, which is
127forwarded over adb.
128
129As an overview, the ItsSession.do_capture() function takes a Python dictionary
130object as an argument, converts that object to JSON, and sends it to the
131device over tcp which then deserializes from the JSON object representation to
132Camera2 Java objects (CaptureRequests) which are used to specify one or more
133captures. Once the captures are complete, the resultant images are copied back
134to the host machine (over tcp again), along with JSON representations of the
135CaptureResult and other objects that describe the shot that was actually taken.
136
137The Python capture request object(s) can contain key/value entries corresponding
138to any of the Java CaptureRequest object fields.
139
140The output surface's width, height, and format can also be specified. Currently
141supported formats are "jpg", "raw", "raw10", "dng", and "yuv", where "yuv" is
142YUV420 fully planar. The default output surface is a full sensor YUV420 frame.
143
144The metadata that is returned along with the captured images is also in JSON
145format, serialized from the CaptureRequest and CaptureResult objects that were
146passed to the capture listener, as well as the CameraProperties object.
147
1483.2. Image processing and analysis
149----------------------------------
150
151The its.image module is a collection of Python functions, built on top of numpy
152arrays, for manipulating captured images. Some functions of note include:
153
154    load_yuv420_to_rgb_image
155    apply_lut_to_image
156    apply_matrix_to_image
157    write_image
158
159The scripts in the tests directory make use of these modules.
160
161Note that it's important to do heavy image processing using the efficient numpy
162ndarray operations, rather than writing complex loops in standard Python to
163process pixels. Refer to online docs and examples of numpy for information on
164this.
165
1663.3. Tests
167----------
168
169The tests directory contains a number of self-contained test scripts. All
170tests should pass if the tree is in a good state.
171
172Most of the tests save various files in the current directory. To have all the
173output files put into a separate directory, run the script from that directory,
174for example:
175
176    mkdir out
177    cd out
178    python ../tests/scene1/test_linearity.py
179
180Any test can be specified to reboot the camera prior to capturing any shots, by
181adding a "reboot" or "reboot=N" command line argument, where N is the number of
182seconds to wait after rebooting the device before sending any commands; the
183default is 30 seconds.
184
185    python tests/scene1/test_linearity.py reboot
186    python tests/scene1/test_linearity.py reboot=20
187
188It's possible that a test could leave the camera in a bad state, in particular
189if there are any bugs in the HAL or the camera framework. Rebooting the device
190can be used to get it into a known clean state again.
191
192Each test assumes some sort of target or scene. There are multiple scene<N>
193folders under the tests directory, and each contains a README file which
194describes the scene for the scripts in that folder.
195
196By default, camera device id=0 is opened when the script connects to the unit,
197however this can be specified by adding a "camera=1" or similar argument to
198the script command line. On a typical device, camera=0 is the main (rear)
199camera, and camera=1 is the front-facing camera.
200
201    python tests/scene1/test_linearity.py camera=1
202
203The tools/run_all_tests.py script should be executed from the top-level
204CameraITS directory, and it will run all of the tests in an automated fashion,
205saving the generated output files along with the stdout and stderr dumps to
206a temporary directory.
207
208    python tools/run_all_tests.py
209
210This can be run with the "noinit" argument, and in general any args provided
211to this command line will be passed to each script as it is executed.
212
213The tests/inprog directory contains a mix of unfinished, in-progress, and
214incomplete tests. These may or may not be useful in testing a HAL impl.,
215and as these tests are copmleted they will be moved into the scene<N> folders.
216
217When running individual tests from the command line (as in the examples here),
218each test run will ensure that the ItsService is running on the device and is
219ready to accept TCP connections. When using a separate test harness to control
220this infrastructure, the "noinit" command line argument can be provided to
221skip this step; in this case, the test will just try to open a socket to the
222service on the device, and will fail if it's not running and ready.
223
224    python tests/scene1/test_linearity.py noinit
225
2263.4. Target exposure
227--------------------
228
229The tools/config.py script is a wrapper for the its.target module, which is
230used to set an exposure level based on the scene that the camera is imaging.
231The purpose of this is to be able to have tests which use hard-coded manual
232exposure controls, while at the same time ensuring that the captured images
233are properly exposed for the test (and aren't clamped to white or black).
234
235If no argument is provided, the script will use the camera to measure the
236scene to determine the exposure level. An argument can be provided to hard-
237code the exposure level.
238
239    python tools/config.py
240    python tools/config.py 16531519962
241
242This creates a file named its.target.cfg in the current directory, storing the
243target exposure level. Tests that use the its.target module will be reusing
244this value, if they are run from the same directory and if they contain the
245"target" command line argument:
246
247    python tests/scene1/test_linearity.py target
248
249If the "target" argument isn't present, then the script won't use any cached
250its.target.cfg values that may be present in the current directory.
251
2523.5. Docs
253---------
254
255The pydoc tool can generate HTML docs for the ITS Python modules, using the
256following command (run after PYTHONPATH has been set up as described above):
257
258    pydoc -w its its.device its.image its.error its.objects its.dng its.target
259
260There is a tutorial script in the tests folder (named tutorial.py). It
261illustrates a number of the its.image and its.device primitives, and shows
262how to work with image data in general using this infrastructure. (Its code
263is commented with explanatory remarks.)
264
265    python tests/tutorial.py
266
2673.6. List of command line args
268---------------------------------
269
270The above doc sections describe the following command line arguments that may
271be provided when running a test:
272
273    reboot
274    reboot=N
275    target
276    noinit
277    camera=N
278
2794. Known issues
280---------------
281
282The Python test scripts don't work if multiple devices are connected to the
283host machine; currently, the its.device module uses a simplistic "adb -d"
284approach to communicating with the device, assuming that there is only one
285device connected. Fixing this is a TODO.
286
287