org.geotools.image.io.mosaic
Class MosaicImageReadParam

java.lang.Object
  extended by javax.imageio.IIOParam
      extended by javax.imageio.ImageReadParam
          extended by org.geotools.image.io.mosaic.MosaicImageReadParam

public class MosaicImageReadParam
extends javax.imageio.ImageReadParam

The parameters for MosaicImageReader. Users are strongly encouraged to invoke the following:

 parameters.setSubsamplingChangeAllowed(true);
 
Explanation: the tile manager will select the tile overviews depending on the source subsampling defined in this parameter object. Suppose that an image size is 1000×1000 pixels and this image has an overview of 500×500 pixels. If the image (always 1000×1000 pixels from user's point of view) is requested with a subsampling of (6,6) along (x,y) axis, then the mosaic image reader will detect that it can read the 500×500 pixels overview with a subsampling of (3,3) instead. But if the requested subsampling was (7,7), then the reader can not use the overview because it would require a subsampling of (3.5, 3.5) and fractional subsamplings are not allowed. It will read the full 1000×1000 pixels image instead, thus leading to lower performance even if we would have expected the opposite from a higher subsampling value.

To avoid this problem, MosaicImageReader can adjust automatically the subsampling parameter to the highest subsampling that overviews can handle, not greater than the specified subsampling. But this adjustment is not allowed by default because it would violate the usual ImageReader contract. It is allowed only if the setSubsamplingChangeAllowed(boolean) method has been explicitly invoked with value true.

If subsampling changes are allowed, then the values defined in this MosaicImageReadParam will be modified during the read process and can be queried once the reading is finished.

Since:
2.5
Version:
$Id: MosaicImageReadParam.java 30729 2008-06-16 09:26:48Z desruisseaux $
Author:
Martin Desruisseaux

Field Summary
 
Fields inherited from class javax.imageio.ImageReadParam
canSetSourceRenderSize, destination, destinationBands, minProgressivePass, numProgressivePasses, sourceRenderSize
 
Fields inherited from class javax.imageio.IIOParam
controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, subsamplingYOffset
 
Constructor Summary
  MosaicImageReadParam()
          Constructs default parameters for any mosaic image reader.
protected MosaicImageReadParam(MosaicImageReader reader)
          Constructs default parameters for the given image reader.
 
Method Summary
 javax.imageio.IIOParamController getDefaultController()
          Returns the default controller.
 ImageTypePolicy getImageTypePolicy()
          Returns the policy for computing image types.
 boolean getNullForEmptyImage()
          If true, then the read method is allowed to return null if no tile intersect the source region to be read.
protected  javax.imageio.ImageReadParam getTileParameters(javax.imageio.ImageReader reader)
          Returns the parameters to use for reading an image from the given image reader.
 boolean hasController()
          Returns true if there is a controller installed.
 boolean isSubsamplingChangeAllowed()
          Returns true if the mosaic image reader is allowed to change the subsampling to some more efficient value.
 void setImageTypePolicy(ImageTypePolicy policy)
          Sets the policy for computing image types.
 void setNullForEmptyImage(boolean allowed)
          Sets whatever the read method is allowed to return null when no tile intersect the source region to be read.
 void setSubsamplingChangeAllowed(boolean allowed)
          Sets whatever the mosaic image reader will be allowed to change the subsampling to some more efficient value.
 
Methods inherited from class javax.imageio.ImageReadParam
canSetSourceRenderSize, getDestination, getDestinationBands, getSourceMaxProgressivePass, getSourceMinProgressivePass, getSourceNumProgressivePasses, getSourceRenderSize, setDestination, setDestinationBands, setDestinationType, setSourceProgressivePasses, setSourceRenderSize
 
Methods inherited from class javax.imageio.IIOParam
activateController, getController, getDestinationOffset, getDestinationType, getSourceBands, getSourceRegion, getSourceXSubsampling, getSourceYSubsampling, getSubsamplingXOffset, getSubsamplingYOffset, setController, setDestinationOffset, setSourceBands, setSourceRegion, setSourceSubsampling
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MosaicImageReadParam

public MosaicImageReadParam()
Constructs default parameters for any mosaic image reader. Parameters created by this constructor will not have controller. Consider invoking MosaicImageReader.getDefaultReadParam() for parameters better suited to a particular reader instance.


MosaicImageReadParam

protected MosaicImageReadParam(MosaicImageReader reader)
Constructs default parameters for the given image reader. This constructor is provided for subclassing only. Uses MosaicImageReader.getDefaultReadParam() instead.

Parameters:
reader - The image reader, or null if none.
Method Detail

isSubsamplingChangeAllowed

public boolean isSubsamplingChangeAllowed()
Returns true if the mosaic image reader is allowed to change the subsampling to some more efficient value. The default value is false, which means that the reader will use exactly the given subsampling and may leads to very slow reading. See class javadoc.

Returns:
true if the mosaic image reader is allowed to change the subsampling.

setSubsamplingChangeAllowed

public void setSubsamplingChangeAllowed(boolean allowed)
Sets whatever the mosaic image reader 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. See class javadoc for more details.

Parameters:
allowed - true if the mosaic image reader is allowed to change the subsampling.

getNullForEmptyImage

public boolean getNullForEmptyImage()
If true, then the read method is allowed to return null if no tile intersect the source region to be read. The default value is false.

Note that a non-null image is not necessarily non-empty. A non-null image intersects at least one tile, but that tile could be empty in the intersection area.

Returns:
true if the read method is allowed to return null.

setNullForEmptyImage

public void setNullForEmptyImage(boolean allowed)
Sets whatever the read method is allowed to return null when no tile intersect the source region to be read. Setting this flag to true speedup the read process in region that doesn't intersect any tile, at the cost of requerying the caller to handle null return value.

Parameters:
allowed - true if the read method is allowed to return null.

getImageTypePolicy

public ImageTypePolicy getImageTypePolicy()
Returns the policy for computing image types. If no policy has been specified, then this method returns null. In the later case, the reader will use its default policy.

Returns:
The policy for computing image types.

setImageTypePolicy

public void setImageTypePolicy(ImageTypePolicy policy)
Sets the policy for computing image types.

Parameters:
policy - The new policy, or null for reader default policy.

getTileParameters

protected javax.imageio.ImageReadParam getTileParameters(javax.imageio.ImageReader reader)
Returns the parameters to use for reading an image from the given image reader. This method is invoked automatically by MosaicImageReader. The default implementation invokes ImageReader.getDefaultReadParam() and copies the source bands, destination bands and progressive passes settings. Other settings like source region don't need to be copied since they will be computed by the mosaic image reader.

Subclasses can override this method if they want to configure the parameters for tile readers in an other way. Note however that MosaicController provides an other way to configure parameters.

Parameters:
reader - The tile reader.
Returns:
The parameter for reading a tile using the given reader.

hasController

public boolean hasController()
Returns true if there is a controller installed. The implementation in this class is more conservative than the default implementation in that if the current controller is the default controller instance, then this method returns true only if the controller for at least one tile parameters returned true.

Overrides:
hasController in class javax.imageio.IIOParam

getDefaultController

public javax.imageio.IIOParamController getDefaultController()
Returns the default controller. This is typically an instance of MosaicController, but this is not mandatory.

Overrides:
getDefaultController in class javax.imageio.IIOParam


Copyright © 1996-2010 Geotools. All Rights Reserved.