FlickrPanoGen
Copyright © 2011-2013 Giles Winstanley
Updated: 28 May 2013
Version: 1.1
Description
FlickrPanoGen is a utility for users of the Flickr image hosting website, which allows panoramic images hosted with Flickr to be viewed interactively. It supports equirectangular/spherical, cubic, and cylindrical panoramic projections. Interactive panoramas are launched from a link embedded in the text associated with an image, and are presented in a new browser window using a Java applet (PURE Player PRO).
To view FlickrPanoGen on the Flickr App Garden website, click here.
Requirements
- Panoramic image(s), hosted on Flickr.
- Flickr Pro account (optional, but recommended).
- Browser supporting Java 1.6 or later, and Javascript.
Note: panoramic images in cubic format should be in vertical format (as required by PURE Player PRO), with the following order (top-bottom): {front, right, back left, top, bottom}.
Usage
To configure FlickrPanoGen:
- Provide access to original version of Flickr image (not required, but recommended).
- Assign machine-tags to panoramic image.
- Add a link to the Flickr image description.
1. Providing access to images
Displaying panoramic scenes requires high resolution image files. Panoramic projections are warped/stretched to be viewed interactively, so compromises in quality become readily apparent. To get the best viewing experience it's recommended to make the original images available, which requires that you have a Flickr Pro account (free accounts cannot make originals available). It's also recommended that original image files be a minimum of 2048×1024 pixels for reasonable display in the interactive viewer.
(Note: be careful not to make them too big, due to memory limitations of the Java Virtual Machine; I generally upload equirectangular/spherical panoramas at 3072×1536 pixels, and request 96MB from the JVM.)
Flickr automatically resizes your uploaded images to provide a variety of resolutions, but even the large size is only 1024 pixels in the long dimension, making a poor source for panoramic viewing. However, if you want to test the application before committing to authentication, just go ahead, and it will use the largest available size for display.
Note also that the PURE Player PRO uses Java technology, which has different default memory allocation depending on your browser/computer. The most restrictive is Mac OS which by default limits the Java virtual machine to 64MB. To learn more about the memory requirements of the applet, visit this page.
Flickr authentication
This is the recommended way to make your panoramic images available, and follows the standard Flickr authentication mechanism.
- Ensure you are currently logged into Flickr.com.
- Authenticate your Flickr account for use with FlickrPanoGen.
If for some reason you would like to remove FlickrPanoGen authorization from your Flickr account, simply remove the permission on the Flickr account management page (click here).
2. Assigning machine-tags
Machine-tags on Flickr are just like ordinary tags, but have a specific format: n:t=v, where n=namespace, t=tag, v=value. FlickrPanoGen uses the panorama namespace, and has the following available tags:
| Machine-tag | Purpose | Type | Default |
|---|---|---|---|
| panorama:projection | Panorama projection type | One of: {equirectangular, cubic, cylindrical} | equirectangular |
| panorama:width | Width of panorama viewer (pixels). | integer | 800 |
| panorama:height | Height of panorama viewer (pixels). | integer | 450 |
| panorama:aspect | Aspect ratio of panorama viewer. | float | 1.778 (16/9 widescreen) |
| panorama:pan | Initial pan angle (i.e. left/right). | float | 0 |
| panorama:minpan | Minimum pan angle. | float | -180 |
| panorama:maxpan | Maximum pan angle. | float | 180 |
| panorama:tilt | Initial tilt angle (i.e. up/down). | float | 0 |
| panorama:mintilt | Minimum tilt angle. | float | -180 |
| panorama:maxtilt | Maximum tilt angle. | float | 180 |
| panorama:fov | Initial field-of-view (type as for panorama:fovtype). |
float | 90 |
| panorama:fovtype | Field-of-view type. | One of: {diagonal, horizontal, vertical} | diagonal |
| panorama:minfov | Minimum field of view (type as for panorama:fovtype). |
float | 20 |
| panorama:maxfov | Maximum field of view (type as for panorama:fovtype). |
float | 120 |
| panorama:map_minpan | Minimum pan angle for cylindrical projection mapping (equivalent to PURE Player <panoCylinder minPan="…">). |
float | -180 |
| panorama:map_maxpan | Maximum pan angle for cylindrical projection mapping (equivalent to PURE Player <panoCylinder maxPan="…">). |
float | 180 |
| panorama:map_mintilt | Minimum tilt angle for cylindrical projection mapping (equivalent to PURE Player <panoCylinder minTilt="…">). |
float | -180 |
| panorama:map_maxtilt | Maximum tilt angle for cylindrical projection mapping (equivalent to PURE Player <panoCylinder maxTilt="…">). |
float | 180 |
3. Adding Flickr image link
For each panoramic image link you want to create, you need to have available:
- Flickr UserID ("nsid")
- Flickr PhotoID
Your UserID is the same for all images associated with a specific account; the PhotoID is unique per image. For Flickr users who haven't setup an alias on their account, the easiest way to find these is to load an image page for which you want to display a pano viewer, then examine the URL in the browser address bar:
For those who have an account alias setup, the UserID is not displayed in the URL, so you have to find it another way. Simple right-click on your "buddy icon", copy the image location/address to the clipboard, then paste this into a text editor (e.g. TextEdit, Notepad, etc.). Your UserID is the name of this image file (omitting the file extension). For example, the address of my buddy icon is "66388786@N00.jpg".
Create a link in the description text of your Flickr image using the following format:
http://www.snaq.net/pano/FlickrPanoGen/launch.php?nsid=<UserID>&pid=<PhotoID>
The available URL parameters are as follows, and additional ones should be added to the end of the URL in the format: &<param>=<value>, as usual.
| Parameter | Purpose | Type | Default |
|---|---|---|---|
| nsid | Flickr UserID. | string | |
| pid | Flickr PhotoID. | string | |
| w | Width of viewer (pixels). | integer | 800 |
| h | Height of viewer (pixels). | integer | 450 |
| a | Aspect ratio of viewer (width / height). | float | 1.778 (16/9 widescreen) |
| fixed | Whether width/height are fixed, or just define aspect ratio. | boolean {true, false} | false |
| image | Flickr image size to use for main panoramic image (original size only for Flickr Pro account holders) |
string {medium, large, original}. | original/large |
| preview | Flickr image size to use for preview | string {none, small, medium, large}. | small |
| title | Title to display below panorama. | string | |
| mem | Amount of memory (MB) to try to allocate to Java Virtual Machine. | integer | 64 |
| debug | Whether to display debugging info. | boolean {true, false} | false |
Examples
Here is an example URL embedded in an image description:
Here are some example Flickr panoramic images:
Notes/Limitations
- The applet hosting page for panorama display is written in XHTML1.0-Strict format using the
<object…>tag (with the usual alternative version required for the ever-awkward Internet Explorer). - Currently works with equirectangular and cylindrical projection types.
- When creating cylindrical panoramic images, PURE Player remaps the projection as though it were a partial equirectangular projection, which might be different to expectation. In other words, where other viewers may project it as if wrapped around the inside of a vertical cylinder, PURE Player assumes it is wrapped around the inside of a sphere. If you encounter this issue it most likely manifests as unexpected vertical distortion/stretching. An easy way to fix this, if you use software such as PTGui, is to load your cylindrical pano and simply change over to equirectangular projection (without re-optimizing), then re-export the image.
- Results from Flickr API calls are currently cached for three hours to improve performance and reduce bandwidth.
Frequently Asked Questions
What size panoramic image should I upload?
Short answer: big enough for reasonable quality, but small enough to avoid occupying too much space.
Long answer: the JVM implementation on most computers has a limited amount of RAM space available for use, and this varies across operating systems and browsers. For example, Macintosh users generally have to make do with a comparatively small default memory allocation (often 64MB), whereas Windows users often benefit from a greater amount. If running a modern operating system with an up-to-date Java installation and browser, the amount of RAM allocated to Java should be configurable using the mem URL parameter previously mentioned. Manipulating images requires a lot of memory, and a simple calculation for memory requirements for PURE Player PRO for Java as used by FlickrPanoGen is:
RAM required (bytes) = (W × H × 4) + (X × Y × 12)
where:
- W = image width (pixels)
- H = image height (pixels)
- X = viewport width (pixels)
- Y = viewport height (pixels)
For example, for an equirectangular image of dimensions 3072×1536 using the default viewport (800×450):
RAM required = ((3072×1536×4) + (800×450×12)) / 1000000 = 23.2 MB (≡22.1 MiB)
Why do I just get the Immervision logo, yet my panorama never gets displayed?
You are probably trying to display a panorama which is too big. Large image files occupy a large amount of memory, and the Java Virtual Machine on most machines is only configured to allow up to a maximum limit, often around 60-70MB. As a guideline, my equirectangular/spherical panoramas are generally uploaded at a resolution of 3072×1536 pixels.
I just get a blank popup window showing in the centre of a grey screen; what's happened?
In all likelihood you are using a browser which has a bug and/or memory leak. For example, Firefox 3.x notoriously has memory leak issues, particularly when working with Java, so it's highly recommended to upgrade to the latest available releases of both your browser and Java environment.
How can I check if the generated panorama configuration is correct?
PURE Player Pro for Java requires a configuration file in IVP format (basically an XML configuration), which is used by the player to figure out how the panorama should be displayed in the Java applet. FlickrPanoGen generates this IVP configuration automatically based on the parameters supplied. If you would like to check the content of this generated content, copy/paste this URL into your browser location bar, and add the relevant parameters as you would to the regular link:
http://www.snaq.net/pano/FlickrPanoGen/gen-ivp.php?nsid=<UserID>&pid=<PhotoID>
For added convenience you may add the debug=true parameter to obtain extra information in the XML output. For example:
http://www.snaq.net/pano/FlickrPanoGen/gen-ivp.php?nsid=66388786@N00&pid=1234567890&debug=true
Support
Send all queries/issues/requests here, and if hoping to resolve issues, give as much relevant detail as possible to help diagnose any problems.
Change log
| 2011-05-23 (v1.0) |
|
|---|---|
| 2013-05-28 (v1.1) |
|