org.geotools.image.io.netcdf
Class NetcdfImageReader

java.lang.Object
  extended by javax.imageio.ImageReader
      extended by org.geotools.image.io.GeographicImageReader
          extended by org.geotools.image.io.StreamImageReader
              extended by org.geotools.image.io.FileImageReader
                  extended by org.geotools.image.io.netcdf.NetcdfImageReader
All Implemented Interfaces:
ucar.nc2.util.CancelTask

public class NetcdfImageReader
extends FileImageReader
implements ucar.nc2.util.CancelTask

Base implementation for NetCDF image reader. Pixels are assumed organized according the COARDS convention (a precursor of CF Metadata conventions), i.e. in (t,z,y,x) order, where x varies faster. The image is created from the two last dimensions (x,y). Additional dimensions (if any) are handled as below in the default implementation:

Example:
Assuming that:

Then the users can select the z value using IIOParam.setSourceBands(int[]). If no band is selected, then the default selection is the first band (0) only. Note that this is different than the usual Image I/O default, which is all bands.

Connection to DODS servers This image reader accepts File and URL inputs. In the later case, if and only if the URL uses the DODS protocol (as in "dods://opendap.aviso.oceanobs.com/"), then this image reader tries to connect to the DODS remote server. Otherwise the URL content is copied in a temporary file.

Since:
2.4
Version:
$Id: NetcdfImageReader.java 31017 2008-07-15 13:56:22Z desruisseaux $
Author:
Antoine Hnawia, Martin Desruisseaux

Nested Class Summary
static class NetcdfImageReader.Spi
          The service provider for NetcdfImageReader.
 
Field Summary
protected  ucar.nc2.Variable variable
          The data from the NetCDF file.
 
Fields inherited from class org.geotools.image.io.StreamImageReader
closeOnReset
 
Fields inherited from class javax.imageio.ImageReader
availableLocales, ignoreMetadata, input, locale, minIndex, originatingProvider, progressListeners, seekForwardOnly, updateListeners, warningListeners, warningLocales
 
Constructor Summary
NetcdfImageReader(NetcdfImageReader.Spi spi)
          Constructs a new NetCDF reader.
 
Method Summary
protected  void close()
          Closes the NetCDF file.
protected  javax.imageio.metadata.IIOMetadata createMetadata(ucar.nc2.dataset.NetcdfDataset file)
          Creates metadata for the specified NetCDF file.
protected  javax.imageio.metadata.IIOMetadata createMetadata(ucar.nc2.dataset.VariableDS variable)
          Creates metadata for the specified NetCDF variable.
protected  ucar.nc2.Variable findVariable(java.lang.String name)
          Returns the variable of the given name.
 javax.imageio.ImageReadParam getDefaultReadParam()
          Returns parameters initialized with default values appropriate for this format.
 int getDimension(int imageIndex)
          Returns the number of dimension of the image at the given index.
 int getHeight(int imageIndex)
          Returns the image height.
 javax.imageio.metadata.IIOMetadata getImageMetadata(int imageIndex)
          Returns the metadata associated with the image at the specified index.
 int getNumBands(int imageIndex)
          Returns the number of bands available for the specified image.
 int getNumImages(boolean allowSearch)
          Returns the number of images available from the current input source.
protected  int getRawDataType(int imageIndex)
          Returns the data type which most closely represents the "raw" internal data of the image.
 Statistics getStatistics(int imageIndex)
          Returns statistics about the sample values in the specified image.
 javax.imageio.metadata.IIOMetadata getStreamMetadata()
          Returns the metadata associated with the input source as a whole.
 java.lang.String[] getVariables()
          Returns the names of the variables to be read.
 int getWidth(int imageIndex)
          Returns the image width.
 boolean isCancel()
          Invoked by the NetCDF library during read operation in order to check if the task has been canceled.
protected  boolean prepareVariable(int imageIndex)
          Ensures that data are loaded in the NetCDF variable.
 java.awt.image.BufferedImage read(int imageIndex, javax.imageio.ImageReadParam param)
          Creates an image from the specified parameters.
 void setError(java.lang.String message)
          Invoked by the NetCDF library when an error occured during the read operation.
 void setVariables(java.lang.String[] variableNames)
          Sets the name of the variables to be read in a NetCDF file.
 
Methods inherited from class org.geotools.image.io.FileImageReader
getInputFile, getURLEncoding, isRandomAccessEasy, isTemporaryFile
 
Methods inherited from class org.geotools.image.io.StreamImageReader
dispose, finalize, getInputStream, getStreamLength, reset, setInput
 
Methods inherited from class org.geotools.image.io.GeographicImageReader
checkBandIndex, checkImageIndex, collapseNoDataValues, flipVertically, getDestination, getGeographicMetadata, getImageTypes, getRawImageType, getRawImageType, read, warningOccurred
 
Methods inherited from class javax.imageio.ImageReader
abort, abortRequested, addIIOReadProgressListener, addIIOReadUpdateListener, addIIOReadWarningListener, canReadRaster, checkReadParamBandSettings, clearAbortRequest, computeRegions, getAspectRatio, getAvailableLocales, getDestination, getFormatName, getImageMetadata, getInput, getLocale, getMinIndex, getNumThumbnails, getOriginatingProvider, getSourceRegion, getStreamMetadata, getThumbnailHeight, getThumbnailWidth, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, hasThumbnails, isIgnoringMetadata, isImageTiled, isSeekForwardOnly, processImageComplete, processImageProgress, processImageStarted, processImageUpdate, processPassComplete, processPassStarted, processReadAborted, processSequenceComplete, processSequenceStarted, processThumbnailComplete, processThumbnailPassComplete, processThumbnailPassStarted, processThumbnailProgress, processThumbnailStarted, processThumbnailUpdate, processWarningOccurred, processWarningOccurred, readAll, readAll, readAsRenderedImage, readerSupportsThumbnails, readRaster, readThumbnail, readTile, readTileRaster, removeAllIIOReadProgressListeners, removeAllIIOReadUpdateListeners, removeAllIIOReadWarningListeners, removeIIOReadProgressListener, removeIIOReadUpdateListener, removeIIOReadWarningListener, setInput, setInput, setLocale
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

variable

protected ucar.nc2.Variable variable
The data from the NetCDF file. The value for this field is set by prepareVariable(int) when first needed. This is typically (but not necessarly) an instance of VariableDS.

Constructor Detail

NetcdfImageReader

public NetcdfImageReader(NetcdfImageReader.Spi spi)
Constructs a new NetCDF reader.

Parameters:
spi - The service provider.
Method Detail

getVariables

public java.lang.String[] getVariables()
                                throws java.io.IOException
Returns the names of the variables to be read. The first name is assigned to image index 0, the second name to image index 1, etc.. In other words a call to read(imageIndex) will read the variable names variables[imageIndex] where variables is the value returned by this method.

The sequence of variable to be read can be changed by a call to setVariables(java.lang.String[]).

Returns:
The name of the variables to be read.
Throws:
java.io.IOException - if the NetCDF file can not be read.

setVariables

public void setVariables(java.lang.String[] variableNames)
Sets the name of the variables to be read in a NetCDF file. The first name is assigned to image index 0, the second name to image index 1, etc..

If variableNames is set to null (which is the default), then the variables will be inferred from the content of the NetCDF file.

Parameters:
variableNames - The set of variables to be assigned to image index.

getNumImages

public int getNumImages(boolean allowSearch)
                 throws java.lang.IllegalStateException,
                        java.io.IOException
Returns the number of images available from the current input source.

Overrides:
getNumImages in class GeographicImageReader
Parameters:
allowSearch - If true, the number of images will be returned even if a search is required.
Returns:
The number of images, or -1 if allowSearch is false and a search would be required.
Throws:
java.lang.IllegalStateException - if the input source has not been set.
java.io.IOException - if an error occurs reading the information from the input source.

getNumBands

public int getNumBands(int imageIndex)
                throws java.io.IOException
Returns the number of bands available for the specified image.

Overrides:
getNumBands in class GeographicImageReader
Parameters:
imageIndex - The image index.
Returns:
The number of bands available.
Throws:
java.io.IOException - if an error occurs reading the information from the input source.

getDimension

public int getDimension(int imageIndex)
                 throws java.io.IOException
Returns the number of dimension of the image at the given index.

Overrides:
getDimension in class GeographicImageReader
Parameters:
imageIndex - The image index.
Returns:
The number of dimension for the image at the given index.
Throws:
java.io.IOException - if an error occurs reading the information from the input source.
Since:
2.5

getStatistics

public Statistics getStatistics(int imageIndex)
                         throws java.io.IOException
Returns statistics about the sample values in the specified image. This is for informative purpose only and may be used when the metadata do not provides useful information about valid minimum and maximum values. Note that this method requires a full scan of image data and may be slow.

Parameters:
imageIndex - The index of the image to analyze.
Returns:
Statistics on the sample values in the given image.
Throws:
java.io.IOException - if an I/O error occured while reading the sample values.

getWidth

public int getWidth(int imageIndex)
             throws java.io.IOException
Returns the image width.

Specified by:
getWidth in class javax.imageio.ImageReader
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.

getHeight

public int getHeight(int imageIndex)
              throws java.io.IOException
Returns the image height.

Specified by:
getHeight in class javax.imageio.ImageReader
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.

getStreamMetadata

public javax.imageio.metadata.IIOMetadata getStreamMetadata()
                                                     throws java.io.IOException
Returns the metadata associated with the input source as a whole.

Overrides:
getStreamMetadata in class GeographicImageReader
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.

getImageMetadata

public javax.imageio.metadata.IIOMetadata getImageMetadata(int imageIndex)
                                                    throws java.io.IOException
Returns the metadata associated with the image at the specified index.

Overrides:
getImageMetadata in class GeographicImageReader
Parameters:
imageIndex - The image index.
Returns:
The metadata, or null if none.
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.

createMetadata

protected javax.imageio.metadata.IIOMetadata createMetadata(ucar.nc2.dataset.NetcdfDataset file)
                                                     throws java.io.IOException
Creates metadata for the specified NetCDF file. This method is invoked automatically by getStreamMetadata() when first needed. The default implementation returns an instance of NetcdfMetadata. Subclasses can override this method in order to create a more specific set of metadata.

Parameters:
file - The NetCDF dataset.
Returns:
The metadata for the given dataset.
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.

createMetadata

protected javax.imageio.metadata.IIOMetadata createMetadata(ucar.nc2.dataset.VariableDS variable)
                                                     throws java.io.IOException
Creates metadata for the specified NetCDF variable. This method is invoked automatically by getImageMetadata(int) when first needed. The default implementation returns an instance of NetcdfMetadata. Subclasses can override this method in order to create a more specific set of metadata.

Parameters:
variable - The NetCDF variable.
Returns:
The metadata for the given variable.
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.

getRawDataType

protected int getRawDataType(int imageIndex)
                      throws java.io.IOException
Returns the data type which most closely represents the "raw" internal data of the image.

Overrides:
getRawDataType in class GeographicImageReader
Parameters:
imageIndex - The index of the image to be queried.
Returns:
The data type, or DataBuffer.TYPE_UNDEFINED if unknown.
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.
See Also:
GeographicImageReader.getRawImageType(int, ImageReadParam, SampleConverter[])

prepareVariable

protected boolean prepareVariable(int imageIndex)
                           throws java.io.IOException
Ensures that data are loaded in the NetCDF variable. If data are already loaded, then this method do nothing.

This method is invoked automatically before any operation that require the NetCDF variable, including (but not limited to):

Parameters:
imageIndex - The image index.
Returns:
true if the variable changed as a result of this call, or false if the current value is already appropriate.
Throws:
java.lang.IndexOutOfBoundsException - if the specified index is outside the expected range.
java.lang.IllegalStateException - If ImageReader.input is not set.
java.io.IOException - If an error occured while reading the NetCDF file.

findVariable

protected ucar.nc2.Variable findVariable(java.lang.String name)
                                  throws java.io.IOException
Returns the variable of the given name. This method is similar to NetcdfFile.findVariable(String) except that the search is case-insensitive and an exception is thrown if no variable has been found for the given name.

Parameters:
name - The name of the variable to search.
Returns:
The variable for the given name.
Throws:
javax.imageio.IIOException - if no variable has been found for the given name.
java.io.IOException - If an error occured while reading the NetCDF file.

getDefaultReadParam

public javax.imageio.ImageReadParam getDefaultReadParam()
Returns parameters initialized with default values appropriate for this format.

Overrides:
getDefaultReadParam in class GeographicImageReader
Returns:
Parameters which may be used to control the decoding process using a set of default settings.

read

public java.awt.image.BufferedImage read(int imageIndex,
                                         javax.imageio.ImageReadParam param)
                                  throws java.io.IOException
Creates an image from the specified parameters.

Specified by:
read in class javax.imageio.ImageReader
Throws:
java.io.IOException - If an error occured while reading the NetCDF file.

isCancel

public boolean isCancel()
Invoked by the NetCDF library during read operation in order to check if the task has been canceled. Users should not invoke this method directly.

Specified by:
isCancel in interface ucar.nc2.util.CancelTask
Returns:
true if abort has been requested.

setError

public void setError(java.lang.String message)
Invoked by the NetCDF library when an error occured during the read operation. Users should not invoke this method directly.

Specified by:
setError in interface ucar.nc2.util.CancelTask
Parameters:
message - An error message to report.

close

protected void close()
              throws java.io.IOException
Closes the NetCDF file.

Overrides:
close in class FileImageReader
Throws:
java.io.IOException - If an error occured while accessing the NetCDF file.
See Also:
StreamImageReader.closeOnReset


Copyright © 1996-2010 Geotools. All Rights Reserved.