Working with the Ladybug Spherical Viewer for iOS

Last Revision Date: 3/22/2016

This article explains how to add images and folders to the Ladybug Spherical Viewer for iOS, and how to launch the viewer from other applications. 

About the Ladybug Spherical Viewer for iOS

The Ladybug Spherical Viewer application can be used on iOS devices such as the iPad, iPhone and iPod Touch. This application allows panoramic JPEG images to be viewed on these devices, and makes use of the pan, tilt and zoom capabilities that are standard features of multi-touch and accelerometer-based image displays.  The Ladybug Viewer application can be downloaded for free from the Apple iTunes App Store.

Adding Images to the Ladybug Spherical Viewer

The Viewer comes with a set of image URLs that have been previously added. You can also add your own.

Preparing Images

The Viewer requires images to be in one of the following formats:

    • Equirectangular panoramic images in JPEG format. You can output this format by using the LadybugCapPro application (included with the Ladybug SDK). On the Stream Processing toolbar, select Panoramic(JPG) from the Output Typelistbox. On the Output Size listbox, the recommended output size is 2048x1024. In this case, images will be 2 megapixels.
    • Cube-mapped panoramic images in JPEG format. This format consists of 6 square images that construct a cube. It is ideal for high-resolution imaging because each image is 1024x1024 resolution, which yields 6 megapixels in the entire image. Six files are required; file names must be in the format “yourfilename_*.jpg” where * is 0 to 5.
    • Sequential equirectangular panoramic images in JPEG format. This format is for video applications. Video display is realized by displaying static images continuously. All images must be in the same format, and the last part of each file name must have a 6-digit sequential number. The first frame can start at any number, but successive frames must be sequential (i.e., ladybug_000100.jpg, ladybug_000101.jpg….).

For more information about panoramic image formats, see

Displaying Images in the Viewer

After preparing images, follow these steps to view them in the Viewer:

    1. Upload an image to your web server.
    2. In the Master Index page of the Viewer, press Add and input the URL of an image previously uploaded. If it is a cube-mapped image or a sequential image for a video, input only the URL of the first image in the sequence (i.e., yourfilename_0.jpg or ladybug_000100.jpg).
    3. The new image will appear in the master index.

Creating an Image Folder

You can add a folder that contains multiple images or folders. This is done by preparing a plist (property list) file in XML format. The root element under <plist> must be <dict> (dictionary), which must contain the following key-value pairs:

    • “Title” – title of the index
    • “Items” – an array of items

The “Items” array contains multiple <dict> elements under <array>, and each must have the following key-value pairs:

    • “Title” – title of the item
    • “Subtitle” – subtitle of the item
    • “URL” – the URL of the item. If it is a cube-mapped image, it must point to the 0th surface (such as, cube_0.jpg). If the item is video, it must point to the first frame.
    • “Type” – the type of the item. This can be "panoramic_image" for a single panoramic image, "cubic_image" for a cube mapped image, “index” for a folder, or “video” for sequential images.

You can add subfolders under a folder. In this case, “Type” must be “index”.

After preparing the plist file, upload it to the web server. Then, press Add to add the index to the master index.

For more information about the property list format, see this page on the Mac OS X Reference Library. For a sample plist file, see this xml file.

Launching the Viewer from an External Application

In iOS, you can launch the Ladybug Spherical Viewer from external applications such as Mail or Safari. This way, you can show the images you added through an email or web site, provided the Viewer is also installed on the receiving side. Simply append “ladybug://” to the beginning of the URL of the image or folder you want to show, and mention it in the email or web site. On the receiving side, the URL will appear as a link that launches the Viewer. For example, if your image's URL is ../image.jpg, then specify the link as ladybug://../image.jpg.