Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Panorama Tracks

A movie’s panorama track is a track that contains information about the panoramic nodes in a scene. The media type of the panorama track is 'pano'. Each sample in a panorama track corresponds to a single panoramic node. This sample parallels the corresponding sample in the QTVR track. Panorama tracks do not have a sample description (although QuickTime requires that you specify a dummy sample description when you call AddMediaSample to add a sample to a panorama track). The sample itself contains an atom container that includes a panorama sample atom and other optional atoms.

In this section:

Panorama Sample Atom Structure
Panorama Image Track
Cylindrical Panoramas

Panorama Sample Atom Structure

A panorama sample atom has an atom type of kQTVRPanoSampleDataAtomType ('pdat'). It describes a single panorama, including track reference indexes of the scene and hot spot tracks and information about the default viewing angles and the source panoramic image.

The structure of a panorama sample atom is defined by the QTVRPanoSampleAtom data type:

typedef struct VRPanoSampleAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    UInt32                              imageRefTrackIndex;

    UInt32                              hotSpotRefTrackIndex;

    Float32                             minPan;

    Float32                             maxPan;

    Float32                             minTilt;

    Float32                             maxTilt;

    Float32                             minFieldOfView;

    Float32                             maxFieldOfView;

    Float32                             defaultPan;

    Float32                             defaultTilt;

    Float32                             defaultFieldOfView;

    UInt32                              imageSizeX;

    UInt32                              imageSizeY;

    UInt16                              imageNumFramesX;

    UInt16                              imageNumFramesY;

    UInt32                              hotSpotSizeX;

    UInt32                              hotSpotSizeY;

    UInt16                              hotSpotNumFramesX;

    UInt16                              hotSpotNumFramesY;

    UInt32                              flags;

    OSType                              panoType;

    UInt32                              reserved2;

} VRPanoSampleAtom, *VRPanoSampleAtomPtr;

Field descriptions

majorVersion

The major version number of the file format.

minorVersion

The minor version number of the file format.

imageRefTrackIndex

The index of the image track reference. This is the index returned by the AddTrackReference function when the image track is added as a reference to the panorama track. There can be more than one image track for a given panorama track and hence multiple references. (A panorama track might have multiple image tracks if the panoramas have different characteristics, which could occur if the panoramas were shot with different size camera lenses.) The value in this field is 0 if there is no corresponding image track.

hotSpotRefTrackIndex

The index of the hot spot track reference.

minPan

The minimum pan angle, in degrees. For a full panorama, the value of this field is usually 0.0.

maxPan

The maximum pan angle, in degrees. For a full panorama, the value of this field is usually 360.0.

minTilt

The minimum tilt angle, in degrees. For a high-resolution panorama, a typical value for this field is –42.5.

maxTilt

The maximum tilt angle, in degrees. For a high-resolution panorama, a typical value for this field is +42.5.

minFieldOfView

The minimum vertical field of view, in degrees. For a high-resolution panorama, a typical value for this field is 5.0. The value in this field is 0 for the default minimum field of view, which is 5 percent of the maximum field of view.

maxFieldOfView

The maximum vertical field of view, in degrees. For a high-resolution panorama, a typical value for this field is 85.0. The value in this field is 0 for the default maximum field of view, which is maxTilt – minTilt.

defaultPan

The default pan angle, in degrees.

defaultTilt

The default tilt angle, in degrees.

defaultFieldOfView

The default vertical field of view, in degrees.

imageSizeX

The width, in pixels, of the panorama stored in the highest resolution image track.

imageSizeY

The height, in pixels, of the panorama stored in the highest resolution image track.

imageNumFramesX

The number of frames into which the panoramic image is diced horizontally. The width of each frame (which is imageSizeX/imageNumFramesX) should be divisible by 4.

imageNumFramesY

The number of frames into which the panoramic image is diced vertically. The height of each frame (which is imageSizeY/imageNumFramesY) should be divisible by 4.

hotSpotSizeX

The width, in pixels, of the panorama stored in the highest resolution hot spot image track.

hotSpotSizeY

The height, in pixels, of the panorama stored in the highest resolution hot spot image track.

hotSpotNumFramesX

The number of frames into which the panoramic image is diced horizontally for the hot spot image track.

hotSpotNumFramesY

The number of frames into which the panoramic image is diced vertically for the hot spot image track.

flags

A set of panorama flags. kQTVRPanoFlagHorizontal has been superseded by the panoType field. It is only used when the panoType field is nil to indicate a horizontally-oriented cylindrical panorama. kQTVRPanoFlagAlwaysWrap is set if the panorama should wrap horizontally, regardless of whether or not the pan range is 360 degrees. Note that these flags are currently supported only under Mac OS X.

panoType

An OSType describing the type of panorama. Types supported are

kQTVRHorizontalCylinder

kQTVRVerticalCylinder

kQTVRCube

reserved2

Reserved. This field must be 0.

Important:  A new flag has been added to the flags field of the QTVRPanoSampleAtom data structure. This flag controls how panoramas wrap horizontally. If kQTVRPanoFlagAlwaysWrap is set, then the panorama wraps horizontally, regardless of the number of degrees in the panorama. If the flag is not set, then the panorama wraps only when the panorama range is 360 degrees. This is the default behavior.

The minimum and maximum values in the panorama sample atom describe the physical limits of the panoramic image. QuickTime VR allows you to set further constraints on what portion of the image a user can see by calling the QTVRSetConstraints routine. You can also preset image constraints by adding constraint atoms to the panorama sample atom container. The three constraint atom types are kQTVRPanConstraintAtomType, kQTVRTiltConstraintAtomType, and kQTVRFOVConstraintAtomType. Each of these atom types share a common structure defined by the QTVRAngleRangeAtom data type:

typedef struct QTVRAngleRangeAtom {

    Float32                             minimumAngle;

    Float32                             maximumAngle;

} QTVRAngleRangeAtom, *QTVRAngleRangeAtomPtr;

Field descriptions

minimumAngle

The minimum angle in the range, in degrees.

maximumAngle

The maximum angle in the range, in degrees.

Panorama Image Track

The actual panoramic image for a panoramic node is contained in a panorama image track, which is a standard QuickTime video track. The track reference to this track is stored in the imageRefTrackIndex field of the panorama sample atom.

QuickTime VR 2.1 required the original panoramic image to be rotated 90 degrees counterclockwise. This orientation has changed in QuickTime VR 2.2, however, as discussed later in this section.

The rotated image is diced into smaller frames, and each diced frame is then compressed and added to the video track as a video sample, as shown in Figure 3-21. Frames can be compressed using any spatial compressor; however, temporal compression is not allowed for panoramic image tracks.

Figure 3-21  Creating an image track for a panorama

QuickTime VR 2.2 does not require the original panoramic image to be rotated 90 degrees counterclockwise, as was the case in QuickTime VR 2.1. The rotated image is still diced into smaller frames, and each diced frame is then compressed and added to the video track as a video sample, as shown in Figure 3-22.

Figure 3-22  Creating an image track for a panorama, with the image track oriented horizontally

In QuickTime 3.0, a panorama sample atom (which contains information about a single panorama) contains the panoType field, which indicates whether the diced panoramic image is oriented horizontally or vertically.

Cylindrical Panoramas

The primary change to cylindrical panoramas in QuickTime VR 2.2 is that the panorama, as stored in the image track of the movie, can be oriented horizontally. This means that the panorama does not need to be rotated 90 degrees counterclockwise, as required previously.

To indicate a horizontal orientation, the field in the VRPanoSampleAtom data structure formerly called reserved1 has been renamed panoType. Its type is OSType. The panoType field value for a horizontally oriented cylinder is kQTVRHorizontalCylinder ('hcyl'), while a vertical cylinder is kQTVRVerticalCylinder ('vcyl'). For compatibility with older QuickTime VR files, when the panoType field is nil, then a cylinder is assumed, with the low order bit of the flags field set to 1 to indicate if the cylinder is horizontal and 0 if the cylinder is vertical.

One consequence of reorienting the panorama horizontally is that, when the panorama is divided into separate tiles, the order of the samples in the file is now the reverse of what it was for vertical cylinders. Since vertical cylinders were rotated 90 degrees counterclockwise, the first tile added to the image track was the rightmost tile in the panorama. For unrotated horizontal cylinders, the first tile added to the image track is the left-most tile in the panorama.

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice