This guide explains the core concepts and API for loading, modeling, and processing panoramic image data. Please read this quick start guide first.

While you can model, load, and process panoramas with LuciadLightspeed and LuciadFusion, those products don’t offer integrated visualization of these images in an ILcdView.

To inspect the images, you can use the Panorama Viewer sample. For an immersive geospatial view, load them in LuciadRIA.

What is panoramic image data?

A panoramic dataset consists of one or more panoramas.
The Luciad API reflects this in an ILcdModel. Its model descriptor is an instance of ILcdPanoramaModelDescriptor.

A panorama is a series of one or more panoramic images. Together, they represent a continuous scene. The images are taken from a single viewpoint.
In a so-called immersive panorama, the depicted scene is a full-spherical scene, but partial panoramas are equally valid.
In the Luciad API, the ILcdPanorama interface reflects these concepts.

panorama
Figure 1. A panorama consists of panoramic images

A single panoramic image is specified by a camera pose, a projection type, and the image pixel data.
The API offers the ILcdPanoramicImage interface for this.

  • The camera pose of an image is its exact position and orientation in space, relative to the model’s coordinate system. By using the camera pose, we can calculate the coordinates of a point in the model coordinate system to coordinates in the camera coordinate system and the other way around.

  • A projection type defines how the image is oriented relative to the camera coordinate system, and the mathematical formulas that make it possible to calculate the 2D image coordinates for a 3D world point and the other way around.

In the Luciad API, ILcdModelModelTransformation represents the combination of camera pose and projection type. The source model is a 3D model, with x, y, and z coordinates in the world coordinate system. The destination model is a 2D model, with u and v coordinates in the image coordinate system.

coordinates
Figure 2. Transformation from 3D world coordinates to 2D image coordinates

The image coordinates take the lower left point of the image as origin (0,0), and the top right point as (1,1).

The Luciad API provides builders for creating transformations for the most common projection types:

  • Pinhole

  • Equirectangular

You can combine these projections with a rotation to orient your panorama in the world. See TLcdPanoramicTransformationFactory for more information. You can also implement your own image transformation.

Processing panoramic data into the Luciad Panorama Format for streaming

LuciadLightspeed and LuciadFusion can process panoramas into the Luciad Panorama Format. This format has tiled and multi-leveled panoramic images ready for streaming to LuciadRIA, for example. The format consists of:

  1. Panorama feature information such as positions, image tiling structure, and data properties. This information sits in a GeoJson file cubemap.json.

  2. Panorama image tiles. These are the multi-leveled tile images stored in the images folder.

The tiled and multi-leveled images form a cubemap.

Cubemaps in the Luciad Panorama format

A cubemap is a specific panorama type, consisting of 6 pinhole images that each describe one face of a cube. Together, these images form an immersive panorama.
The center point of the cubemap is the focal point of all pinhole images.
The entire cubemap has a coordinate system from which we can derive the camera poses of the 6 faces.

cubemap
Figure 3. Cubemaps as defined in the Luciad software

In the Luciad API, a cubemap has these properties:

  • The 6 cube faces have a front, right, back, left, top or bottom label.

  • Coordinate system:

    • The X axis pointing to the right face

    • The Y axis pointing to the front face

    • The Z axis pointing to the top face

  • Orientation of the coordinate system relative to an Easting/Northing/Up (ENU) coordinate system. If the rotation matrix is the identity matrix, then:

    • X points East

    • Y points North

    • Z points Up (Zenith)

Converting panorama data to the Luciad Panorama Format

With the Luciad API, you can transform all panorama formats to the Luciad Panorama Format using the TLcdLuciadPanoramaModelEncoder. See the class reference documentation for more information.

Sample spherical input image
Figure 4. Sample spherical input image
Mapping of the cubemap faces on the sample input image
Figure 5. Mapping of the cubemap faces on the sample input image
Sample generated cubemap
Figure 6. Sample generated cubemap, consisting of 6 images

Converting panoramic image data in LuciadLightspeed

LuciadLightspeed offers command line applications for working with panorama data:

Converting panoramic image data in LuciadFusion and serving it to LuciadRIA

LuciadFusion can process panoramic image format into the Luciad Panorama Format, and serve the data for optimized visualization in LuciadRIA.