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.
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.
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:

Alternatively, the variables can be assigned to bands instead than images. This is useful
when two related variables - for example the East-West (U) and North-South
(V) components of wind speed - shall be stored in the same image:

imageReader.setBandNames(0, "WindSpeed-U", "WindSpeed-V");
BufferedImage windSpeed = imageReader.read(0);
// windSpeed is now an image with two bands.

For any dimension greater than 2, the region to read can be specified in two different ways:

The slice to read can be specified by DimensionSlice objects, which are
associated to the SpatialImageReadParam object controlling the reading
process. This approach is similar to the WCS 2.0 specification.

The slice to read can be specified as bands or as image index, using the methods
defined in the MultidimensionalImageStore interface. This approach allows
compatibility with library working only with the Java Image I/O API.

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.
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.

Field Detail

variable

protected Variable variable

The data from the NetCDF file for a given image index. The value for this field is set by
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.

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.

getAggregatedFiles

Returns the URIs to the aggregated files, or 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.

getImageNames

Returns the names of the variables to be read. The first name is assigned to the image
at index 0, the second name to the image at index 1, etc. In other words a call
to read(imageIndex) will read the variable named
variables.get(imageIndex) where variables is the list returned by this
method.

getNumImages

Returns the number of images available from the current input source. By default, this
method returns the number of variables since each variable
is considered as an image. However if the
IMAGES API has been assigned
to a dimension, then this method returns the number of slices in that dimension.

getBandNames

Returns the names of the bands for the given image, or 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.

setBandNames

Sets the names of the bands for the given image, or 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.

getRawDataType

Returns the data type which most closely represents the "raw" internal data of the image.
In the case of NetCDF files, The raw type is determined from the value returned by the
VariableIF.getDataType() method on the variable identified by the
given index. The NetCDF DataType is then mapped to one of the
DataBuffer constants.

findVariable

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.

Subclasses can override this method if they want this NetcdfImageReader
to use a different variable for the given name.