org.geotoolkit.image.io.mosaic
Class MosaicProfiler

Object
  MosaicProfiler

@ThreadSafe
public class MosaicProfiler
extends Object

Profiles the loading of random rectangular regions using a given TileManager. The images to load while have random locations and random sizes, constrained between a minimal and maximal size. A random subsampling will be requested, constrained between a minimum and maximum subsampling.

More details on the algorithm used by this class are defined in the following methods:

• estimateEfficiency(int)

The example below profiles a mosaic for different subsampling values. See MosaicImageReadParam for an explanation about why invoking setSubsamplingChangeAllowed(true) is strongly recommended.

MosaicProfiler profiler = new MosaicProfiler(mosaic);
profiler.setSubsamplingChangeAllowed(true); // STRONGLY RECOMMANDED
profiler.setMaxSubsampling(1);
for (int i=1; i<20; i++) {
    profiler.setMinSubsampling(i);
    double efficiency = profiler.estimateEfficiency(100);
    System.out.println("Subsampling=" + i + ", estimated efficiency=" + efficiency);
}

Since:

3.00

Version:

3.00

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

TileManager

mosaic The mosaic to profile.

Constructor Summary

MosaicProfiler(TileManager mosaic)
Creates a profiler for the given mosaic.

Method Summary

Statistics	estimateEfficiency(int numSamples) Returns an empirical estimation of the efficiency of loading images using the mosaic.
Dimension	getMaxSize() Returns the maximal size of the images to load.
Dimension	getMaxSubsampling() Returns the maximal subsampling of the random rectangular regions to load.
Dimension	getMinSize() Returns the minimal size of the images to load.
Dimension	getMinSubsampling() Returns the minimal subsampling of the random rectangular regions to load.
Dimension	getMosaicSize() Returns the size of the mosaic given to the constructor.
Rectangle	getQueryRegion() Returns the region in which random rectangles will be calculated.
boolean	isSubsamplingChangeAllowed() Returns true if the mosaic is allowed to change the subsampling to some more efficient value.
void	setMaxSize(Dimension size) Sets the maximal size of the images to load.
void	setMaxSize(int size) Convenience method setting the maximal size to the same value along x and y axis.
void	setMaxSubsampling(Dimension subsampling) Sets the maximal subsampling of the random rectangular regions to load.
void	setMaxSubsampling(int subsampling) Convenience method setting the maximal subsampling to the same value along x and y axis.
void	setMinSize(Dimension size) Sets the minimal size of the images to load.
void	setMinSize(int size) Convenience method setting the minimal size to the same value along x and y axis.
void	setMinSubsampling(Dimension subsampling) Sets the minimal subsampling of the random rectangular regions to load.
void	setMinSubsampling(int subsampling) Convenience method setting the minimal subsampling to the same value along x and y axis.
void	setQueryRegion(Rectangle bounds) Sets the region in which random rectangles will be calculated.
void	setSeed(long seed) Sets the seed of the random number generator.
void	setSubsamplingChangeAllowed(boolean allowed) Sets whatever the mosaic will be allowed to change the subsampling to some more efficient value.

Methods inherited from class Object

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

Field Detail

mosaic

public final TileManager mosaic

The mosaic to profile.

Constructor Detail

MosaicProfiler

public MosaicProfiler(TileManager mosaic)
               throws IOException

Creates a profiler for the given mosaic.

Parameters:

mosaic - The mosaic to profile.

Throws:

IOException - If it was necessary to fetch an image dimension from its reader and this operation failed.

Method Detail

setSeed

public void setSeed(long seed)

Sets the seed of the random number generator. If this profiler is set to the same seed than a previous profiling session and if the properties (minimum and maximal tile size and subsampling) have not been changed, then the generated random rectangular regions while be the same than the previous profiling session.

Parameters:

seed - The seed to be given to the random number generator.

getQueryRegion

public Rectangle getQueryRegion()

Returns the region in which random rectangles will be calculated. On MosaicProfiler construction, this is set to the region covered by the whole mosaic.

Returns:

The region in which random rectangles will be calculated.

setQueryRegion

public void setQueryRegion(Rectangle bounds)
                    throws IOException

Sets the region in which random rectangles will be calculated. This method computes the intersection of the given rectangle with the mosaic bounds, and the result must be non-empty.

Parameters:

bounds - The region in which random rectangles will be calculated.

Throws:

IOException - If it was necessary to fetch an image dimension from its reader and this operation failed.

getMosaicSize

public Dimension getMosaicSize()
                        throws IOException

Returns the size of the mosaic given to the constructor.

Returns:

The mosaic size.

Throws:

IOException - If it was necessary to fetch an image dimension from its reader and this operation failed.

getMinSize

public Dimension getMinSize()

Returns the minimal size of the images to load.

Returns:

The minimal size of the images to load.

setMinSize

public void setMinSize(Dimension size)

Sets the minimal size of the images to load. If the given size is greater than the maximal size, then the maximal size will be increased accordingly.

Parameters:

size - The minimal size of the images to load.

setMinSize

public void setMinSize(int size)

Convenience method setting the minimal size to the same value along x and y axis.

Parameters:

size - The minimal width and height of the images to load.

getMaxSize

public Dimension getMaxSize()

Returns the maximal size of the images to load.

Returns:

The maximal size of the images to load.

setMaxSize

public void setMaxSize(Dimension size)

Sets the maximal size of the images to load. If the given size is smaller than the minimal size, then the minimal size will be reduced accordingly.

Parameters:

size - The maximal size of the images to load.

setMaxSize

public void setMaxSize(int size)

Convenience method setting the maximal size to the same value along x and y axis.

Parameters:

size - The maximal width and height of the images to load.

getMinSubsampling

public Dimension getMinSubsampling()

Returns the minimal subsampling of the random rectangular regions to load.

Returns:

The minimal subsampling of the regions to load.

setMinSubsampling

public void setMinSubsampling(Dimension subsampling)

Sets the minimal subsampling of the random rectangular regions to load. If the given subsampling is greater than the maximal subsampling, then the maximal subsampling will be increased accordingly.

Parameters:

subsampling - The minimal subsampling of the regions to load.

setMinSubsampling

public void setMinSubsampling(int subsampling)

Convenience method setting the minimal subsampling to the same value along x and y axis.

Parameters:

subsampling - The minimal subsampling along x and y axis.

getMaxSubsampling

public Dimension getMaxSubsampling()

Returns the maximal subsampling of the random rectangular regions to load.

Returns:

The maximal subsampling of the regions to load.

setMaxSubsampling

public void setMaxSubsampling(Dimension subsampling)

Sets the maximal subsampling of the random rectangular regions to load. If the given subsampling is smaller than the minimal subsampling, then the minimal subsampling will be reduced accordingly.

Parameters:

subsampling - The maximal subsampling of the regions to load.

setMaxSubsampling

public void setMaxSubsampling(int subsampling)

Convenience method setting the maximal subsampling to the same value along x and y axis.

Parameters:

subsampling - The maximal subsampling along x and y axis.

isSubsamplingChangeAllowed

public boolean isSubsamplingChangeAllowed()

Returns true if the mosaic is allowed to change the subsampling to some more efficient value. The default value is false, which means that the mosaic will use exactly the given subsampling and may leads to very slow reading.

Returns:

true if the mosaic is allowed to change the subsampling.

See Also:

MosaicImageReadParam.isSubsamplingChangeAllowed()

setSubsamplingChangeAllowed

public void setSubsamplingChangeAllowed(boolean allowed)

Sets whatever the mosaic will be allowed to change the subsampling to some more efficient value. Users are strongly encouraged to set this value to true, which is not the default because doing so would violate the ImageReader contract.

Parameters:

allowed - true if the mosaic is allowed to change the subsampling.

See Also:

MosaicImageReadParam.setSubsamplingChangeAllowed(boolean)

estimateEfficiency

public Statistics estimateEfficiency(int numSamples)
                              throws IOException

Returns an empirical estimation of the efficiency of loading images using the mosaic. This method creates the given amount of random rectangles in the area of the mosaic, then estimates the theorical cost that loading those images would have. This is a only a guess - the images are not really loaded.

The highest value that this method can return is 1, which means that optimal loading (defined below) would occur. Values lower than 1 are the average time of image loadings compared to the optimal case. For example a value of 0.5 means that the theorical image loading time (defined below) is on average two time greater than it would be if it was possible to read all images optimally.

Definition of terms
The "theorical image loading time" is defined as proportional to the amount of pixels to read, assuming that each tile is read in a "all or nothing" fashion. This is only a gross approximation of the reality since image compression induces non-linear relationship between the amount of pixels and the loading time, and some image formats like TIFF and JPEG2000 can be tiled - thus breaking the "all or nothing" assumption.

The "optimal loading" case is defined as the case where every pixels to be traversed while reading tiles are useful to the requested image, with no pixel to discart because of croping or subsampling.

Parameters:

numSamples - The number of rectangular region to simulate loading.

Returns:

The estimated efficiency of loading images, as a value between 0 and 1 inclusve. Higher values are better.

Throws:

IOException - If it was necessary to fetch an image dimension from its reader and this operation failed.