• Subscribe

    Subscribe to This Week In Panospace by eMail.
    Subscribe in a reader
  • License

    Creative Commons License
    This work is © 2008-2012
    by Yuval Levy
    and licensed under a
    Creative Commons License.
  • Entries

    July 2008
    M T W T F S S
    « Jun   Aug »
  • Archives

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.


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 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 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.


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.

One Response

  1. Thanx for your tutorial Yuval.
    Today has been my first day of research into the concept of VR on a phone and I’ve found your three tutorials to be some of the best reading as yet.
    I’ve been able to follow them and get the VR’s to run on my phone – very nice, but only by following your instructions to the T.
    I don;t yet fully understand the whole process.
    Quick question – I want to add sound to a interactive .mov and send it via MMS to another phone – is this possible with the standalone files you described (I’ve don;t want to go through all that detail coding if it’s not possible.)

    Thx for your work – again …

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s