ImageReader
SpatialImageReader
StreamImageReader
FileImageReader
NetcdfImageReader
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Object
public class NetcdfImageReader
Base implementation for NetCDF image readers. Pixels are assumed organized according the COARDS convention (a precursor of CF Metadata conventions). For a 4-D dataset with horizontal, vertical and temporal ordinates, the dimension are typically (x,y,z,t) where x index varies faster.
Note:
NetCDF data files actually declare dimensions in reverse order. For the above example,
the dimensions would be declared as (t,z,y,x). This
NetcdfImageReader plugin reverse the order of dimensions read in the NetCDF file,
in order to get an ordering consistent with the ordering used by other plugins.
The image is created from the (x,y) dimensions in the above example.
Additional dimensions (if any) are ignored by default: only the slice at index 0 is read,
which is z0 and t0 in the example above. See
below for selecting slices in other dimensions.
Specifying the variable to read
Each variable having at least two dimensions (except the variables used for Coordinate System
axes) is an image. The variables to read can be specified using the methods defined in the
NamedImageStore interface, as in the example below:
imageReader.setImageNames("temperature", "salinity");
BufferedImage temperature = imageReader.read(0);
BufferedImage salinity = imageReader.read(1);imageReader.setBandNames(0, "WindSpeed-U", "WindSpeed-V"); BufferedImage windSpeed = imageReader.read(0); // windSpeed is now an image with two bands.
Specifying the slice to read in extra dimensions
For any dimension greater than 2, the region to read can be specified in two different ways:
DimensionSlice objects, which are
associated to the SpatialImageReadParam object controlling the reading
process. This approach is similar to the WCS 2.0 specification.MultidimensionalImageStore interface. This approach allows
compatibility with library working only with the Java Image I/O API.
Connection to DODS servers
This image reader accepts String, File, URL and URI inputs.
The input can use the DODS protocol (as in "dods://opendap.aviso.oceanobs.com/"),
in order to connect to the specified DODS remote server.
Support of related formats
This implementation uses the UCAR
NetCDF library for reading data. Consequently, it can be used for reading other formats
supported by that library. For a list of supported formats, see
file types
and remote access protocols on the NetCDF web site.
NetcdfCRS
| coverage/geotk-coverageio-netcdf (download) | View source code for this class |
| Nested Class Summary | |
|---|---|
static class |
NetcdfImageReader.Spi
The service provider for NetcdfImageReader. |
| Field Summary | |
|---|---|
protected Variable |
variable
The data from the NetCDF file for a given image index. |
| Fields inherited from class StreamImageReader |
|---|
closeOnReset |
| Fields inherited from class ImageReader |
|---|
availableLocales, ignoreMetadata, input, locale, minIndex, originatingProvider, progressListeners, seekForwardOnly, updateListeners, warningListeners, warningLocales |
| Fields inherited from interface MultidimensionalImageStore |
|---|
X_DIMENSION, Y_DIMENSION |
| Fields inherited from interface WarningProducer |
|---|
LOGGER |
| Constructor Summary | |
|---|---|
NetcdfImageReader(NetcdfImageReader.Spi spi)
Constructs a new NetCDF reader. |
|
| Method Summary | |
|---|---|
boolean |
canReadRaster()
Returns true since this class supports calls to
readRaster(int, ImageReadParam). |
protected void |
close()
Closes the NetCDF file. |
protected SpatialMetadata |
createMetadata(int imageIndex)
Creates a new stream or image metadata. |
protected Variable |
findVariable(String name)
Returns the variable of the given name. |
List<URI> |
getAggregatedFiles(int imageIndex)
Returns the URIs to the aggregated files, or null if none. |
DimensionSlice.API |
getAPIForDimension(Object... identifiers)
Returns the API assigned to the given dimension identifiers. |
Set<DimensionSlice.API> |
getAPIForDimensions()
Returns the set of APIs for which at least one dimension has identifiers. |
List<String> |
getBandNames(int imageIndex)
Returns the names of the bands for the given image, or null if none. |
int |
getDimension(int imageIndex)
Returns the number of dimensions in the image identified by the given index. |
DimensionIdentification |
getDimensionForAPI(DimensionSlice.API api)
Returns the dimension assigned to the given API. |
GridEnvelope |
getGridEnvelope(int imageIndex)
Returns the grid envelope in the image identified by the given index. |
int |
getHeight(int imageIndex)
Returns the image height. |
List<String> |
getImageNames()
Returns the names of the variables to be read. |
int |
getNumBands(int imageIndex)
Returns the number of bands available for the image identified by the given index. |
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. |
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. |
BufferedImage |
read(int imageIndex,
ImageReadParam param)
Creates an image from the specified parameters. |
Raster |
readRaster(int imageIndex,
ImageReadParam param)
Creates a raster from the specified parameters. |
void |
reset()
Restores the ImageReader to its initial state. |
void |
setBandNames(int imageIndex,
String... names)
Sets the names of the bands for the given image, or null for removing any naming. |
void |
setError(String message)
Invoked by the NetCDF library when an error occurred during the read operation. |
void |
setImageNames(String... names)
Sets the name of the variables to be read in a NetCDF file. |
| Methods inherited from class FileImageReader |
|---|
getInputFile, getURLEncoding, isRandomAccessEasy, isTemporaryFile |
| Methods inherited from class StreamImageReader |
|---|
finalize, getChannel, getInputStream, getStreamLength, setInput |
| Methods inherited from class SpatialImageReader |
|---|
checkBandIndex, checkImageIndex, collapseNoDataValues, dispose, getDefaultReadParam, getDestination, getImageMetadata, getImageType, getImageTypes, getRawImageType, getStreamMetadata, hasColors, warningOccurred |
| Methods inherited from class Object |
|---|
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Methods inherited from interface Localized |
|---|
getLocale |
| Field Detail |
|---|
protected Variable variable
prepareVariable(int) when first needed, and may be updated when the argument given to
any method expecting a imageIndex parameter has changed.
This field is typically (but not necessarily) an instance of VariableDS.
| Constructor Detail |
|---|
public NetcdfImageReader(NetcdfImageReader.Spi spi)
spi - The service provider.| Method Detail |
|---|
public DimensionIdentification getDimensionForAPI(DimensionSlice.API api)
imageIndex specifies the variable to read, where the variable name
is determined by getImageNames().get(imageIndex).The above-cited default can be changed by calls to this method. For example, the following method call allows usage of the otherwise unused bands API for selecting slices in the third dimension:
reader.setImageNames("temperature");
reader.getDimensionForAPI(API.BANDS).addDimensionId(2); // Zero-based indexThis NetCDF reader allows usage ofreader.setBandNames(0, "temperature"); reader.getDimensionForAPI(API.IMAGES).addDimensionId(3);
BANDS and
IMAGES API.
The COLUMNS and ROWS API can not be assigned to new
dimensions in current implementation.
getDimensionForAPI in interface MultidimensionalImageStoreapi - The API for which to return a dimension.
DimensionSet.getOrCreate(DimensionSlice.API)public DimensionSlice.API getAPIForDimension(Object... identifiers)
DimensionIdentification.addDimensionId(...) methods. Unknown identifiers are silently
ignored.
If more than one dimension is found for the given identifiers, then a
warning is emitted and
this method returns the first dimension matching the given identifiers.
If no dimension is found, API.NONE is returned.
getAPIForDimension in interface MultidimensionalImageStoreidentifiers - The identifiers of the dimension to query.
DimensionSlice.API.NONE if none.DimensionSet.getAPI(Object[])public Set<DimensionSlice.API> getAPIForDimensions()
getDimensionForAPI(...).addDimensionId(...);
getAPIForDimensions in interface MultidimensionalImageStoreDimensionSet.getAPIs()
public List<URI> getAggregatedFiles(int imageIndex)
throws IOException
null if none. This information applies
mostly to NcML files, which are XML files listing many NetCDF files to be aggregated as if
they were a single dataset. The method returns the individual files that compose such
aggregation.
getAggregatedFiles in interface AggregatedImageStoreimageIndex - The index of the variable for which to get the aggregated files.
null if none.
IOException - If an error occurred while building the list of files.NetcdfDataset.getAggregation()
public List<String> getImageNames()
throws IOException
read(imageIndex) will read the variable named
variables.get(imageIndex) where variables is the list returned by this
method.
The sequence of variables to be read can be changed by a call to
setImageNames(String[]).
getImageNames in interface NamedImageStoreIOException - if the NetCDF file can not be read.NetcdfFile.getVariables()
public void setImageNames(String... names)
throws IOException
Special cases:
variableNames is set to null, then the variables will be inferred
from the content of the NetCDF file. This is the default behavior.IMAGES API has been
assigned to a dimension, then at most one variable can be specified.
setImageNames in interface NamedImageStorenames - The set of variables to be assigned to image index,
or null for all variables declared in the NetCDF file.
IOException - if the NetCDF file can not be read.
public int getNumImages(boolean allowSearch)
throws IllegalStateException,
IOException
IMAGES API has been assigned
to a dimension, then this method returns the number of slices in that dimension.
getNumImages in class SpatialImageReaderallowSearch - If true, the number of images will be returned
even if a search is required.
allowSearch
is false and a search would be required.
IllegalStateException - if the input source has not been set.
IOException - if an error occurs reading the information from the input source.
public List<String> getBandNames(int imageIndex)
throws IOException
null if none.
By default, this method returns null for every image index. Non-null
values can be specified with calls to the setBandNames(int, String[])
method.
getBandNames in interface NamedImageStoreimageIndex - Index of the image for which to get the band names.
null
if the bands for the given image are unnamed.
IOException - if the NetCDF file can not be read.
public void setBandNames(int imageIndex,
String... names)
throws IOException
null for removing any naming.
This method is useful for merging different variables as different bands in the image to
be read, typically because each band is a vector component. See the NamedImageStore
javadoc for an example.
setBandNames in interface NamedImageStoreimageIndex - Index of the image for which to set the band names.names - The variable names of the bands for the given image,
or null for removing any naming.
IOException - if the NetCDF file can not be read.
public int getNumBands(int imageIndex)
throws IOException
getNumBands in class SpatialImageReaderimageIndex - The image index.
IOException - if an error occurs reading the information from the input source.
public int getWidth(int imageIndex)
throws IOException
getWidth in class ImageReaderIOException - If an error occurred while reading the NetCDF file.Variable.getDimension(int)
public int getHeight(int imageIndex)
throws IOException
getHeight in class ImageReaderIOException - If an error occurred while reading the NetCDF file.Variable.getDimension(int)
public GridEnvelope getGridEnvelope(int imageIndex)
throws IOException
getGridEnvelope in class SpatialImageReaderimageIndex - The image index.
IOException - if an error occurs reading the information from the input source.Variable.getDimension(int)
public int getDimension(int imageIndex)
throws IOException
getDimension in class SpatialImageReaderimageIndex - The image index.
IOException - if an error occurs reading the information from the input source.Variable.getRank()
protected SpatialMetadata createMetadata(int imageIndex)
throws IOException
createMetadata in class SpatialImageReaderimageIndex - -1 for stream metadata, or the image index for image metadata.
null if none.
IOException - If an error occurred while reading metadata.CoordSysBuilder.factory(NetcdfDataset, CancelTask)
protected int getRawDataType(int imageIndex)
throws IOException
VariableIF.getDataType() method on the variable identified by the
given index. The NetCDF DataType is then mapped to one of the
DataBuffer constants.
getRawDataType in class SpatialImageReaderimageIndex - The index of the image to be queried.
DataBuffer.TYPE_UNDEFINED if unknown.
IOException - If an error occurred while reading the NetCDF file.SpatialImageReader.getImageType(int, ImageReadParam, SampleConverter[]),
SampleConversionType.SHIFT_SIGNED_INTEGERS
protected boolean prepareVariable(int imageIndex)
throws IOException
This method is invoked automatically before any operation requiring the NetCDF variable, including (but not limited to):
imageIndex - The image index.
true if the variable changed as a result of this call,
or false if the current value is already appropriate.
IndexOutOfBoundsException - if the specified index is outside the expected range.
IllegalStateException - If ImageReader.input is not set.
IOException - If an error occurred while reading the NetCDF file.
protected Variable findVariable(String name)
throws IOException
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.
Subclasses can override this method if they want this NetcdfImageReader
to use a different variable for the given name.
name - The name of the variable to search.
IOException - If an error occurred while reading the NetCDF file.NetcdfFile.findVariable(String)
public BufferedImage read(int imageIndex,
ImageReadParam param)
throws IOException
read in class ImageReaderIOException - If an error occurred while reading the NetCDF file.
public Raster readRaster(int imageIndex,
ImageReadParam param)
throws IOException
read(int, ImageReadParam), because NetCDF file usually don't
provide color information.
readRaster in class ImageReaderIOException - If an error occurred while reading the NetCDF file.read(int, param).
Futures versions should do a more efficient work.public boolean canReadRaster()
true since this class supports calls to
readRaster(int, ImageReadParam).
canReadRaster in class ImageReaderpublic boolean isCancel()
isCancel in interface CancelTasktrue if abort has been requested.public void setError(String message)
setError in interface CancelTaskmessage - An error message to report.
protected void close()
throws IOException
close in class FileImageReaderIOException - If an error occurred while accessing the NetCDF file.StreamImageReader.closeOnResetpublic void reset()
ImageReader to its initial state. This method removes the input,
the locale, all listeners and any DimensionSlice.API.
reset in class ImageReader
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||