CameraITS: Updated docs; moved README text into PDF with figures
Bug: 17994909
Change-Id: Id71c3b2f5a6fb901876c92a95163ca2170e3c9d4
diff --git a/apps/CameraITS/CameraITS.pdf b/apps/CameraITS/CameraITS.pdf
new file mode 100644
index 0000000..5e5fd29
--- /dev/null
+++ b/apps/CameraITS/CameraITS.pdf
Binary files differ
diff --git a/apps/CameraITS/README b/apps/CameraITS/README
deleted file mode 100644
index b09e1b7..0000000
--- a/apps/CameraITS/README
+++ /dev/null
@@ -1,292 +0,0 @@
-# Copyright 2013 The Android Open Source Project
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-
-Android Camera Imaging Test Suite (ITS)
-=======================================
-
-1. Introduction
----------------
-
-The ITS is a framework for running tests on the images produced by an Android
-camera. The general goal of each test is to configure the camera in a desired
-manner and capture one or more shots, and then examine the shots to see if
-they contain the expected image data. Many of the tests will require that the
-camera is pointed at a specific target chart or be illuminated at a specific
-intensity.
-
-2. Setup
---------
-
-There are two components to the ITS:
-1. The Android device running CtsVerifier.apk.
-2. A host machine connected to the Android device that runs Python tests.
-
-2.1. Device setup
------------------
-
-Build and install CtsVerifier.apk for your device. Along with the regular
-CTS verifier tests, this includes the ITS service used by the ITS python
-scripts to capture image data. After setting up your shell for Android builds,
-from the cts/apps/CameraITS directory run the following commands:
-
- cd <BUILD_PATH>/cts/apps/CtsVerifier
- mma -j32
- adb install -r <YOUR_OUTPUT_PATH>/CtsVerifier.apk
-
-using whatever path is appropriate to your output CtsVerifier.apk file.
-
-Note: If you are installing this from CTS Verifier bundle
-(android-cts-verifier.zip) rather than from a full Android source tree, both
-the CtsVerifier.apk and CameraITS directory can be found at the top level of
-the zipped android-cts-verifier folder.
-
-2.2. Host PC setup
-------------------
-
-The first pre-requisite is the Android SDK, as adb is used to communicate with
-the device.
-
-The test framework is based on Python on the host machine. It requires
-Python 2.7 and the scipy/numpy stack, including the Python Imaging Library.
-
-(For Ubuntu users)
-
- sudo apt-get install python-numpy python-scipy python-matplotlib
-
-(For other users)
-
-All of these pieces can be installed on your host machine separately,
-however it is highly recommended to install a bundled distribution of
-Python that comes with these modules. Some different bundles are listed
-here:
-
- http://www.scipy.org/install.html
-
-Of these, Anaconda has been verified to work with these scripts, and it is
-available on Mac, Linux, and Windows from here:
-
- http://continuum.io/downloads
-
-Note that the Anaconda python executable's directory must be at the front of
-your PATH environment variable, assuming that you are using this Python
-distribution. The Anaconda installer may set this up for you automatically.
-
-Once your Python installation is ready, set up the test environment.
-
-2.2.1. Linux + Mac OS X
------------------------
-
-On Linux or Mac OS X, run the following command (in a terminal) from the
-cts/apps/CameraITS directory, from a bash shell:
-
- source build/envsetup.sh
-
-This will do some basic sanity checks on your Python installation, and set up
-the PYTHONPATH environment variable.
-
-2.2.2. Windows
---------------
-
-On Windows, the bash script won't run (unless you have cygwin (which has not
-been tested)), but all you need to do is set your PYTHONPATH environment
-variable in your shell to point to the cts/apps/CameraITS/pymodules directory,
-giving an absolute path. Without this, you'll get "import" errors when running
-the test scripts.
-
-3. Python framework overview
-----------------------------
-
-The Python modules are under the pymodules directory, in the "its" package.
-
-* its.device: encapsulates communication with ITS service included in the
- CtsVerifier.apk running on the device
-* its.objects: contains a collection of functions for creating Python objects
- corresponding to the Java objects which the ITS service uses
-* its.image: contains a collection of functions (built on numpy arrays) for
- processing captured images
-* its.error: the exception/error class used in this framework
-* its.target: functions to set and measure the exposure level to use for
- manual shots in tests, to ensure that the images are exposed well for the
- target scene
-* its.dng: functions to work with DNG metadata
-
-All of these module have associated unit tests; to run the unit tests, execute
-the modules (rather than importing them).
-
-3.1. Device control
--------------------
-
-The its.device.ItsSession class encapsulates a session with a connected device
-under test (which is running CtsVerifier.apk). The session is over TCP, which is
-forwarded over adb.
-
-As an overview, the ItsSession.do_capture() function takes a Python dictionary
-object as an argument, converts that object to JSON, and sends it to the
-device over tcp which then deserializes from the JSON object representation to
-Camera2 Java objects (CaptureRequests) which are used to specify one or more
-captures. Once the captures are complete, the resultant images are copied back
-to the host machine (over tcp again), along with JSON representations of the
-CaptureResult and other objects that describe the shot that was actually taken.
-
-The Python capture request object(s) can contain key/value entries corresponding
-to any of the Java CaptureRequest object fields.
-
-The output surface's width, height, and format can also be specified. Currently
-supported formats are "jpg", "raw", "raw10", "dng", and "yuv", where "yuv" is
-YUV420 fully planar. The default output surface is a full sensor YUV420 frame.
-
-The metadata that is returned along with the captured images is also in JSON
-format, serialized from the CaptureRequest and CaptureResult objects that were
-passed to the capture listener, as well as the CameraProperties object.
-
-3.2. Image processing and analysis
-----------------------------------
-
-The its.image module is a collection of Python functions, built on top of numpy
-arrays, for manipulating captured images. Some functions of note include:
-
- load_yuv420_to_rgb_image
- apply_lut_to_image
- apply_matrix_to_image
- write_image
-
-The scripts in the tests directory make use of these modules.
-
-Note that it's important to do heavy image processing using the efficient numpy
-ndarray operations, rather than writing complex loops in standard Python to
-process pixels. Refer to online docs and examples of numpy for information on
-this.
-
-3.3. Tests
-----------
-
-The tests directory contains a number of self-contained test scripts. All
-tests should pass if the tree is in a good state.
-
-Most of the tests save various files in the current directory. To have all the
-output files put into a separate directory, run the script from that directory,
-for example:
-
- mkdir out
- cd out
- python ../tests/scene1/test_linearity.py
-
-Any test can be specified to reboot the camera prior to capturing any shots, by
-adding a "reboot" or "reboot=N" command line argument, where N is the number of
-seconds to wait after rebooting the device before sending any commands; the
-default is 30 seconds.
-
- python tests/scene1/test_linearity.py reboot
- python tests/scene1/test_linearity.py reboot=20
-
-It's possible that a test could leave the camera in a bad state, in particular
-if there are any bugs in the HAL or the camera framework. Rebooting the device
-can be used to get it into a known clean state again.
-
-Each test assumes some sort of target or scene. There are multiple scene<N>
-folders under the tests directory, and each contains a README file which
-describes the scene for the scripts in that folder.
-
-By default, camera device id=0 is opened when the script connects to the unit,
-however this can be specified by adding a "camera=1" or similar argument to
-the script command line. On a typical device, camera=0 is the main (rear)
-camera, and camera=1 is the front-facing camera.
-
- python tests/scene1/test_linearity.py camera=1
-
-The tools/run_all_tests.py script should be executed from the top-level
-CameraITS directory, and it will run all of the tests in an automated fashion,
-saving the generated output files along with the stdout and stderr dumps to
-a temporary directory.
-
- python tools/run_all_tests.py
-
-This can be run with the "noinit" argument, and in general any args provided
-to this command line will be passed to each script as it is executed.
-
-The tests/inprog directory contains a mix of unfinished, in-progress, and
-incomplete tests. These may or may not be useful in testing a HAL impl.,
-and as these tests are completed they will be moved into the scene<N> folders.
-
-When running individual tests from the command line (as in the examples here),
-each test run will ensure that the ITS service is running on the device and is
-ready to accept TCP connections. When using a separate test harness to control
-this infrastructure, the "noinit" command line argument can be provided to
-skip this step; in this case, the test will just try to open a socket to the
-service on the device, and will fail if it's not running and ready.
-
- python tests/scene1/test_linearity.py noinit
-
-3.4. Target exposure
---------------------
-
-The tools/config.py script is a wrapper for the its.target module, which is
-used to set an exposure level based on the scene that the camera is imaging.
-The purpose of this is to be able to have tests which use hard-coded manual
-exposure controls, while at the same time ensuring that the captured images
-are properly exposed for the test (and aren't clamped to white or black).
-
-If no argument is provided, the script will use the camera to measure the
-scene to determine the exposure level. An argument can be provided to hard-
-code the exposure level.
-
- python tools/config.py
- python tools/config.py 16531519962
-
-This creates a file named its.target.cfg in the current directory, storing the
-target exposure level. Tests that use the its.target module will be reusing
-this value, if they are run from the same directory and if they contain the
-"target" command line argument:
-
- python tests/scene1/test_linearity.py target
-
-If the "target" argument isn't present, then the script won't use any cached
-its.target.cfg values that may be present in the current directory.
-
-3.5. Docs
----------
-
-The pydoc tool can generate HTML docs for the ITS Python modules, using the
-following command (run after PYTHONPATH has been set up as described above):
-
- pydoc -w its its.device its.image its.error its.objects its.dng its.target
-
-There is a tutorial script in the tests folder (named tutorial.py). It
-illustrates a number of the its.image and its.device primitives, and shows
-how to work with image data in general using this infrastructure. (Its code
-is commented with explanatory remarks.)
-
- python tests/tutorial.py
-
-3.6. List of command line args
----------------------------------
-
-The above doc sections describe the following command line arguments that may
-be provided when running a test:
-
- reboot
- reboot=N
- target
- noinit
- camera=N
-
-4. Known issues
----------------
-
-The Python test scripts don't work if multiple devices are connected to the
-host machine; currently, the its.device module uses a simplistic "adb -d"
-approach to communicating with the device, assuming that there is only one
-device connected. Fixing this is a TODO.
-
diff --git a/apps/CameraITS/tests/scene0/README b/apps/CameraITS/tests/scene0/README
deleted file mode 100644
index 50be04a..0000000
--- a/apps/CameraITS/tests/scene0/README
+++ /dev/null
@@ -1,3 +0,0 @@
-This scene has no requirements; scene 0 tests don't actually
-look at the image content, and the camera can be pointed at
-any target (or even flat on the desk).
diff --git a/apps/CameraITS/tests/scene1/README b/apps/CameraITS/tests/scene1/README
deleted file mode 100755
index 93543d9..0000000
--- a/apps/CameraITS/tests/scene1/README
+++ /dev/null
@@ -1,16 +0,0 @@
-Scene 1 description:
-* Camera on tripod in portrait or landscape orientation
-* Scene mostly filled by grey card, with white background behind grey card
-* Illuminated by simple light source, for example a desk lamp
-* Uniformity of lighting and target positioning need not be precise
-
-This is intended to be a very simple setup that can be recreated on an
-engineer's desk without any large or expensive equipment. The tests for this
-scene in general only look at a patch in the middle of the image (which is
-assumed to be within the bounds of the grey card).
-
-Note that the scene should not be completely uniform; don't have the grey card
-100% fill the field of view and use a high quality uniform light source, for
-example, and don't use a diffuser on top of the camera to simulate a grey
-scene.
-
