Luciad Developer Platform

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.

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.

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:

Panorama feature information such as positions, image tiling structure, and data properties. This information sits in a GeoJson file cubemap.json.
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.

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.

Figure 4. Sample spherical input image

Figure 5. Mapping of the cubemap faces on the sample input image

Figure 6. Sample generated cubemap, consisting of 6 images

Converting panoramic image data in LuciadLightspeed and LuciadFusion

LuciadLightspeed and LuciadFusion offer sample applications for working with panorama data:

You can use the Panorama Converter command line sample to convert panorama data to the Luciad Panorama Format. See the documentation that comes with the sample for more information.

LuciadLightspeed does not support displaying the image data of a panorama dataset. You can visualize only the positions of the panoramas. See Visualize Panoramic image data locations on a Lightspeed view or Visualize Panoramic image data locations on a GXY view for more information.
You can use the Panorama viewer sample to calculate cubemap image data on-the-fly for a single panorama location. The sample shows the cubemap images in a flat view, as in Figure 6, “Sample generated cubemap, consisting of 6 images”. See the documentation that comes with the sample for more information.

There are only a few standardized formats for exchanging panorama data. Out-of-the-box, LuciadLightspeed and LuciadFusion support these panoramic image formats:

You can plug in other, custom panorama data by implementing an ILcdModelDecoder that makes ILcdPanorama objects. See this article for instructions.

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. See Serving panoramic image data article in the LuciadFusion documentation.

Panoramic images