1# Copyright 2014 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# The Google Python style guide should be used for scripts:                   #
17# http://google-styleguide.googlecode.com/svn/trunk/pyguide.html              #
18# --------------------------------------------------------------------------- #
19
20# The ITS modules that are in the utils directory. To see formatted
21# docs, use the "pydoc" command:
22#
23# > pydoc image_processing_utils
24#
25"""Tutorial script for CameraITS tests."""
26import capture_request_utils
27import image_processing_utils
28import its_base_test
29import its_session_utils
30
31# Standard Python modules.
32import logging
33import os.path
34
35# Modules from the numpy, scipy, and matplotlib libraries. These are used for
36# the image processing code, and images are represented as numpy arrays.
37from matplotlib import pylab
38import numpy
39import matplotlib
40import matplotlib.pyplot
41
42# Module for Mobly
43from mobly import test_runner
44
45# A convention in each script is to use the filename (without the extension)
46# as the name of the test, when printing results to the screen or dumping files.
47_NAME = os.path.basename(__file__).split('.')[0]
48
49
50# Each script has a class definition
51class TutorialTest(its_base_test.ItsBaseTest):
52  """Test the validity of some metadata entries.
53
54  Looks at the capture results and at the camera characteristics objects.
55  Script uses a config.yml file in the CameraITS directory.
56  A sample config.yml file:
57    TestBeds:
58    - Name: TEST_BED_TUTORIAL
59      Controllers:
60          AndroidDevice:
61            - serial: 03281FDD40008Y
62              label: dut
63      TestParams:
64        camera: "1"
65        scene: "0"
66
67  A sample script call:
68    python tests/tutorial.py --config config.yml
69
70  """
71
72  def test_tutorial(self):
73    # Each script has a string description of what it does. This is the first
74    # entry inside the main function.
75    """Tutorial script to show how to use the ITS infrastructure."""
76
77    # The standard way to open a session with a connected camera device. This
78    # creates a cam object which encapsulates the session and which is active
79    # within the scope of the 'with' block; when the block exits, the camera
80    # session is closed. The device and camera are defined in the config.yml
81    # file.
82    with its_session_utils.ItsSession(
83        device_id=self.dut.serial,
84        camera_id=self.camera_id,
85        hidden_physical_id=self.hidden_physical_id) as cam:
86
87      # Append the log_path to store images in the proper location.
88      # Images will be stored in the test output folder:
89      # /tmp/logs/mobly/$TEST_BED_NAME/$DATE/TutorialTest
90      file_name = os.path.join(self.log_path, _NAME)
91
92      # Get the static properties of the camera device. Returns a Python
93      # associative array object; print it to the console.
94      props = cam.get_camera_properties()
95      logging.debug('props\n%s', str(props))
96
97      # Grab a YUV frame with manual exposure of sensitivity = 200, exposure
98      # duration = 50ms.
99      req = capture_request_utils.manual_capture_request(200, 50*1000*1000)
100      cap = cam.do_capture(req)
101
102      # Print the properties of the captured frame; width and height are
103      # integers, and the metadata is a Python associative array object.
104      # logging.info will be printed to screen & test_log.INFO
105      # logging.debug to test_log.DEBUG in /tmp/logs/mobly/... directory
106      logging.info('Captured image width: %d, height: %d',
107                   cap['width'], cap['height'])
108      logging.debug('metadata\n%s', str(cap['metadata']))
109
110      # The captured image is YUV420. Convert to RGB, and save as a file.
111      rgbimg = image_processing_utils.convert_capture_to_rgb_image(cap)
112      image_processing_utils.write_image(rgbimg, f'{file_name}_rgb.jpg')
113
114      # Can also get the Y,U,V planes separately; save these to greyscale
115      # files.
116      yimg, uimg, vimg = image_processing_utils.convert_capture_to_planes(cap)
117      image_processing_utils.write_image(yimg, f'{file_name}_y_plane.jpg')
118      image_processing_utils.write_image(uimg, f'{file_name}_u_plane.jpg')
119      image_processing_utils.write_image(vimg, f'{file_name}_v_plane.jpg')
120
121      # Run 3A on the device. In this case, just use the entire image as the
122      # 3A region, and run each of AWB,AE,AF. Can also change the region and
123      # specify independently for each of AE,AWB,AF whether it should run.
124      #
125      # NOTE: This may fail, if the camera isn't pointed at a reasonable
126      # target scene. If it fails, the script will end. The logcat messages
127      # can be inspected to see the status of 3A running on the device.
128      #
129      # If this keeps on failing, try also rebooting the device before
130      # running the test.
131      sens, exp, gains, xform, focus = cam.do_3a(get_results=True)
132      logging.info('AE: sensitivity %d, exposure %dms', sens, exp/1000000.0)
133      logging.info('AWB: gains %s', str(gains))
134      logging.info('AWB: transform %s', str(xform))
135      logging.info('AF: distance %.4f', focus)
136
137      # Grab a new manual frame, using the 3A values, and convert it to RGB
138      # and save it to a file too. Note that the 'req' object is just a
139      # Python dictionary that is pre-populated by the capture_request_utils
140      # functions (in this case a default manual capture), and the key/value
141      # pairs in the object can be used to set any field of the capture
142      # request. Here, the AWB gains and transform (CCM) are being used.
143      # Note that the CCM transform is in a rational format in capture
144      # requests, meaning it is an object with integer numerators and
145      # denominators. The 3A routine returns simple floats instead, however,
146      # so a conversion from float to rational must be performed.
147      req = capture_request_utils.manual_capture_request(sens, exp)
148      xform_rat = capture_request_utils.float_to_rational(xform)
149
150      req['android.colorCorrection.transform'] = xform_rat
151      req['android.colorCorrection.gains'] = gains
152      cap = cam.do_capture(req)
153      rgbimg = image_processing_utils.convert_capture_to_rgb_image(cap)
154      image_processing_utils.write_image(rgbimg, f'{file_name}_rgb_2.jpg')
155
156      # log the actual capture request object that was used.
157      logging.debug('req: %s', str(req))
158
159      # Images are numpy arrays. The dimensions are (h,w,3) when indexing,
160      # in the case of RGB images. Greyscale images are (h,w,1). Pixels are
161      # generally float32 values in the [0,1] range, however some of the
162      # helper functions in image_processing_utils deal with the packed YUV420
163      # and other formats of images that come from the device (and convert
164      # them to float32).
165      # Print the dimensions of the image, and the top-left pixel value,
166      # which is an array of 3 floats.
167      logging.info('RGB image dimensions: %s', str(rgbimg.shape))
168      logging.info('RGB image top-left pixel: %s', str(rgbimg[0, 0]))
169
170      # Grab a center tile from the image; this returns a new image. Save
171      # this tile image. In this case, the tile is the middle 10% x 10%
172      # rectangle.
173      tile = image_processing_utils.get_image_patch(
174          rgbimg, 0.45, 0.45, 0.1, 0.1)
175      image_processing_utils.write_image(tile, f'{file_name}_rgb_2_tile.jpg')
176
177      # Compute the mean values of the center tile image.
178      rgb_means = image_processing_utils.compute_image_means(tile)
179      logging.info('RGB means: %s', str(rgb_means))
180
181      # Apply a lookup table to the image, and save the new version. The LUT
182      # is basically a tonemap, and can be used to implement a gamma curve.
183      # In this case, the LUT is used to double the value of each pixel.
184      lut = numpy.array([2*i for i in range(65536)])
185      rgbimg_lut = image_processing_utils.apply_lut_to_image(rgbimg, lut)
186      image_processing_utils.write_image(
187          rgbimg_lut, f'{file_name}_rgb_2_lut.jpg')
188
189      # Compute a histogram of the luma image, in 256 buckets.
190      yimg, _, _ = image_processing_utils.convert_capture_to_planes(cap)
191      hist, _ = numpy.histogram(yimg*255, 256, (0, 256))
192
193      # Plot the histogram using matplotlib, and save as a PNG image.
194      pylab.plot(range(256), hist.tolist())
195      pylab.xlabel('Luma DN')
196      pylab.ylabel('Pixel count')
197      pylab.title('Histogram of luma channel of captured image')
198      matplotlib.pyplot.savefig(f'{file_name}_histogram.png')
199
200      # Capture a frame to be returned as a JPEG. Load it as an RGB image,
201      # then save it back as a JPEG.
202      cap = cam.do_capture(req, cam.CAP_JPEG)
203      rgbimg = image_processing_utils.convert_capture_to_rgb_image(cap)
204      image_processing_utils.write_image(rgbimg, f'{file_name}_jpg.jpg')
205      r, _, _ = image_processing_utils.convert_capture_to_planes(cap)
206      image_processing_utils.write_image(r, f'{file_name}_r.jpg')
207
208# This is the standard boilerplate in each test that allows the script to both
209# be executed directly and imported as a module.
210if __name__ == '__main__':
211  test_runner.main()
212
213