PTViewerME2 Tutorial - Part 3

Given the download statistics for the sample posted in the first part, there is not much interest for a Java VR viewer for cellphones and I should head out to buy a device which can play PangeaVR, the panorama viewer for the iPod Touch and iPhone that got off to a stellar start. No iPhone for me: here in Canada consumers are punished by the Rogers/Fido monopoly. Besides, it’s not my kind of phone. But first, let’s wrap up on PTViewerME2, a wonderful OpenSource panorama viewer whose sole fault is that it relies on Java. In this third and last part, we look into the details of what we quickly did in the second part, and expand on configuring content for PTViewerME2.

default.html

The file default.html controls the VRs in the JAR. Each VR has an entry in an <embed></embed> tag and can be customized with the following parameters:

Parameter	Description
name	name listed for the VR in the cellphone’s navigation
src	source file for the VR (.mov)
icon	references the icon to be displayed in the cellphone’s navigation, see discussion of icons below
order	lists the order of the cubefaces in the VR file. For QTVR this is order=”0,2,1,3,4,5″
autopan	starts panning as soon as the VR is loaded, at the defined speed. A positive value turns counterclockwise
fov, fovmax, fovmin	field of view (or zoom), in degrees. Sensible values are between 50° and 120°
pan, panmax, panmin	Range from -180° ro +180°. The QTVR must still be a full cube – pad the image to equirectangular size before converting to QTVR.
tilt, tiltmax, tiltmin	Eange from -90° (looking down to the nadir) to +90° (looking up to the zenith). The QTVR must still be a full cube, even if only displaying a cylinder.

The panorama

There is a utility that comes with PTViewerME2, but I did not use it. What worked for me was to create a standard QTVR and use the order parameter.

On most cellphones, RAM is still a precious commodity and since the VR is decoded in RAM, specifically in heap memory. The QTVR needs to be carefully crafted to avoid an out of memory error.

Mainstream phones today have about 2MB of heap memory. Aim for 256px cubefaces with a JPG compression quality to keep the size of the QTVR at 100Kb. Even so zenith and nadir will be downscaled to 128px by Java’s 3D engine. Other phones may support larger files, YMMV.

Icons

Icons can be used both within the MIDlet to display the individual VR when choosing, and for the MIDlet itself. Recommended format is PNG 8-bit. Store the icons inside the MIDlet, e.g. in an icons/ folder, and reference them from default.html, MANIFEST.MF, and the JAD deployment file. Unfortunately there is no standard or even convention for the icon’s size. It varies from manufacturer to manufacturer. The ideal size varies and depends from the targeted cellphone. For best compatibility, try 16×16 pixels. Your phone’s mileage may vary.

File and size of the JAR (Java Archive)

There is a size limit for the JAR. To keep it simple, put a single VR and a single MIDlet, even if it is possible to reference many of them inside the same JAR. The critical path when deploying Java applications is that Java is not Java – every device has its quirks and compatibility issues. By keeping things simple we increase the probability that they work on a wider range of phones.

JAD Java Deployment File and MANIFEST.MF – the nitty gritty detail

Deploying Java applications to a cell phone is a major pain because of these two files. Much of their content must be synchronized. THe MANIFEST.MF goes inside the JAR. The two files are particularly important for signed archives, to make sure they have not been tampered.

MANIFEST.MF

MANIFEST.MF is used to compile the JAR:

Manifest-Version: 1.0
MicroEdition-Configuration: CLDC-1.1
MIDlet-Name: VR-Demo
Created-By: 1.4.2_05 (Sun Microsystems Inc.)
MIDlet-Permissions: javax.microedition.io.Connector.file.read
MIDlet-Vendor: You
MIDlet-1: VR-Demo, icon.png, PTViewerME
MIDlet-Version: 1.0
MicroEdition-Profile: MIDP-2.0

The important line is MIDlet-1. It’s first argument is the name to display on the phone. It is followed by an optional icon (URL relative to the JAR’s top level) and the name of the class inside the JAR that will be started  when the user activate the Midlet. A JAR archive can contain multiple executable classes and it is possible to specify many MIDlets inside the same JAR – just increment the counter and add another line: MIDlet-2, MIDlet-3 …

Midlet-Vendor can be any name – we are not cryptographically signing the MIDlet.

JAD – deployment information

The JAD file is kept externally to the JAR and used during deployment. Here is an example:

MIDlet-1: VR-Demo, icon.png, PTViewerME
MIDlet-Jar-Size: 82978
MIDlet-Jar-URL: VR-Demo.jar
MIDlet-Name: VR-Demo
MIDlet-Permissions: javax.microedition.io.Connector.file.read
MIDlet-Vendor: You
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.1
MicroEdition-Profile: MIDP-2.0

Important: note that almost all lines are identical to MANIFEST.MF. The new lines are the MIDlet-Jar-Size, which you learn to set in part 2, and the MIDlet-Jar-URL, relative to the JAD file.

Conclusions

Deploying Java applications to a cellphone is not easy. Even if PTViewerME2 is a fine applications, it may have problems running on specific phones. I’ve found that on my Nokia 5200, some VR display nicely while others show seams and darker cubefaces. In my exchanges with Professor Dersch he mentioned that this can be due to incompatibilities of the Java Virtual Machine. In his experience, the most time consuming part in supporting a Java applications are incompatible Java Virtual Machines (JVM) on different phone models.

This concludes for now my foray in the realm of PTViewerME2 / Java. I can now illustrate the concept of a VR with my cheap cell phone.