Class TLcdLuciadPanoramaModelEncoder
- All Implemented Interfaces:
ILcdModelEncoder
,ILcdStatusSource
,Serializable
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 setDelegateDecoder(com.luciad.model.ILcdModelDecoder) and setDelegateEncoder(com.luciad.model.ILcdModelEncoder) methods 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 restartexport(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 aTLcdPostGISModelEncoder
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, useILcdOGCFeatureIDRetriever.createDefaultFeatureIDRetriever(ILcdModel)
. -
There are several settings impact the processing speed and/or quality:
setMaximumTileSize(int)
,setResolutionFactor(double)
,setResampleGridSize(int)
,setCompressionQuality(double)
. -
The
setElementProcessingParameters(int, long, int)
method allows you to gain quick insight in a specific large input dataset by skipping elements, limiting the number of elements, or processing only every n-th element.
- Since:
- 2020.1
- See Also:
-
Constructor Summary
ConstructorsConstructorDescriptionCreate a default panorama encoder.TLcdLuciadPanoramaModelEncoder
(int aSkip, long aLimit, int aEvery, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all propertiesTLcdLuciadPanoramaModelEncoder
(int aSkip, long aLimit, int aEvery, int aMaximumTileSize, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all propertiesTLcdLuciadPanoramaModelEncoder
(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder) Deprecated.use the no-argument constructor and individual setters for all propertiesTLcdLuciadPanoramaModelEncoder
(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder, int aSkip, long aLimit, int aEvery, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all propertiesTLcdLuciadPanoramaModelEncoder
(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder, int aSkip, long aLimit, int aEvery, int aMaximumTileSize, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all properties -
Method Summary
Modifier and TypeMethodDescriptionvoid
addStatusListener
(ILcdStatusListener aListener) Registers the given listener so it will receive status events from this source.boolean
Returns whether this encoder can export the specified model to the specified destination.boolean
Returns whether this model encoder can save the specified model to the location it originally came from.void
Exports the specified model to the specified destination.Returns a short, displayable name for the format thisILcdModelEncoder
encodes to.void
removeStatusListener
(ILcdStatusListener aListener) Removes the specified listener so it is no longer notified.void
Saves the model to the location where it originally came from.void
setCompressionQuality
(double aCompressionQuality) Set the jpg compression quality that will be used for the output images.void
setDelegateDecoder
(ILcdModelDecoder aDelegateDecoder) Set the delegate decoder that must be used when appending panorama metadata to an existing model.void
setDelegateEncoder
(ILcdModelEncoder aDelegateEncoder) Set the delegate encoder that must be used to write panorama metadata.void
setDrawOrientation
(boolean aDrawOrientation) Set whether the output panoramic images should contain an orientation grid with N/E/S/W labels.void
setElementProcessingParameters
(int aSkip, long aLimit, int aEvery) Set the element processing parameters for the encoder.void
setFeatureIDRetriever
(ILcdOGCFeatureIDRetriever aFeatureIDRetriever) Set the primary key provider.void
setMaximumTileSize
(int aMaximumTileSize) Set the maximum tile size that will be used when creating the Luciad panoramas.void
setResampleGridSize
(int aResampleGridSize) Set the grid size that will be used when remapping pixels from the input panoramic images to the output images.void
setResolutionFactor
(double aResolutionFactor) Set the resolution factor that will be used when calculating the quality of output images.void
stop()
Abort processing.
-
Constructor Details
-
TLcdLuciadPanoramaModelEncoder
public TLcdLuciadPanoramaModelEncoder()Create a default panorama encoder.The encoder is initialized with default values for its properties:
-
TLcdLuciadPanoramaModelEncoder
public TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder) Deprecated.use the no-argument constructor and individual setters for all propertiesCreate a new Luciad Panorama encoder that saves the panorama feature properties using the decoder and encoder.The encoder is initialized with default values for the following properties:
- Parameters:
aDelegateDecoder
- see setDelegateDecoder(com.luciad.model.ILcdModelDecoder)aDelegateEncoder
- see setDelegateEncoder(com.luciad.model.ILcdModelEncoder)
-
TLcdLuciadPanoramaModelEncoder
public TLcdLuciadPanoramaModelEncoder(int aSkip, long aLimit, int aEvery, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all propertiesCreate a new encoder with the given parameters.The encoder is initialized with default values for the following properties:
- Parameters:
aSkip
- see setElementProcessingParameters(int, long, int)aLimit
- see setElementProcessingParameters(int, long, int)aEvery
- see setElementProcessingParameters(int, long, int)aResampleGridSize
- see setResampleGridSize(int)aDrawOrientation
- see setDrawOrientation(boolean)aCompressionQuality
- see setCompressionQuality(double)
-
TLcdLuciadPanoramaModelEncoder
public TLcdLuciadPanoramaModelEncoder(int aSkip, long aLimit, int aEvery, int aMaximumTileSize, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all propertiesCreate a new encoder with the given parameters.The encoder is initialized with default values for the following properties:
- Parameters:
aSkip
- see setElementProcessingParameters(int, long, int)aLimit
- see setElementProcessingParameters(int, long, int)aEvery
- see setElementProcessingParameters(int, long, int)aMaximumTileSize
- see setMaximumTileSize(int)aResampleGridSize
- see setResampleGridSize(int)aDrawOrientation
- see setDrawOrientation(boolean)aCompressionQuality
- see setCompressionQuality(double)- Since:
- 2023.0
-
TLcdLuciadPanoramaModelEncoder
public TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder, int aSkip, long aLimit, int aEvery, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all propertiesCreate a new encoder with the given parameters.The encoder is initialized with default values for the following properties:
- Parameters:
aDelegateDecoder
- see setDelegateDecoder(com.luciad.model.ILcdModelDecoder)aDelegateEncoder
- see setDelegateEncoder(com.luciad.model.ILcdModelEncoder)aSkip
- see setElementProcessingParameters(int, long, int)aLimit
- see setElementProcessingParameters(int, long, int)aEvery
- see setElementProcessingParameters(int, long, int)aResampleGridSize
- see setResampleGridSize(int)aDrawOrientation
- see setDrawOrientation(boolean)aCompressionQuality
- see setCompressionQuality(double)
-
TLcdLuciadPanoramaModelEncoder
public TLcdLuciadPanoramaModelEncoder(ILcdModelDecoder aDelegateDecoder, ILcdModelEncoder aDelegateEncoder, int aSkip, long aLimit, int aEvery, int aMaximumTileSize, int aResampleGridSize, boolean aDrawOrientation, double aCompressionQuality) Deprecated.use the no-argument constructor and individual setters for all propertiesCreate a new encoder with the given parameters.The encoder is initialized with default values for the following properties:
- Parameters:
aDelegateDecoder
- see setDelegateDecoder(com.luciad.model.ILcdModelDecoder)aDelegateEncoder
- see setDelegateEncoder(com.luciad.model.ILcdModelEncoder)aSkip
- see setElementProcessingParameters(int, long, int)aLimit
- see setElementProcessingParameters(int, long, int)aEvery
- see setElementProcessingParameters(int, long, int)aMaximumTileSize
- see setMaximumTileSize(int)aResampleGridSize
- see setResampleGridSize(int)aDrawOrientation
- see setDrawOrientation(boolean)aCompressionQuality
- see setCompressionQuality(double)- Since:
- 2023.0
-
-
Method Details
-
setDelegateDecoder
Set the delegate decoder that must be used when appending panorama metadata to an existing model.This setting is closely related to the
delegate encoder
, as both the decoder and encoder need to use the same format and should be consistent with themselves.By default, the delegate decoder is a GeoJSON model decoder.
- Parameters:
aDelegateDecoder
- the new delegate decoder, ornull
to use the default- Since:
- 2024.1
- See Also:
-
setDelegateEncoder
Set the delegate encoder that must be used to write panorama metadata.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.This setting is closely related to the
delegate decoder
, as both the decoder and encoder need to use the same format and should be consistent with themselves.By default, the cubemap information will be stored as GeoJSON.
- Parameters:
aDelegateEncoder
- the new delegate encoder, ornull
to use the default- Since:
- 2024.1
-
setFeatureIDRetriever
Set the 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, useILcdOGCFeatureIDRetriever.createDefaultFeatureIDRetriever(ILcdModel)
.- Parameters:
aFeatureIDRetriever
- The new primary key provider, usenull
to use the default.
-
setMaximumTileSize
public void setMaximumTileSize(int aMaximumTileSize) Set the maximum tile size that will be used 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.
Default value: 350
- Parameters:
aMaximumTileSize
- the new maximum tile size- Throws:
IllegalArgumentException
- if the given value is smaller than 1- Since:
- 2024.1
-
setResolutionFactor
public void setResolutionFactor(double aResolutionFactor) Set the resolution factor that will be used when calculating the quality of output images.The processor will automatically determine the resolution of the output images, based on the available input images. In some cases, that resolution might be too high (e.g. when the input dataset is too detailed or heavy for the intended end use), or too low (e.g. when important information is located in parts of the input images that are distorted).
This parameter allows you to change the resolution of the output images: values higher than 1 will increase the resolution, while values lower than 1 will decrease the resolution. The resulting dataset size (on disk) will change accordingly.Default value: 1.0
- Parameters:
aResolutionFactor
- the new resolution factor- Throws:
IllegalArgumentException
- if the given value is not strictly positive- Since:
- 2024.1
-
setResampleGridSize
public void setResampleGridSize(int aResampleGridSize) Set 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.Default value: 20
- Parameters:
aResampleGridSize
- the new grid size- Throws:
IllegalArgumentException
- if the given value is not strictly positive- Since:
- 2024.1
-
setDrawOrientation
public void setDrawOrientation(boolean aDrawOrientation) Set whether the output panoramic images should contain an orientation grid with N/E/S/W labels.Default value: false
- Parameters:
aDrawOrientation
- the new value- Since:
- 2024.1
-
setElementProcessingParameters
public void setElementProcessingParameters(int aSkip, long aLimit, int aEvery) Set the element processing parameters for the encoder.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 to100
will start processing from the 101st element forward.
Default value: 0aLimit
: maximum number of input model elements that will be processed.
If a negative value is provided for this parameter, all elements will be processed.
Default value: -1aEvery
: number of input model elements to jump from one processed element to the next
This value must be strictly positive. A value of1
means that every element will be processed.
Default value: 1
A combination of these parameters can 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 useaSkip
andaLimit
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 useaEvery = 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 ofaSkip = 10
andaEvery = 20
will again process 5% of the dataset.- Parameters:
aSkip
- the number of input model elements that will be skipped at the startaLimit
- the maximum number of elements that will be processedaEvery
- the number of input model elements to jump from one processed element to the next- Throws:
IllegalArgumentException
- if any of the given values is not valid- Since:
- 2024.1
-
setCompressionQuality
public void setCompressionQuality(double aCompressionQuality) Set the jpg compression quality that will be used for the output images.This must be a value between 0 and 1.
Default value: 0.75
- Parameters:
aCompressionQuality
- the new compression quality- Throws:
IllegalArgumentException
- if the given value is not in the range (0,1)- Since:
- 2024.1
-
getDisplayName
Description copied from interface:ILcdModelEncoder
Returns a short, displayable name for the format thisILcdModelEncoder
encodes to.- Specified by:
getDisplayName
in interfaceILcdModelEncoder
- Returns:
- the displayable name of this
ILcdModelEncoder
.
-
canSave
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 interfaceILcdModelEncoder
- 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:
-
addStatusListener
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 interfaceILcdStatusSource
- Parameters:
aListener
- The listener to be notified when the status has changed.
-
removeStatusListener
Description copied from interface:ILcdStatusSource
Removes the specified listener so it is no longer notified.- Specified by:
removeStatusListener
in interfaceILcdStatusSource
- Parameters:
aListener
- The listener to remove.
-
save
Description copied from interface:ILcdModelEncoder
Saves the model to the location where it originally came from.- Specified by:
save
in interfaceILcdModelEncoder
- Parameters:
aModel
- the model to be saved.- Throws:
IllegalArgumentException
- if the model cannot be saved by this encoder (!canSave(aModel)
).
-
canExport
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 aILcdPanoramaModelDescriptor
. - 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 interfaceILcdModelEncoder
- 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:
- the given
-
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 interfaceILcdModelEncoder
- 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.
-