com.luciad.fusion.tilestore

LuciadLightspeedClass TLfnTileStoreUtil

java.lang.Object

com.luciad.fusion.tilestore.TLfnTileStoreUtil

public final class TLfnTileStoreUtil
extends Object

Utility methods for Tile Stores.

Since:

2012.0

Method Summary

Modifier and Type	Method and Description
static Future<?>	copyCoverage(ALfnCoverage aSourceCoverage, ALfnTileStore aTargetTileStore, ILfnImportHandler aHandler) Copies the given source coverage to the given target Tile Store.
static Future<?>	copyCoverage(ALfnCoverage aSourceCoverage, ALfnTileStore aTargetTileStore, String aTargetCoverageId, ILfnProgressCallback<ALfnTileStore.WriteResult> aCallback) Copies a given source coverage to a the given target Tile Store with a new ID.
static Future<?>	copyCoverageTileData(ALfnCoverage aSourceCoverage, ALfnCoverage aTargetCoverage, ILfnImportHandler aHandler) Deprecated. use copyCoverage(ALfnCoverage, ALfnTileStore, String, ILfnProgressCallback) instead
static void	createTileStore(File aTileStoreDir, ALfnEnvironment aEnvironment) Creates a new, empty Tile Store at the given path.
static double	getAssetPartPixelDensity(TLfnRasterCoverageMetadata aCoverageMetadata, TLfnRasterAssetMetadata aAssetMetadata, TLfnRasterAssetMetadata.RasterAssetPart aAssetPart) Gets the asset part pixel density expressed in the coverage's georeference.
static double	getMaxAssetPartPixelDensity(TLfnRasterCoverageMetadata aCoverageMetadata, ALfnTileStore aTileStore) Gets the maximum pixel density of all the asset parts of all the assets of a coverage, expressed in the coverage's georeference.
static double	getMaxCoveragePixelDensity(TLfnRasterCoverageMetadata aCoverageMetadata, ALfnTileStore aTileStore) Gets the maximum coverage pixel density for a given coverage.
static TLfnRasterAssetMetadata.Builder	newCoverageAsAssetMetadataBuilder(TLfnRasterCoverageMetadata aCoverageMetadata, ALfnTileStore aTileStore) Creates a new asset metadata builder for a given coverage metadata.
static TLfnRasterAssetMetadata.Builder	newCoverageAsAssetMetadataBuilder(TLfnRasterCoverageMetadata aCoverageMetadata, double aPixelDensity, ALfnTileStore aTileStore) Deprecated. use newCoverageAsAssetMetadataBuilder(TLfnRasterCoverageMetadata, ALfnTileStore) instead
static void	optimizeTileLayout(ALfnCoverageMetadata aSource, ALfnCoverageMetadata.Builder<?> aTarget) Optimizes the tile layout of the target coverage, using the tile size of the source coverage and the bounding box of the target coverage as a given.
static void	optimizeTileSize(TLfnRasterCoverageMetadata aSource, TLfnRasterCoverageMetadata.Builder aTarget) Optimizes the tile size of the target coverage, using the tile size of the source coverage and the tile layout of the target coverage as a given.

Methods inherited from class java.lang.Object

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

Method Detail

createTileStore

public static void createTileStore(File aTileStoreDir,
                                   ALfnEnvironment aEnvironment)
                            throws IOException

Creates a new, empty Tile Store at the given path.

• ID: a new UUID
• Name: "LuciadFusion Tile Store"
• No abstract or keywords

Parameters:

aTileStoreDir - The root of the new Tile Store

aEnvironment - The environment

Throws:

IOException - If the Tile Store could not be created

Since:

2013.0

copyCoverage

public static Future<?> copyCoverage(ALfnCoverage aSourceCoverage,
                                     ALfnTileStore aTargetTileStore,
                                     ILfnImportHandler aHandler)

Copies the given source coverage to the given target Tile Store. A new coverage with the same ID and same properties will be created in the target Tile Store, and all the tile data will be copied from source to target. The assets are not copied to the target.

When the copy is cancelled or fails, a best effort is made to remove the incomplete coverage from the target Tile Store. If this removal fails, it will fail silently and a potentially incomplete coverage may still be on the target Tile Store.

When a coverage with the same ID already exists in the target Tile Store, the copy will fail. As a consequence, this method cannot be used to 'clone' a coverage within the same Tile Store. If that is what you desire, have a look at copyCoverage(ALfnCoverage, ALfnTileStore, String, ILfnProgressCallback).

Parameters:

aSourceCoverage - the source coverage to be copied

aTargetTileStore - the Tile Store to which the source coverage should be copied

aHandler - a handler for progress and error reporting

Returns:

a future that will complete when the copy is complete

copyCoverage

public static Future<?> copyCoverage(ALfnCoverage aSourceCoverage,
                                     ALfnTileStore aTargetTileStore,
                                     String aTargetCoverageId,
                                     ILfnProgressCallback<ALfnTileStore.WriteResult> aCallback)

Copies a given source coverage to a the given target Tile Store with a new ID. A new coverage will be created in the target Tile Store, and all the tile data will be copied from source to target.

• Assets are not copied to the target. Unless you don't copy the assets yourself, this will lead to a coverage with dangling asset infos on the target. An asset info is said to be dangling if the asset it points to does not exist. Dangling asset info is usually not a problem.
• The coverage data doesn't become visible until the operation completes successfully. The asset infos of the target coverage will initially be set to ALfnCoverageMetadata.AssetInfo.STATUS_INCOMPLETE, and when the operation completes successfully they will be set to ALfnCoverageMetadata.AssetInfo.STATUS_COMPLETE.
• When the copy is cancelled or fails, a best effort is made to remove the incomplete coverage from the target Tile Store. If removal fails, it will fail silently and the data won't become visible on the target.
• If the coverage already exists on the target Tile Store, the operation will fail. In this case, the target coverage will not be deleted on the Tile Store.
• You can use this for copying a coverage to another coverage with a different ID on the same Tile Store.

Parameters:

aSourceCoverage - the source coverage, never null

aTargetTileStore - the target Tile Store, which may be the same as the source coverage's Tile Store, but never null

aTargetCoverageId - the target coverage ID, or null to indicate that the target coverage ID must be the same as the source coverage ID

aCallback - a callback for progress and error reporting

Returns:

a future that will complete when the copy is complete

copyCoverageTileData

public static Future<?> copyCoverageTileData(ALfnCoverage aSourceCoverage,
                                             ALfnCoverage aTargetCoverage,
                                             ILfnImportHandler aHandler)

Deprecated. use copyCoverage(ALfnCoverage, ALfnTileStore, String, ILfnProgressCallback) instead

Copies the tile data from given source coverage to the given target coverage.

It has been deprecated in favor of copyCoverage(ALfnCoverage, ALfnTileStore, String, ILfnProgressCallback) because it not user-friendly:

• The caller must ensure that target coverage metadata exits on the target Tile Store.
• The caller must set the asset info in the target coverage metadata to ALfnCoverageMetadata.AssetInfo.STATUS_INCOMPLETE before calling this method. If not, the tile data on the target coverage will not become visible afterwards.
• The caller must set the asset info in the target coverage metadata to ALfnCoverageMetadata.AssetInfo.STATUS_COMPLETE when the future of this method completed successfully. If not, the tile data on the target coverage will not become visible afterwards.
• The caller is responsible for deleting the target coverage in case of failure. It is not absolutely necessary to do so, but if you don't there may be clutter left on the target.

Note that the source and target coverages may be on the same Tile Store, but in that case they must not have the same ID or this operation will fail. This method may be used to 'clone' a coverage within the same Tile Store, as long as the target coverage has a different ID. The code to do so would look something like this:

 ALfnTileStore tileStore;
 ALfnCoverage source = tileStore.getCoverage("id");
 ALfnCoverageMetadata sourceMetadata = source.getMetadata();
 List<AssetInfo> assetInfos = sourceMetadata.getAssetInfos();
 // You'll have to implement copyAllAssetInfosAndSetTo yourself.
 List<AssetInfo> incompleteAssetInfos = copyAllAssetInfosAndSetTo(assetInfos, STATUS_INCOMPLETE);
 ALfnCoverageMetadata incompleteTargetMetadata = source.getMetadata().asBuilder().id("newId")
     .assetInfos(incompleteAssetInfos).build();
 tileStore.putResourceMetadata(incompleteTargetMetadata);
 ALfnCoverage target = tileStore.getCoverage(targetMetadata.getId());
 copyCoverageTileData(source, target, handler).get();
 List<AssetInfo> completeAssetInfos = copyAllAssetInfosAndSetTo(assetInfos, STATUS_COMPLETE);
 ALfnCoverageMetadata completeTargetMetadata = target.getMetadata().asBuilder()
     .assetInfos(completeAssetInfos).build()
 tileStore.putResourceMetadata(completeTargetMetadata);
 

Parameters:

aSourceCoverage - the source coverage to be copied

aTargetCoverage - the target coverage to copy the data to

aHandler - a handler for progress and error reporting

Returns:

a future that will complete when both export and import are completed

getMaxAssetPartPixelDensity

public static double getMaxAssetPartPixelDensity(TLfnRasterCoverageMetadata aCoverageMetadata,
                                                 ALfnTileStore aTileStore)
                                          throws IOException,
                                                 TLfnServiceException

Gets the maximum pixel density of all the asset parts of all the assets of a coverage, expressed in the coverage's georeference. Asset parts for which the pixel density could not be expressed in the coverage's georeference will have a pixel density 0.0. In case there are no asset parts, the result of this method will be NEGATIVE_INFINITY.

Parameters:

aCoverageMetadata - the coverage metadata linking to the assets to get the asset parts from

aTileStore - a Tile Store where the asset metadata will be retrieved from

Returns:

the maximum pixel density of all the asset parts of the coverage, possibly NEGATIVE_INFINITY in case there are no asset parts, and possibly 0.0 in case no asset parts have a pixel density that can be expressed in the coverage's georeference.

Throws:

IOException - indicates something went wrong retrieving the asset metadata from the Tile Store

TLfnServiceException - indicates something went wrong retrieving the asset metadata from the Tile Store

getAssetPartPixelDensity

public static double getAssetPartPixelDensity(TLfnRasterCoverageMetadata aCoverageMetadata,
                                              TLfnRasterAssetMetadata aAssetMetadata,
                                              TLfnRasterAssetMetadata.RasterAssetPart aAssetPart)

Gets the asset part pixel density expressed in the coverage's georeference. In case the coverage and asset georeferences are equal, this method returns the exact same result as TLfnRasterAssetMetadata.RasterAssetPart.getPixelDensity().

In case the asset part's pixel density could not be expressed in the coverage's georeference, this method returns 0.0.

Parameters:

aCoverageMetadata - the coverage metadata defining the georeference to express pixel densities in (target georeference)

aAssetMetadata - the asset metadata defining the georeference the asset parts' pixel densities are expressed in (source georeference). The coverage metadata should have an asset info about this asset, although this method does not enforce this.

aAssetPart - the asset part to get the pixel density of. This asset part should be part of the asset metadata, although this method does not enforce this.

Returns:

the pixel density of the asset part, expressed in the coverage's georeference, or 0.0 in case the asset part's pixel density could not be expressed in the coverage's georeference

getMaxCoveragePixelDensity

public static double getMaxCoveragePixelDensity(TLfnRasterCoverageMetadata aCoverageMetadata,
                                                ALfnTileStore aTileStore)
                                         throws IOException,
                                                TLfnServiceException

Gets the maximum coverage pixel density for a given coverage. The maximum coverage pixel density is the pixel density corresponding to the maximum level of a (raster) coverage. The maximum level depends on the assets of a coverage; it may change when assets are added to it (additional detail).

The maximum coverage pixel density will be zero if the coverage has an infinitely wide bounding box, or if the level-0 row- and column counts are 0. This is considered a degenerate case.

Another degenerate case is the one where maxCoveragePixelDensity > maxAssetPartPixelDensity. This means that the pixel densities of all asset parts are lower than the coverage pixel density at level 0. In this case, level 0 is the maximum level and the coverage pixel density is the pixel density at level 0.

All other cases are considered non-degenerate, and for those cases the following is true: maxAssetPartPixelDensity <= maxCoveragePixelDensity < (4 * maxAssetPartPixelDensity).

Parameters:

aCoverageMetadata - the metadata describing the coverage to get the maximum coverage pixel density of

aTileStore - the Tile Store to get the asset metadata from

Returns:

the maximum coverage pixel density of the coverage, always a positive non-zero number

Throws:

IOException - indicates something went wrong retrieving the asset metadata from the Tile Store

TLfnServiceException - indicates something went wrong retrieving the asset metadata from the Tile Store

optimizeTileLayout

public static void optimizeTileLayout(ALfnCoverageMetadata aSource,
                                      ALfnCoverageMetadata.Builder<?> aTarget)

Optimizes the tile layout of the target coverage, using the tile size of the source coverage and the bounding box of the target coverage as a given. This operation will overwrite the level-0 row- and column counts on the target coverage metadata builder.

The intended use of this method is to prepare a coverage for cropping. The new bounding box is expected to have already been set on the target coverage metadata builder, for it will be used for the optimization.

Parameters:

aSource - the source coverage metadata

aTarget - the target coverage metadata (cropped) of which the level-0 row- and column counts will be optimized

optimizeTileSize

public static void optimizeTileSize(TLfnRasterCoverageMetadata aSource,
                                    TLfnRasterCoverageMetadata.Builder aTarget)

Optimizes the tile size of the target coverage, using the tile size of the source coverage and the tile layout of the target coverage as a given. This operation will overwrite the tile width and tile height on the target coverage metadata builder.

The intended use of this method is to prepare a coverage for cropping. The new bounding box and tile layout are expected to have already been set on the target coverage metadata builder, for they will be used as input for the optimization.

Parameters:

aSource - the source coverage, of which the bounding box, level-0 row- and column count, tile width and height are used as inputs

aTarget - the target coverage, of which the bounding box, level-0 row- and column count are used as inputs, and on which the optimized tile width and height will be written as output

newCoverageAsAssetMetadataBuilder

public static TLfnRasterAssetMetadata.Builder newCoverageAsAssetMetadataBuilder(TLfnRasterCoverageMetadata aCoverageMetadata,
                                                                                double aPixelDensity,
                                                                                ALfnTileStore aTileStore)

Deprecated. use newCoverageAsAssetMetadataBuilder(TLfnRasterCoverageMetadata, ALfnTileStore) instead

Creates a new asset metadata builder for a given coverage metadata. The new asset will also have the type, name, abstract, bounding box, georeference, ISO metadata and supported coverage types of the coverage. It will have an asset part for every asset part of every asset which contributed to the coverage. Each of these asset parts will have the same location URI, pointing to the same coverage, but a bounding box and pixel density corresponding to a single one of the original asset parts. If necessary, bounding box and pixel density will be transformed to the new asset's georeference.

On top of these asset parts, the new asset will have one extra asset part with pixel density 0, with the bounding box of the coverage. This ensures that the bounding box of the asset metadata is the same as that of the coverage, even in case the bounding box is larger than the union of the bounding boxes of all the asset parts. The pixel density of 0 ensures that this asset does not add any "depth" to the asset metadata.

Beware that this method does not set an asset ID on the builder. It is up to the caller to do that.

Note that there are potentially a large amount of asset parts, all pointing to the same source, yet fusion will only decode a single model. This ensures that memory use remains virtually constant, regardless of how many asset parts there are.

Parameters:

aCoverageMetadata - the coverage metadata to be used as input for the asset. Currently, only TLfnRasterCoverageMetadata is supported.

aPixelDensity - unused

aTileStore - a Tile Store to build the asset's location (URI) from, and to retrieve the original asset metadata from

Returns:

the asset metadata builder for the coverage-as-asset

newCoverageAsAssetMetadataBuilder

public static TLfnRasterAssetMetadata.Builder newCoverageAsAssetMetadataBuilder(TLfnRasterCoverageMetadata aCoverageMetadata,
                                                                                ALfnTileStore aTileStore)
                                                                         throws IOException,
                                                                                TLfnServiceException

Creates a new asset metadata builder for a given coverage metadata. The new asset will also have the type, name, abstract, bounding box, georeference, ISO metadata and supported coverage types of the coverage. It will have an asset part for every asset part of every asset which contributed to the coverage. Each of these asset parts will have the same location URI, pointing to the same coverage, but a bounding box and pixel density corresponding to a single one of the original asset parts. If necessary, bounding box and pixel density will be transformed to the new asset's georeference.

On top of these asset parts, the new asset will have one extra asset part with pixel density 0, with the bounding box of the coverage. This ensures that the bounding box of the asset metadata is the same as that of the coverage, even in case the bounding box is larger than the union of the bounding boxes of all the asset parts. The pixel density of 0 ensures that this asset does not add any "depth" to the asset metadata.

Beware that this method does not set an asset ID on the builder. It is up to the caller to do that.

Note that there are potentially a large amount of asset parts, all pointing to the same source, yet fusion will only decode a single model. This ensures that memory use remains virtually constant, regardless of how many asset parts there are.

Parameters:

aCoverageMetadata - the original coverage metadata

aTileStore - a Tile Store to build the asset's location (URI) from, and to retrieve the original asset metadata from

Returns:

a new raster asset metadata builder with all parameters set except the asset ID

Throws:

IOException - if there was a failure retrieving the metadata of one of the original assets from the Tile Store

TLfnServiceException - if there was a failure retrieving the metadata of one of the original assets from the Tile Store