Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.motorola.iden.multimedia
Class DigitalCamera

java.lang.Object
  |
  +--com.motorola.iden.multimedia.DigitalCamera
public class DigitalCamera
extends java.lang.Object

DigitalCamera API

DigitalCamera API provides control over digital still-image camera. The API allows the developer to capture an image from the camera, as well as adjust certain aspects of the captured images such as the image resolution, orientation, and quality. The API provides several methods that fit into three categories:

  1. Controlling the camera
  2. Obtaining image from the camera
  3. Controlling the image properties

Controlling the Camera

In order to use the camera a reference to the DigitalCamera object must be obtained. This can be accomplished by calling the getDigitalCamera() method. There is only one instance of DigitalCamera per MIDlet. Therefore, all subsequent invocations of this method will return the same reference. When a reference to the DigitalCamera object is obtained for the very first time, the API will allocate around 80KB of memory for its internal use, which can significantly impact the amount of free memory available to the application. These buffers will not be released until the application is terminated.

The camera is enabled or disabled by calling the enableCamera(boolean enabled) method. The argument taken by this method determines whether to enable or disable the camera. The camera must be enabled before an image can be captured. Since enabling the camera increases the power consumption, it is the developer’s responsibility to disable the camera when exiting from a MIDlet. Due to the increased power consumption, the camera should be disabled when switching to other screens in the application that do not directly use the camera. The camera API exhibits the following characteristics that need to be taken into consideration when enabling or disabling the camera:

Invoking the method getSupportedResolutions() will return an integer array containing all the resolutions (in pixels) that are supported by the given camera. The resolutions are returned as an integer array in the format [w0, h0, w1, h1, ..., wn, hn], where each wx,hx pair is a width and height describing a supported resolution. Some cameras only support a single resolution, while others might support several. The resolutions are arranged in ascending order from the smallest image size to the largest. If the camera has been disconnected or disabled, this method will return an array of size 0.

Obtaining Image Data

There are three methods that can be used to obtain an image from the camera. Each one of these methods will throw a java.io.IOException if the camera has been disabled, disconnected from the phone, or the camera is not able to acquire an image for any other reason.

The method getPreviewImage() is used to obtain a preview image from the camera. This image can used to provide a real-time digital viewfinder, so that the MIDlet can display the image visible by the camera. This method will return an Image object that can be drawn on the screen. In order to improve the memory performance, this method will always return a reference to the same immutable Image object. Only the content of the Image object will change on the subsequent calls. If the preview image has been rotated the width and the height of the preview image will be adjusted accordingly. Therefore, if the application needs to preserve several preview images at the same time, it is the application's responsibility to create a new Image object from the reference returned by this method. The size of the preview image is determined by the implementation and cannot be changed. It will be the largest image supported by the given camera that can entirely fit on the screen. The most common use for getPreviewImage() would be in a loop that continuously captures a preview image from the camera and then draws that image on the screen. Using this approach it is possible to create a digital viewfinder with a refresh rate of few frames per second (depending on the camera). The dithering algorithm used for the viewfinder image will also affect the refresh rate for the viewfinder (see next section).

The method captureImage() is used to capture an image from the camera. This method acquires an image from the camera, encodes the image using the JPEG encoder, and returns the image as a byte array. This byte array can then be stored in the local file system or transferred to a desktop computer. The byte array contains the image in the JPEG format (complete with all the necessary headers) that can be viewed with any standard JPEG viewer or displayed on the phone if the JPEG decoder is available.

The method getData() is used to obtain un-encoded image data from the camera. This data is returned as a byte array and is in the format that is usable by the Image.createImage() method. It is up to the implementation to decide on the color depth for the image data (8-bit, 16-bit, or 24-bit depending on the camera). Each implementation may also choose to ignore the width and height parameters for the captured image. If those parameters are ignored, then the image returned by the getData() method will have the same size as the viewfinder image. This method can be used to provide thumbnails for JPEG images that are too big to decode and/or display on the phone.

Controlling the Image Properties

In addition to the methods used to obtain an image from the camera, the API provides several methods for obtaining and modifying image properties.

The method setSize(int width, int height) is used to specify the resolution for the captured images. The specified width and height parameters must match the values returned by the getSupportedResolutions() method. The setSize() method will only affect captureImage() and getData() methods. The current image width and height can be obtained by calling getWidth() and getHeight() respectively. The default resolution is the highest resolution that is supported by the camera driver and is set automatically when the camera is enabled.

The method setQuality(int quality) is used to specify the JPEG image quality. Therefore, it only affects captureImage() method. The image quality is a value between 0 and 100 (inclusive), which indicates the compression level to be used by the JPEG encoder. Lower values indicate higher compression level and therefore result in lower-quality images. Similarly, higher values indicate lower compression level and result in higher-quality images. Note that higher quality images will be larger (in bytes) than the lower quality ones. The current image quality can be retrieved by invoking getQuality() method. The default image quality is 60, which provides a good compromise between the image quality and the image data size. Not all cameras support user-selectable image quality. For the cameras that do not provide that support, this method will be ignored and a default image quality value will be used. Additionally, some cameras might only support a limited number of image quality settings. In those cases, the implementation will decide how the values are mapped to the camera’s capabilities.

The method setViewfinderDithering(int dithering) is used to specify dithering algorithm for the preview image. A dithering algorithm is used to improve the quality of a 24-bit image that is displayed on an 8-bit display. For displays with higher bit depths (16-bit or higher) the dithering algorithm will have no effect on the image. The setViewfinderDithering() method takes a single parameter which specifies the dithering algorithm to use for the images returned by the getPreviewImage() method. The parameter can have one of three values: DITHERING_NONE, DITHERING_8BIT_ORDERED, and DITHERING_8BIT_FLOYD_STEINBERG, which correspond to no dithering, ordered dithering, and Floyd-Steinberg dithering algorithms respectively. The default value is DITHERING_8BIT_ORDERED. The dithering algorithm affects the amount of time needed to capture a preview image - this in turn affects the maximum refresh rate for the viewfinder. The Floyd-Steinberg algorithm (DITHERING_8BIT_FLOYD_STEINBERG) produces the best image quality, but at the same time takes the longest time, which results in high quality viewfinder image with low refresh rate. On the other hand, no dithering (DITHERING_NONE) will produce low quality viewfinder image with high refresh rate. The ordered dithering algorithm (DITHERING_ORDERED) will fall in between no dithering and Floyd-Steinberg algorithm in terms of both image quality and refresh rate. The method getViewfinderDithering() will return the current dithering algorithm used for the viewfinder image.

The method setLightMode(int ligthMode) is used to specify the light mode for the camera. The lightMode parameter can be used to adjust the image according to the light conditions. This method affects images returned by captureImage(), getPreviewImage(), and getData() methods. The possible values for the lightMode parameter are DigitalCamera.LIGHT_NORMAL and DigitalCamera.LIGHT_LOW. The setting LIGHT_NORMAL is used for normal light condition when the subject is well lit. The setting LIGHT_LOW is used for low light conditions. Using the low light setting will increase the time to obtain an image from the camera - as a result the viewfinder frame rate will be lower. The default value for the light mode is LIGHT_NORMAL. The method getLightMode() is used to retrieve the current light mode setting of the camera.

The method setBrightness(int brightness) is used to specify the image brightness. This method affects images returned by captureImage(), getPreviewImage(), and getData() methods. The brightness is specified as a value between 0 and 100 (inclusive). Lower brightness values result in darker images, while higher brightness values result in brighter images. The default brightness value is 50. The brightness setting can be used along with the light mode setting. Increasing the image brightness while at the same time switching the camera to low-light mode will result in the best images under low-light conditions. The implementation might not support all 100 distinct brightness values and might instead chose to map a range of values to a single setting. The method getBrightness() is used to retrieve the current brightness value for the camera.

The method setOrientation(int orientation) is used to specify the orientation of the camera image. The orientation parameter is used to adjust the image so that it remains upright regardless of whether the camera is pointing towards or away from the user. This method affects captureImage(), getData(), and getPreviewImage() methods. The possible values for the image orientation are DigitalCamera.ORIENTATION_FLIP_ON and DigitalCamera.ORIENTATION_FLIP_OFF. The default value is ORIENTATION_FLIP_OFF meaning the image will be in the upright orientation when the camera is facing the user. The method getOrientation() is used to retrieve the current value of the image orientation.

The method setViewfinderRotation() is used to specify the rotation angle of the preview image. This method will only affect the images returned by getPreviewImage() method. The method takes a single argument that can have one of the following values: ROTATION_NONE, ROTATION_90, ROTATION_180, and ROTATION_270. These arguments will respectively rotate the viewfinder by 0, 90, 180, and 270 degrees clockwise. The effects of this method are not cumulative (i.e. calling setViewfinderRotation(ROTATION_90) twice, will rotate the image 90 degrees clockwise). If a camera does not support a particular rotation angle, this method will be ignored. Due to hardware constraints, rotating the image may temporarily cause the next few frames to have incorrect appearance (they will be rotated correctly, but might have incorrect horizontal flip). The method getViewfinderRotation() is used to retrieve the current setting for the viewfinder rotation. The table below illustrates the effects of image orientation and viewfinder rotation on the getPreviewImage() method.

Code Example

The following code example will open the camera, capture an image of 640 by 480 pixels with low quality and flipped orientation, and then close the camera.

 byte[] imageData;
 try {
 	 // get a reference to the camera
 	 DigitalCamera digicam = DigitalCamera.getDigitalCamera();
 	 // open the camera
 	 digicam.enableCamera(true);
 	 // set the image resolution to 640 by 480
	 digicam.setSize(640, 480);
	 // specify a low image quality
 	 digicam.setQuality(25);
	 // set the desired image orientation
	 digicam.setOrientation(DigitalCamera.ORIENTATION_FLIP_ON);
	 // capture the image and get the JPEG data
 	 imageData = digicam.captureImage();
 	 // disable the camera
 	 digicam.enableCamera(false);
 }
 catch (java.io.IOException e) { 
 	 // process the Exception 
  }

MOTOROLA and the Stylized M Logo are registered trademarks of Motorola, Inc. Reg. U.S. Pat. & Tm. Off.
© Copyright 2001-2003 Motorola, Inc. All Rights Reserved.

Field Summary
static int DITHERING_8BIT_FLOYD_STEINBERG
          Specifies dithering algorithm for the viewfinder image.
static int DITHERING_8BIT_ORDERED
          Specifies dithering algorithm for the viewfinder image.
static int DITHERING_NONE
          Specifies dithering algorithm for the viewfinder image.
static int LIGHT_LOW
          Specifies light mode for the camera.
static int LIGHT_NORMAL
          Specifies light mode for the camera.
static int ORIENTATION_FLIP_OFF
          Orientation for the camera image.
static int ORIENTATION_FLIP_ON
          Orientation for the camera image.
static int ROTATION_180
          Specifies rotation for the viewfinder.
static int ROTATION_270
          Specifies rotation for the viewfinder.
static int ROTATION_90
          Specifies rotation for the viewfinder.
static int ROTATION_NONE
          Specifies rotation for the viewfinder.
 
Method Summary
 byte[] captureImage()
          Captures an image and returns a byte array containing JPEG image data.
 void enableCamera(boolean enabled)
          Enables or disables the camera.
 int getBrightness()
          Returns the brightness setting for the camera.
 byte[] getData()
          Returns byte array containing image data.
static DigitalCamera getDigitalCamera()
          Returns a reference to the DigitalCamera.
 int getHeight()
          Returns the height of the captured images.
 int getLightMode()
          Returns the light mode of the camera.
 int getOrientation()
          Returns the current image orientation.
 Image getPreviewImage()
          Returns a preview image from the camera.
 int getQuality()
          Returns the current image quality index.
 int[] getSupportedResolutions()
          Returns image resolutions supported by the camera.
 int getViewfinderDithering()
          Gets the current dithering mode of the viewfinder.
 int getViewfinderRotation()
          Gets the current rotation of the viewfinder.
 int getWidth()
          Returns the current width of the captured images.
 void setBrightness(int brightness)
          Sets the image brightness for the camera.
 void setLightMode(int lightMode)
          Sets the light mode for the camera.
 void setOrientation(int orientation)
          Specifies the orientation of the image.
 void setQuality(int imgQ)
          Specifies the image quality of a captured image.
 void setSize(int width, int height)
          Sets the size of the captured images to the specified width and height.
 void setViewfinderDithering(int dithering)
          Specifies the dithering mode for the viewfinder.
 void setViewfinderRotation(int rotation)
          Specifies the rotation for the viewfinder.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ORIENTATION_FLIP_OFF

public static final int ORIENTATION_FLIP_OFF
Orientation for the camera image. With this orientation, the image appears upright when the camera is pointing in the direction of the person holding the camera.

See Also:
Constant Field Values

ORIENTATION_FLIP_ON

public static final int ORIENTATION_FLIP_ON
Orientation for the camera image. With this orientation, the image appears upright when the camera is pointing in the direction away from the person holding the camera.

See Also:
Constant Field Values

ROTATION_NONE

public static final int ROTATION_NONE
Specifies rotation for the viewfinder. This rotation value displays the viewfinder such that it is rotated 0 degrees.

See Also:
Constant Field Values

ROTATION_90

public static final int ROTATION_90
Specifies rotation for the viewfinder. This rotation value displays the viewfinder such that it is rotated 90 degrees clockwise.

See Also:
Constant Field Values

ROTATION_180

public static final int ROTATION_180
Specifies rotation for the viewfinder. This rotation value displays the viewfinder such that it is rotated 180 degrees clockwise.

See Also:
Constant Field Values

ROTATION_270

public static final int ROTATION_270
Specifies rotation for the viewfinder. This rotation value displays the viewfinder such that it is rotated 270 degrees clockwise.

See Also:
Constant Field Values

DITHERING_NONE

public static final int DITHERING_NONE
Specifies dithering algorithm for the viewfinder image. No dithering.

See Also:
Constant Field Values

DITHERING_8BIT_ORDERED

public static final int DITHERING_8BIT_ORDERED
Specifies dithering algorithm for the viewfinder image. Ordered dithering.

See Also:
Constant Field Values

DITHERING_8BIT_FLOYD_STEINBERG

public static final int DITHERING_8BIT_FLOYD_STEINBERG
Specifies dithering algorithm for the viewfinder image. Floyd-Steinberg dithering.

See Also:
Constant Field Values

LIGHT_NORMAL

public static final int LIGHT_NORMAL
Specifies light mode for the camera. Normal light mode.

See Also:
Constant Field Values

LIGHT_LOW

public static final int LIGHT_LOW
Specifies light mode for the camera. Low light mode.

See Also:
Constant Field Values
Method Detail

captureImage

public byte[] captureImage()
                    throws java.io.IOException
Captures an image and returns a byte array containing JPEG image data. The size of the image corresponds to the size specified with the setSize() method. Due to the data size and the portability of the format, this data is best suited for storing and sharing of the images.

Returns:
byte array containing JPEG image data.
Throws:
java.io.IOException - if unable to capture an image or the camera is disabled.

enableCamera

public void enableCamera(boolean enabled)
                  throws java.io.IOException
Enables or disables the camera. The camera must be enabled before it can be used. When the camera is enabled, it is initialized and ready to capture images. The camera must be disabled when exiting or suspending the MIDlet. It is also recommended to disable the camera when transitioning the application to another screen that doesn't use the camera. Enabling the camera that is already enabled has no effect; similarly disabling already disabled camera has no effect. The camera will power down automatically after 60 seconds of inactivity. See section 'Controlling the Camera' in the class description for details regarding power and memory consumption when enabling the camera.

Parameters:
enabled - true to enable the camera, false to disable.
Throws:
java.io.IOException - if unable to enable/disable the camera.

getDigitalCamera

public static DigitalCamera getDigitalCamera()
Returns a reference to the DigitalCamera. Each MIDlet can only have one reference to the camera. Therefore, subsequent calls to getDigitalCamera() within a MIDlet will return the same reference. When a reference to the DigitalCamera object is obtained for the very first time, the API will allocate around 80KB of memory for its internal use, which can significantly impact the amount of free memory available to the application. These buffers will not be released until the application is terminated.

Returns:
reference to the digital camera.

getData

public byte[] getData()
               throws java.io.IOException
Returns byte array containing image data. This image data is a format that can be used to create an Image object using Image.createImage() method.

Returns:
byte array containing raw image data.
Throws:
java.io.IOException - if unable to capture image or the camera is disabled.

getHeight

public int getHeight()
Returns the height of the captured images.

Returns:
height of the captured image.

getQuality

public int getQuality()
Returns the current image quality index. The returned valued will be between 0 and 100.

Returns:
image quality.

getWidth

public int getWidth()
Returns the current width of the captured images.

Returns:
width of the captured image.

getOrientation

public int getOrientation()
Returns the current image orientation.

Returns:
current orientation of the image.

getPreviewImage

public Image getPreviewImage()
                      throws java.io.IOException
Returns a preview image from the camera. The returned image is returned as an Image object. In order to improve the memory performance, this method will always return a reference to the same immutable Image object. Only the content of the Image object will change on the subsequent calls. If the preview image has been rotated the width and the height of the preview image will be adjusted accordingly. Therefore, if the application needs to preserve several preview images at the same time, it is the application's responsibility to create a new Image object from the reference returned by this method. The size of the image (its dimensions) depends on the available camera, and is the largest image from the camera that fits entirely on the screen (without scrolling). The preview image can be used to create a viewfinder mode (preview mode).

Returns:
a reference to an Image object containing the preview image.
Throws:
java.io.IOException - if not able to acquire preview image, or the camera is disabled.

getSupportedResolutions

public int[] getSupportedResolutions()
Returns image resolutions supported by the camera. The resolutions are returned as an integer array in the format [w0, h0, w1, h1, ..., wn, hn], where each wx, hx pair is a width and height describing supported resolution. Some cameras only support single resolution, while other might support several. The resolutions are ordered in ascending order from the smallest image size to the largest. If the camera has been disconnected or disabled, this method will return an array of size 0.

Returns:
int array containing image resolutions supported by the camera.

setQuality

public void setQuality(int imgQ)
                throws java.lang.IllegalArgumentException
Specifies the image quality of a captured image. The image quality only affects JPEG images ie. the images returned by captureImage(). The image quality is a value between 0 and 100, with 100 representing highest image quality. Lower quality images take up less space than high quality ones. The default value for image quality is 60.

Parameters:
imgQ - Image quality index. Integer value between 0 and 100.
Throws:
java.lang.IllegalArgumentException - if the specified image quality is < 0 or > 100.

setSize

public void setSize(int width,
                    int height)
             throws java.lang.IllegalArgumentException
Sets the size of the captured images to the specified width and height. Once the size has been set, all images returned by captureImage() and getData() will have the specified size. The default image size for a camera is the largest resolution supported by that camera. This method does not affect images returned by getPreviewImage() method.

Parameters:
width - desired width of the image.
height - desired height of the image.
Throws:
java.lang.IllegalArgumentException - if the specified image width or height does not much any of the resolutions returned by getSupportedResolutions().

setOrientation

public void setOrientation(int orientation)
                    throws java.lang.IllegalArgumentException
Specifies the orientation of the image. This method affects the captureImage(), getData(), and getPreviewImage() methods. An image can have one of two orientations: normal and flipped.

Parameters:
orientation - orientation of the image. The values are either ORIENTATION_FLIP_OFF or ORIENTATION_FLIP_ON.
Throws:
java.lang.IllegalArgumentException - if the specified image orientation other than ORIENTATION_FLIP_OFF or ORIENTATION_FLIP_ON.

setViewfinderRotation

public void setViewfinderRotation(int rotation)
                           throws java.lang.IllegalArgumentException
Specifies the rotation for the viewfinder. The value for the rotation can be one of the following values: ROTATION_NONE, ROTATION_90, ROTATION_180, ROTATION_270. The viewfinder rotation is not cumulative (ie. calling setViewfinderRotation(ROTATION_90) twice, will rotate the viewfinder image by 90 degrees clockwise). This method does not affect the rotation of images returned by captureImage() or getData() methods. The default value for the viewfinder rotation is ROTATION_NONE. Some digital cameras might not support all rotation values, in which case invoking this method will not produce any results.

Parameters:
rotation - rotation value for the viewfinder.
Throws:
java.lang.IllegalArgumentException - if the specified viewfinder rotation is invalid.

getViewfinderRotation

public int getViewfinderRotation()
Gets the current rotation of the viewfinder. The value returned by this method is one of the four possible viewfinder orientations.

Returns:
the current rotation of the viewfinder.

setViewfinderDithering

public void setViewfinderDithering(int dithering)
                            throws java.lang.IllegalArgumentException
Specifies the dithering mode for the viewfinder. The parameter can have one of the following values: DITHERING_NONE, DITHERING_8BIT_ORDERED, or DITHERING_8BIT_FLOYD_STEINBERG. A dithering algorithm is used to improve the quality of a 24-bit image that is displayed on an 8-bit display. For displays with higher bit depths (16-bit or higher) the dithering algorithm will have no effect on the image. The dithering mode affects only the images returned by the getPreviewImage() method. The default value for the dithering mode is DITHERING_8BIT_ORDERED.

Parameters:
dithering - dithering mode for the viewfinder.
Throws:
java.lang.IllegalArgumentException - if the specified

getViewfinderDithering

public int getViewfinderDithering()
Gets the current dithering mode of the viewfinder. The value returned by this method can have one of the following values: DITHERING_NONE, DITHERING_8BIT_ORDERED, DITHERING_8BIT_FLOYD_STEINBERG.

Returns:
the current dithering mode of the viewfinder.

setLightMode

public void setLightMode(int lightMode)
                  throws java.lang.IllegalArgumentException
Sets the light mode for the camera. The light mode is specified by the paramter and can have one of the following values: LIGHT_NORMAL, and LIGHT_LOW. LIGHT_NORMAL is used for normal conditions with plenty of light available. LIGHT_LOW setting is used for low light conditions. The default light mode is LIGHT_NORMAL.

Parameters:
lightMode - the light mode for the camera.
Throws:
java.lang.IllegalArgumentException - if the specified parameter is not valid.

getLightMode

public int getLightMode()
Returns the light mode of the camera. The value returned by this methods is either LIGHT_NORMAL or LIGHT_LOW.

Returns:
the light mode of the camera.

setBrightness

public void setBrightness(int brightness)
                   throws java.lang.IllegalArgumentException
Sets the image brightness for the camera. The specified parameter is a value between 0 and 100, with 100 representing the highest image brightness. The default value for the brightness is 50. This setting affects images returned by getPreviewImage(), captureImage(), and getData() methods.

Parameters:
brightness - image brightness. Acceptable values are between 0 and 100.
Throws:
java.lang.IllegalArgumentException - if the specified brightness is less than 0 or greater that 100.

getBrightness

public int getBrightness()
Returns the brightness setting for the camera. The returned value will be between 0 and 100.

Returns:
brightness setting.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD