3.4 `camera` -- Interface for taking photographs and video recording

Availability: S60.

The camera module enables taking photographs and video recording.

The following data items for state information are available in camera:

EOpenComplete: The opening of the video clip has succeeded.

ERecordComplete: The video recording has completed (not called on explicit stop_recording call).

EPrepareComplete: The device is ready to begin video recording.

The camera module has the following functions^3.3:

cameras_available( ): Returns the number of cameras available in the device.

image_modes( ): Returns the image modes supported in the device as a list of strings, for example: ['RGB12', 'RGB', 'JPEG_Exif', 'RGB16'].

image_sizes( ): Returns the image sizes (resolution) supported in the device as a list of (x, y) tuples, for example: [(640, 480), (160, 120)].

flash_modes( ): Returns the flash modes available in the device as a list of strings.

max_zoom( ): Returns the maximum digital zoom value supported in the device as an integer.

exposure_modes( ): Returns the exposure settings supported in the device as a list of strings.

white_balance_modes( ): Returns the white balance modes available in the device as a list of strings.

take_photo( [mode, size, zoom, flash, exposure, white_balance, position])

Takes a photograph and returns the image in:

Image format (for more information on Image format, see Chapter 3.3 graphics Module) or
Raw JPEG data^3.4.

The settings listed below describe all settings that are supported by the camera module. You can retrieve the mode settings available for your device by using the appropriate functions listed at the beginning of this chapter.

mode is the display mode of the image. The default value is 'RGB16'. The following display modes are supported for the Image format pictures taken:
- 'RGB12': 4096 colors (12 bits per pixel)
- 'RGB16': 65536 colors (16 bits per pixel). Default value, always supported
- 'RGB': 16.7 million colors (24 bits per pixel)
For the JPEG data format images the following modes are supported:
- 'JPEG_Exif': JPEG Exchangeable image file format
- 'JPEG_JFIF': JPEG File Interchange Format
Note that there is variety between the devices and the supported formats.
size is the resolution of the image. The default value is (640, 480). The following sizes are supported, for example, in Nokia 6630: (1280, 960), (640, 480) and (160, 120).
flash is the flash mode setting. The default value is 'none'. The following flash mode settings are supported:
- 'none'No flash. Default value, always supported
- 'auto'Flash will automatically fire when required
- 'forced'Flash will always fire
- 'fill_in'Reduced flash for general lighting
- 'red_eye_reduce'Red-eye reduction mode
zoom is the digital zoom factor. It is assumed to be on a linear scale from 0 to the maximum zoom value allowed in the device. The default value is 0, meaning that zoom is not used.
exposure is the exposure adjustment of the device. Exposure is a combination of lens aperture and shutter speed used in taking a photograph. The default value is 'auto'. The following exposure modes are supported:
- 'auto'
  Sets exposure automatically. Default value, always supported
- 'night'
  Night-time setting for long exposures
- 'backlight'
  Backlight setting for bright backgrounds
- 'center'
  Centered mode for ignoring surroundings
white_balance can be used to adjust white balance to match the main source of light. The term white balance refers to the color temperature of the current light. A digital camera requires a reference point to represent white. It will then calculate all the other colors based on this white point. The default value for white_balance is 'auto' and the following white balance modes are supported:
- 'auto'
  Sets white balance automatically. Default value, always supported
- 'daylight'
  Sets white balance to normal daylight
- 'cloudy'
  Sets white balance to overcast daylight
- 'tungsten'
  Sets white balance to tungsten filament lighting
- 'fluorescent'
  Sets white balance to fluorescent tube lighting
- 'flash'
  Sets white balance to flash lighting
position is the camera used if the device, such as Nokia N95, has several cameras. In Nokia N95, the camera pointing to the user of the device is located in position 1, whereas the one pointing away from the user is located in position 0. The default position is 0.

If some other application is using the camera, this operation fails, with error SymbianError: KErrInUse. Invoking this function right after the device boot, might result in SymbianError: KErrNotReady error.

In some Nokia devices (e.g. in N95), to be able to get the highest possible size for the captured image, you need to:

switch to the landscape mode (see appuifw.app.orientation)
import the camera module
take the picture in the 'JPEG_Exif' format.

start_finder( callable[, backlight_on=1, size=main_pane_size])

Starts the camera viewfinder and binds a callback to receive Image format feed. When a new viewfinder frame is ready the callback is invoked with the Image as parameter.

The optional parameter backlight_on determines whether the device backlight is kept on when the camera view finder is in operation. By default, the backlight is on (1 = on, 0 = off).

The optional parameter size (of type tuple, e.g. (176, 144)) can be used to change the size of the Image received in the callback. The default size is the same as the application's main pane size.

Example view finder code:

>>> import appuifw
>>> import camera
>>> def cb(im):
...   appuifw.app.body.blit(im)
...
>>> import graphics
>>> appuifw.app.body=appuifw.Canvas()
>>> camera.start_finder(cb)
>>>

stop_finder( ): Stops the viewfinder.

release( ): Releases the camera - After invocation other applications can access the camera hardware.

start_record( filename, callable): Starts video recording. filename is the file where the video clip is saved and callable will be called with possible error code (int) and status information (see data in module camera) as parameter.
Prior calling this function, the view finder needs to be started.

stop_record( ): Stops the video recording.

Footnotes

... functions ^3.3: Descriptions for some of the values are based on information found in S60 SDK documentation [4]
... data ^3.4: For more information, see e.g. http://en.wikipedia.org/wiki/JPEG.

See About this document... for information on suggesting changes.

3.4 camera -- Interface for taking photographs and video recording

Footnotes

3.4 `camera` -- Interface for taking photographs and video recording