org.geotoolkit.image.io
Interface NamedImageStore

All Known Implementing Classes:

NetcdfImageReader

public interface NamedImageStore

Interface for ImageReader and ImageWriter implementations where each image have a name. The standard Java API uses an integer for identifying the images to be read or written, using a zero-based numbering. But some file formats like NetCDF identify the images by name (in the case of NetCDF, "images" are actually "variables"). This class provides a mean to map image (or variable) names to image index for use with the ImageReader or ImageWriter API.

Common usage: names for images
If the image names can not be known a priori, then the user needs to invoke getImageNames() and inspect the returned list. But if the user know in advance the name of the images to be read, then a more efficient approach is to declare the names of the image of interest. This approach avoid the need to extract the list of all image names.

The example below declares that the image named "temperature" should be assigned to the image index 0, and the image named "salinity" to image index 1:

imageReader.setImageNames("temperature", "salinity");
BufferedImage temperature = imageReader.read(0);
BufferedImage salinity    = imageReader.read(1);

If no image exist for a given name, then an ImageNameNotFoundException will be thrown at reading time.

Alternative usage: names for bands
In some cases, it is convenient to use the variable names for band indices rather than image indices. For example when reading geostrophic current data as a vector field, where the variable named u is the East-West component of the vectors and the variable named v is the North-South component, we may want to read those two components as two bands in the same image:

imageReader.setBandNames(0, "u", "v");
BufferedImage currents = imageReader.read(0); // Two-banded image.

Named bands, if any, have precedence over named images. By default there is no named band.

Since:

3.08

Version:

3.11

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Method Summary

List<String>	getBandNames(int imageIndex) Returns the names of the bands for the given image, or null if none.
List<String>	getImageNames() Returns the names associated to all image indices.
void	setBandNames(int imageIndex, String... bandNames) Sets the names of the bands for the given image, or null for removing any naming.
void	setImageNames(String... imageNames) Sets the names to associate to all image indices.

Method Detail

getImageNames

List<String> getImageNames()
                           throws IOException

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

This method initially returns the list of all images contained in the underlying file. If the setImageNames(String[]) method has been invoked with a non-null array argument, then getImageNames() returns the names which were specified to that setImageNames method.

Returns:

The names associated to all image indices, or null if there is no such mapping.

Throws:

IOException - if the image stream can not be read.

setImageNames

void setImageNames(String... imageNames)
                   throws IOException

Sets the names to associate to all image indices. The first name is assigned to the image at index 0, the second name to the image at index 1, etc. This method does not delete or create image in the file; it merely changes the mapping between names and image indices for the purpose of using the ImageReader or ImageWriter API.

If a supplied image name does not exist in the file to be read or written, then an ImageNameNotFoundException will be thrown either at setImageNames(...) invocation time, or deferred to the first invocation of an ImageReader or ImageWriter method expecting an image index argument.

If imageNames array is set to null, then the names will be inferred from the content of the file. This is the default behavior.

Parameters:

imageNames - The set of names to be assigned to image index, or (String[]) null for the default set of names declared in the file.

Throws:

IOException - If the given names can not be assigned to this image reader or writer, or if an I/O error occurred while processing.

getBandNames

List<String> getBandNames(int imageIndex)
                          throws IOException

Returns the names of the bands for the given image, or null if none. By default, this method returns null for every image index.

Parameters:

imageIndex - Index of the image for which to get the band names.

Returns:

The variable names of the bands for the given image, or null if the bands for the given image are unnamed.

Throws:

IOException - if the image stream can not be read.

Since:

3.11

setBandNames

void setBandNames(int imageIndex,
                  String... bandNames)
                  throws IOException

Sets the names of the bands for the given image, or null for removing any naming. See the class-javadoc for a usage example.

Parameters:

imageIndex - Index of the image for which to set the band names.

bandNames - The variable names of the bands for the given image, or null for removing any naming.

Throws:

IOException - If the given names can not be assigned to this image reader or writer, or if an I/O error occurred while processing.

Since:

3.11