Image Capture in V980/E1000

November 23, 2004

WHITE PAPER

Image Capture in V980/E1000

By Motocoder Staff

How do you capture an image from your J2ME application? The newly released CLDC1.1 based handsets like V980 and E1000 support the capture of displayed video on the phones screen from the application using the Mobile Media API [1]. This newsletter describes the various steps of capturing an image from a J2ME application. Capturing an image from an application involves three steps. Firstly, displaying the video on a canvas or a form; secondly, taking the snapshot of the displayed image; thirdly saving the captured image. In this newsletter we will first go through each of these steps (highlighting the API methods involved), then we will give brief description of the sample application, implementing image capture and finally we will highlight the steps for taking the snapshot using the attached sample applications and possible issues that a user may encounter. The complete source code for the sample applications along with jar and jad is attached in a separate zip file as well.

Video Display on Canvas or Form

The video feed from the camera can be feed to the canvas or form so that user can see the picture of what he is going to take snapshot. Following operations are involved in displaying the video on the canvas or form. 1) Creation of player object for obtaining the VideoControl object.
Player p = Manager.createPlayer("capture://video");

2) Obtaining the video control object from the player object, for capturing video.
VideoControl vc = (VideoControl)p.getControl("VideoControl");

3) Video can be displayed in two modes- USE_DIRECT_VIDEO and USE_GUI_PRIMITIVE. USE_DIRECT_VIDEO is used for displaying the video directly on canvas. USE_GUI_PRIMITIVE mode is used to obtain the GUI primitive (Item), where the GUI of video control will be displayed. These modes are initialized by using the initDislayMode() of GUIControl. a. For displaying the video on the canvas:
vc.initDisplayMode(VideoControl.USE_DIRECT_VIDEO, this); // this refers to the current instance of the canvas object.

b. For displaying video on the form:

frm.append((Item)vc.initDisplayMode(vc.USE_GUI_PRIMITIVE, null));//frm refers to the form in use.

4) After setting the appropriate size of display for video, the player can be started.
vc.setDisplayFullScreen(true); //setting the display are for video to be full screen.

vc.setVisible(true); //Used only if the mode to display the video is USE_DIRECT_VIDEO. p.start(); //starting the player

Snapshot of the Image

The snapshot of the displayed image on canvas/form can be taken by using the getSnapshot(String imageType) method of VideoControl. This method returns a byte array containing the snapshot of the captured image in the feature and format defined by the imageType parameter of getSnapshot(). The supported image formats for the getSnapshot() can be obtained from the System.getProperty() with video.snapshot.encodings as key. If null is specified for imageType the default features and formats are used (encoding=jpeg&width=176&height=144). At present the various values of imageType supported by the V980 and E1000 are encoding=jpeg&width=160&height=120 encoding=jpeg&width=176&height=144 encoding=jpeg&width=320&height=240 encoding=jpeg&width=640&height=480 encoding=jpeg&width=1280&height=960(not supported in V980).

Saving the Captured Image

The byte array obtained from the getSnapshot() needs to be saved. The easiest way to save this array is to transfer this byte array containing image to the PC from the serial port and have a serial port listener application listening on the serial port. Following steps are involved in transferring the image to PC : 1) Obtaining the CommConnection Object: This is achieved by opening the CommConnection:
CommConnection commConn = (CommConnection)Connector.open("comm:" + port + baudrate); //The baudrate used for transfer should be same as the baudrate of the receiving application running on PC and port should be same serial port on which the application is listening.

2) Transferring the Image to PC: After serial port connection has opened successfully, the captured image can be transferred to PC, by writing the image byte array to the output stream. Before transferring the byte array, the receiving application should be started. The listener application on PC can use the Java Communication APIs [2] for receiving the image data. On receiving the image data from the J2ME application, the listener will know about it and it can read from input stream the image data and use this data to create an image file, representing the capture image from the phone.

Image Capture Sample Applications

There are three sample applications- two of them are the midlet suites one having the Canvas as displayable (ImageCaptureCanvasSuite) and another having the form as displayable (ImageCaptureFormSuite). Please note that both of these midlet suites provide the same functionality of

capturing image and sending the captured data to PC. The third sample application is a J2SE based application (SerialPortRead.java) for receiving the captured image, send by ImageCaptureCanvasSuite or ImageCaptureFormSuite. 1) ImageCaptureCanvasSuite: This midlet suite contains ImageCaptureCanvasMIDlet midlet and ImageCaptureCanvas class. ImageCaptureCanvas extends the Canvas class and provides the functionality of- displaying the video on a canvas, capturing the image from displayed video and transferring the image data to PC. The ImageCaptureCanvasMIDlet displays the ImageCaptureCanvas object. 2) ImageCaptureFormSuite: This midlet suite contains ImageCaptureFormMIDlet midlet. ImageCaptureFormMIDlet provides the functionality of- displaying the video on a form, capturing and and transferring the image data to PC. 3) SerialPortRead: This is a J2SE based application. It receives the image data send by the ImageCaptureCanvas or ImageCaptureForm and saves the image data as a jpeg file on the PC. In order to compile the source file (SerialPortRead.java) the Java Communication API needs to be downloaded. The Java communication API can be downloaded and installed from: http://java.sun.com/products/javacomm/downloads/index.html. Please follow the appropriate installation instructions, available with the API. The above mentioned applications (ImageCaptureCanvasSuite, ImageCaptureFormSuite and SerialPortRead) are present as part of attached zip file (ImageCapture.zip). The jar, jad and source code of the applications are organized in the following hierarchy: Sample Application-1(ImageCaptureCanvasSuite) 1) ImageCaptureCanvasSuite.jad-- imagecapture/canvas 2) ImageCaptureCanvasSuite.jar-- imagecapture/canvas 3) ImageCaptureMIDlet.java-- imagecapture/canvas 4) ImageCaptureCanvas.java-- imagecapture/canvas Sample Application-2(ImageCaptureFormSuite) 1) ImageCaptureFormSuite.jad-- imagecapture/form 2) ImageCaptureFormSuite.jar-- imagecapture/form 3) ImageCaptureFormMIDlet.java-- imagecapture/form SampleApplication-3(SerialPortRead) 1) SerialPortRead.java-- imagecapture/pcapplication 2) SerialPortRead.class-- imagecapture/pcapplication

Taking the snapshot using the Sample Applications

1) Initially the image capture application will be in the video display mode. Once the image to be captured is selected, press CAPTURE to take snapshot. 2) Press OK (after selecting the appropriate option) on the screen asking you that if you want to Start Recording. 3) Press SAVE to save the captured image. 4) Unplug the RS 232 cable from your phone, if it is connected. Then press OPEN to open serial port connection with PC. 5) Press OK on the screen that asks you for making a local connection on COM1 port. 6) Start the SerialPortRead application on your PC. 7) Plug the RS 232 cable to phone (the cable should connect to PC on COM1 port at one end and phone on other end).

8) Once the image has completely transferred to PC, press BACK to again start the image capture or press EXIT to exit from the image capture application. Possible Issues in Using the Sample Applications Issue: No display appears on the form based application. Solution: Press the down navigation key so that display can appear. Issue: Application hangs while pressing the transfer Solution: Try to unplug the RS232 cable and again connect it firmly to the phone.

Conclusion
In this newsletter we have covered the various steps for taking the snapshot from a J2ME application and saving the captured image to PC. We have also presented the sample applications along with the source code to take the snap shot.

References
1) Mobile Media API (JSR135) version 1.1. 2) Java Communications API http://java.sun.com/products/javacomm/index.jsp.