com.luciad.format.panorama

Advanced Raster ServicesClass TLcdLuciadPanoramaModelEncoder

java.lang.Object

com.luciad.format.panorama.TLcdLuciadPanoramaModelEncoder

All Implemented Interfaces:

ILcdModelEncoder, ILcdStatusSource, Serializable

@LcdService(service=ILcdModelEncoder.class,
            priority=20000)
public class TLcdLuciadPanoramaModelEncoder
extends Object
implements ILcdModelEncoder, ILcdStatusSource

Encodes panoramic image models to the Luciad Panorama Format.

Relevance

See the Panorama guide for more information.

This encoder will create multi-leveled tiled cubemap panoramas, for optimal loading in the RIA scene.

Supported input models

This model encoder handles only models that contain panoramic imagery.

This encoder handles models whose model descriptor implements ILcdPanoramaModelDescriptor. This implies that its elements implement ILcdPanorama. The panoramic models that are created by our decoders (such as TLcdPegasusModelDecoder) fulfill these requirements.

For more information on how you can create your own decoder, see this article.

Output

This encoder outputs a Luciad Panorama dataset. Specifically:

• It creates tiled and multi-leveled images for each face (front, right, left, back, up, down) of each cubemap.
• It writes the panorama metadata to a delegate encoder, which by default is a GeoJSON encoder that will create a cubemap.json file that holds the cubemap imagery information. See the constructor parameters for more information.

Example

Decoding a Leica Pegasus panoramic dataset and encoding it into a Luciad Panorama cubemap.json.

    // Load a Pegasus panoramic dataset
    ILcdModelDecoder decoder = new TLcdPegasusModelDecoder();
    ILcdModel model = decoder.decode("/path/to/pegasus/External Orientation.csv");

    // Encode to GeoJSON
    ILcdModelEncoder encoder = new TLcdLuciadPanoramaModelEncoder();
    encoder.export(model, "/path/to/cubemap/cubemap.json");

Thread-safety

This encoder is not thread-safe for concurrent writing.

Other notes

• This encoder uses multiple threads (number of processors - 1) in parallel to do the processing. You can change this with the system property "com.luciad.format.panorama.TLcdLuciadPanoramaModelEncoder.parallelism".
• You can abort processing by calling stop(), or even killing the process. If you then restart export(com.luciad.model.ILcdModel, java.lang.String), this encoder will automatically try to resume processing from where it got interrupted. When processing a model, this encoder will skip the generation of any cubemap image which already exists in the output location. If you wish to restart processing from scratch, you must first clean the output directory.
• You can plug in your own encoder to save the cubemap position and metadata information. For example, you can plug in a TLcdPostGISModelEncoder to save the cubemap information in a database. By default, the cubemap information is stored as GeoJSON.
• You can process multiple input datasets to the same output. The new panoramas will be appended, as long as they have a unique primary key (feature id). By default, an incrementing number is used, but you can override this behaviour and provide your own primary keys. To use the primary key of the input model, use ILcdOGCFeatureIDRetriever.createDefaultFeatureIDRetriever(ILcdModel).

Since:

2020.1

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
TLcdLuciadPanoramaModelEncoder() Create a default panorama encoder.
TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder) Create a new Luciad Panorama encoder that saves the panorama feature properties using the decoder and encoder.
TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder, int aSkip, long aLimit, int aEvery, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Create a new encoder with the given parameters.
TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder, int aSkip, long aLimit, int aEvery, int aMaximumTileSize, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Create a new encoder with the given parameters.
TLcdLuciadPanoramaModelEncoder(int aSkip, long aLimit, int aEvery, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Create a new encoder with the given parameters.
TLcdLuciadPanoramaModelEncoder(int aSkip, long aLimit, int aEvery, int aMaximumTileSize, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Create a new encoder with the given parameters.

Method Summary

Modifier and Type	Method and Description
void	addStatusListener(ILcdStatusListener aListener) Registers the given listener so it will receive status events from this source.
boolean	canExport(ILcdModel aModel, String aDestinationName) Returns whether this encoder can export the specified model to the specified destination.
boolean	canSave(ILcdModel aModel) Returns whether this model encoder can save the specified model to the location it originally came from.
void	export(ILcdModel aModel, String aDestinationName) Exports the specified model to the specified destination.
String	getDisplayName() Returns a short, displayable name for the format this ILcdModelEncoder encodes to.
void	removeStatusListener(ILcdStatusListener aListener) Removes the specified listener so it is no longer notified.
void	save(ILcdModel aModel) Saves the model to the location where it originally came from.
void	setFeatureIDRetriever(ILcdOGCFeatureIDRetriever aFeatureIDRetriever) Override the default primary key provider.
void	stop() Abort processing.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TLcdLuciadPanoramaModelEncoder

public TLcdLuciadPanoramaModelEncoder()

Create a default panorama encoder.

See constructor TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder, ILcdModelEncoder, int, long, int, int, int, boolean, double) with these default parameters:

• aDelegateDecoder: TLcdGeoJsonModelDecoder
• aDelegateEncoder: TLcdGeoJsonModelEncoder
• aSkip: 0
• aLimit: -1
• aEvery: 1
• aMaximumTileSize: 350
• aResampleGridSize: 20
• aDrawOrientation: false
• aCompressionQuality: 0.75

TLcdLuciadPanoramaModelEncoder

public TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder,
                                      ILcdModelEncoder aDelegateEncoder)

Create a new Luciad Panorama encoder that saves the panorama feature properties using the decoder and encoder.

The decoder and encoder should be consistent with themselves. This allows you to save the panorama feature information into a spatial database, for example.

See constructor TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder, ILcdModelEncoder, int, long, int, int, int, boolean, double) with these default parameters:

• aSkip: 0
• aLimit: -1
• aEvery: 1
• aMaximumTileSize: 350
• aResampleGridSize: 20
• aDrawOrientation: false
• aCompressionQuality: 0.75

Parameters:

aDelegateDecoder - the decoder that must be used when appending panorama metadata to an existing model

aDelegateEncoder - the encoder that will be used for writing the panorama metadata

TLcdLuciadPanoramaModelEncoder

public TLcdLuciadPanoramaModelEncoder(int aSkip,
                                      long aLimit,
                                      int aEvery,
                                      int aResampleGridSize,
                                      boolean aDrawOrientation,
                                      double aCompressionQuality)

Create a new encoder with the given parameters.

See constructor TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder, ILcdModelEncoder, int, long, int, int, int, boolean, double) with these default parameters:

• aDelegateDecoder: TLcdGeoJsonModelDecoder
• aDelegateEncoder: TLcdGeoJsonModelEncoder
• aMaximumTileSize: 350

Parameters:

aSkip - number of input model elements that will be skipped at the start, must be positive

aLimit - maximum number of elements that the output panorama model will have, unlimited if negative

aEvery - number of input model elements that will be skipped between two successive elements to be processed, must be strictly positive

aResampleGridSize - the size of the grid that will be used when resampling the input images, must be 1 or larger

aDrawOrientation - a boolean indicating whether the output images should contain an orientation grid (N/E/S/W)

aCompressionQuality - the jpg compression quality that will be used for the output images, must be a value between 0 and 1

TLcdLuciadPanoramaModelEncoder

public TLcdLuciadPanoramaModelEncoder(int aSkip,
                                      long aLimit,
                                      int aEvery,
                                      int aMaximumTileSize,
                                      int aResampleGridSize,
                                      boolean aDrawOrientation,
                                      double aCompressionQuality)

Create a new encoder with the given parameters.

See constructor TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder, ILcdModelEncoder, int, long, int, int, int, boolean, double) with these default parameters:

• aDelegateDecoder: TLcdGeoJsonModelDecoder
• aDelegateEncoder: TLcdGeoJsonModelEncoder

Parameters:

aSkip - number of input model elements that will be skipped at the start, must be positive

aLimit - maximum number of elements that the output panorama model will have, unlimited if negative

aEvery - number of input model elements that will be skipped between two successive elements to be processed, must be strictly positive

aResampleGridSize - the size of the grid that will be used when resampling the input images, must be 1 or larger

aDrawOrientation - a boolean indicating whether the output images should contain an orientation grid (N/E/S/W)

aCompressionQuality - the jpg compression quality that will be used for the output images, must be a value between 0 and 1

Since:

2023.0

TLcdLuciadPanoramaModelEncoder

public TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder,
                                      ILcdModelEncoder aDelegateEncoder,
                                      int aSkip,
                                      long aLimit,
                                      int aEvery,
                                      int aResampleGridSize,
                                      boolean aDrawOrientation,
                                      double aCompressionQuality)

Create a new encoder with the given parameters.

See constructor TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder, ILcdModelEncoder, int, long, int, int, int, boolean, double) with these default parameters:

• aMaximumTileSize: 350

Parameters:

aDelegateDecoder - the decoder that must be used when appending panorama metadata to an existing model

aDelegateEncoder - the encoder that will be used for writing the panorama metadata

aSkip - number of input model elements that will be skipped at the start, must be positive

aLimit - maximum number of elements that the output panorama model will have, unlimited if negative

aEvery - number of input model elements that will be skipped between two successive elements to be processed, must be strictly positive

aResampleGridSize - the size of the grid that will be used when resampling the input images, must be 1 or larger

aDrawOrientation - a boolean indicating whether the output images should contain an orientation grid (N/E/S/W)

aCompressionQuality - the jpg compression quality that will be used for the output images, must be a value between 0 and 1

TLcdLuciadPanoramaModelEncoder

public TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder,
                                      ILcdModelEncoder aDelegateEncoder,
                                      int aSkip,
                                      long aLimit,
                                      int aEvery,
                                      int aMaximumTileSize,
                                      int aResampleGridSize,
                                      boolean aDrawOrientation,
                                      double aCompressionQuality)

Create a new encoder with the given parameters.

• aDelegateDecoder: when appending panorama metadata to an existing model, this decoder will be used.
• aDelegateEncoder: when writing panorama metadata, this encoder will be used.
  You can plug in your own encoder to save the cubemap position and metadata information. For example, you can plug in a TLcdPostGISModelEncoder to save the cubemap information in a database.
• aSkip: number of input model elements that will be skipped at the start.
  This value must be positive or zero.
  For example, if the input model has 1000 elements, setting this value to 100 will start processing from the 101st element forward.
• aLimit: maximum number of input model elements that will be processed.
  If a negative value is provided for this parameter, all elements will be processed.
• aEvery: number of input model elements to jump from one processed element to the next
  This value must be strictly positive. A value of 1 means that every element will be processed.
• aMaximumTileSize: the maximum size of a tile when creating the Luciad panoramas.
  Higher values for this parameter will generally split the full-detail image in fewer tiles, and will generate fewer levels of detail, but the size of each tile will be bigger.
• aResampleGridSize: The grid size that will be used when remapping pixels from the input panoramic images to the output images.
  The grid defines how many corresponding pixels locations are calculated exactly, while intermediate locations are derived with bilinear interpolation.
  Higher values for this parameter will generally speed up the processing, but might reduce the output image quality because fewer exact pixel locations are calculated.
• aDrawOrientation: setting this value to true will make the encoder paint an orientation grid on the output panoramic images with N/E/S/W labels.
• aCompressionQuality: the jpg compression quality that will be used for the output images
  This must be a value between 0 and 1.

A combination of the parameters aSkip, aLimit and aEvery could be used to gain quick insight in a specific large input dataset.
For example, if a dataset has 5000 panoramic images, processing all these image can take a long time. You could use aSkip and aLimit if you only need a part of the dataset.
Or, if you need to take samples over the entire dataset to verify its quality, you can use aEvery = 20 to have only 5% of the dataset processed. In a second pass, you can add elements to the output dataset by modifying the parameters, for exmple using a combination of aSkip = 10 and aEvery = 20 will again process 5% of the dataset.

Parameters:

aDelegateDecoder - the decoder that must be used when appending panorama metadata to an existing model

aDelegateEncoder - the encoder that will be used for writing the panorama metadata

aSkip - number of input model elements that will be skipped at the start, must be positive

aLimit - maximum number of elements that the output panorama model will have, unlimited if negative

aEvery - number of input model elements that will be skipped between two successive elements to be processed, must be strictly positive

aMaximumTileSize - the maximum size of a tile when creating the Luciad panoramas, must be strictly positive

aResampleGridSize - the size of the grid that will be used when resampling the input images, must be 1 or larger

aDrawOrientation - a boolean indicating whether the output images should contain an orientation grid (N/E/S/W)

aCompressionQuality - the jpg compression quality that will be used for the output images, must be a value between 0 and 1

Since:

2023.0

Method Detail

setFeatureIDRetriever

public void setFeatureIDRetriever(ILcdOGCFeatureIDRetriever aFeatureIDRetriever)

Override the default primary key provider.

By default, an incrementing number is used, restarting on each export(com.luciad.model.ILcdModel, java.lang.String).

To use the primary key of the input model, use ILcdOGCFeatureIDRetriever.createDefaultFeatureIDRetriever(ILcdModel).

Parameters:

aFeatureIDRetriever - The new primary key provider, use null to use the default.

getDisplayName

public String getDisplayName()

Description copied from interface: ILcdModelEncoder

Returns a short, displayable name for the format this ILcdModelEncoder encodes to.

Specified by:

getDisplayName in interface ILcdModelEncoder

Returns:

the displayable name of this ILcdModelEncoder.

canSave

public boolean canSave(ILcdModel aModel)

Description copied from interface: ILcdModelEncoder

Returns whether this model encoder can save the specified model to the location it originally came from. Often this will only be a simple test, for example checking the type of the model's model descriptor.

Specified by:

canSave in interface ILcdModelEncoder

Parameters:

aModel - the model to be verified.

Returns:

true if this encoder can save the model in the location where it originally came from, false otherwise.

See Also:

ILcdModelEncoder.save(com.luciad.model.ILcdModel)

addStatusListener

public void addStatusListener(ILcdStatusListener aListener)

Description copied from interface: ILcdStatusSource

Registers the given listener so it will receive status events from this source.

In case you need to register a listener which keeps a reference to an object with a shorter life-time than this status source, you can use a ALcdWeakStatusListener instance as status listener.

Specified by:

addStatusListener in interface ILcdStatusSource

Parameters:

aListener - The listener to be notified when the status has changed.

removeStatusListener

public void removeStatusListener(ILcdStatusListener aListener)

Description copied from interface: ILcdStatusSource

Removes the specified listener so it is no longer notified.

Specified by:

removeStatusListener in interface ILcdStatusSource

Parameters:

aListener - The listener to remove.

save

public void save(ILcdModel aModel)
          throws IllegalArgumentException

Description copied from interface: ILcdModelEncoder

Saves the model to the location where it originally came from.

Specified by:

save in interface ILcdModelEncoder

Parameters:

aModel - the model to be saved.

Throws:

IllegalArgumentException - if the model cannot be saved by this encoder (!canSave(aModel)).

canExport

public boolean canExport(ILcdModel aModel,
                         String aDestinationName)

Returns whether this encoder can export the specified model to the specified destination.

All the following conditions must be met:

• the given aModel must have a ILcdPanoramaModelDescriptor.
• the given aDestinationName must contain "cubemap".
• this encoder's delegate decoder must be able to export a panorama model to the destination. See class javadoc and constructor javadoc.

Specified by:

canExport in interface ILcdModelEncoder

Parameters:

aModel - the model to be verified.

aDestinationName - the location where the model should be exported to.

Returns:

true if the model can be exported to the location

See Also:

ILcdModelEncoder.export(com.luciad.model.ILcdModel, java.lang.String)

stop

public void stop()

Abort processing.

Saved results are not removed. You can resume processing by simply starting another export(com.luciad.model.ILcdModel, java.lang.String). Panoramas that were already processed will be skipped.

export

public void export(ILcdModel aModel,
                   String aDestinationName)
            throws IllegalArgumentException,
                   IOException

Description copied from interface: ILcdModelEncoder

Exports the specified model to the specified destination.

Specified by:

export in interface ILcdModelEncoder

Parameters:

aModel - the model to be exported.

aDestinationName - the location where the model should be saved. Typically, this is a name for the output file, but it can also point to a file containing the required properties to create a set of data files.

Throws:

IllegalArgumentException - if the model cannot be saved by this encoder (!canExport(aModel, aDestinationName)).

IOException - if an I/O error occurs during encoding.