org.geotoolkit.coverage.io
Class CoverageIO

Object
  Static
      CoverageIO

public final class CoverageIO
extends Static

Convenience methods for reading or writing a coverage. The method in this class creates instances of GridCoverageReader or GridCoverageWriter for performing the actual work. This is similar to the standard ImageIO class and the XImageIO class, but applied to coverages.

Readers
In the simplest case, this class just creates an ImageCoverageReader instance with the input set to the given object (typically a File or URL). However if the image is very large and is not encoded in a format that support natively tiling, it may be more efficient to create a mosaic of tiles first. The writeOrReuseMosaic(File) method is provided for this purpose.

Writers
This class delegates the actual work to the ImageCoverageWriter class.

Since:

3.18

Version:

3.20

Author:

Johann Sorel (Geomatys), Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Method Summary

static GridCoverageReader	createMosaicReader(Object input, CoordinateReferenceSystem crs) Creates a mosaic reader using the given tiles, which must exist.
static GridCoverageReader	createSimpleReader(Object input) Creates a simple reader which does not use any pyramid or mosaic tiling.
static GridCoverageWriter	createSimpleWriter(Object output) Creates a simple writer which does not perform any pyramid or mosaic tiling.
static GridCoverage	read(Object input) Convenience method reading a coverage from the given input.
static void	write(GridCoverage coverage, String formatName, Object output) Convenience method writing a coverage to the given output.
static void	write(Iterable<? extends GridCoverage> coverages, String formatName, Object output) Convenience method writing one of many coverages to the given output.
static GridCoverageReader	writeOrReuseMosaic(File input) Creates a mosaic reader using a cache of tiles at different resolutions.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

read

public static GridCoverage read(Object input)
                         throws CoverageStoreException

Convenience method reading a coverage from the given input. The input is typically a File, URL or String object, but other types (especially ImageInputStream) may be accepted as well depending on the image format. The given input can also be an ImageReader instance with its input initialized.

Parameters:

input - The input to read (typically a File).

Returns:

A coverage read from the given input.

Throws:

CoverageStoreException - If the coverage can not be read.

write

public static void write(GridCoverage coverage,
                         String formatName,
                         Object output)
                  throws CoverageStoreException

Convenience method writing a coverage to the given output. The output is typically a File or String object, but other types (especially ImageOutputStream) may be accepted as well depending on the image format. The given input can also be an ImageWriter instance with its output initialized.

Parameters:

coverage - The coverage to write.

formatName - The image format as one of the Image I/O plugin name (e.g. "png"), or null for auto-detection from the output file suffix.

output - The output where to write the image (typically a File).

Throws:

CoverageStoreException - If the coverage can not be written.

write

public static void write(Iterable<? extends GridCoverage> coverages,
                         String formatName,
                         Object output)
                  throws CoverageStoreException

Convenience method writing one of many coverages to the given output. The output is typically a File or String object, but other types (especially ImageOutputStream) may be accepted as well depending on the image format. The given input can also be an ImageWriter instance with its output initialized.

Parameters:

coverages - The coverages to write.

formatName - The image format as one of the Image I/O plugin name (e.g. "png"), or null for auto-detection from the output file suffix.

output - The output where to write the image (typically a File).

Throws:

CoverageStoreException - If the coverages can not be written.

Since:

3.20

createSimpleReader

public static GridCoverageReader createSimpleReader(Object input)
                                             throws CoverageStoreException

Creates a simple reader which does not use any pyramid or mosaic tiling. This reader is appropriate if the image is known to be small.

The input is typically a File, URL or String object, but other types (especially ImageInputStream) may be accepted as well depending on the image format. The given input can also be an ImageReader instance with its input initialized.

Parameters:

input - The input to read (typically a File).

Returns:

A coverage reader for the given input.

Throws:

CoverageStoreException - If the reader can not be created for the given file.

createSimpleWriter

public static GridCoverageWriter createSimpleWriter(Object output)
                                             throws CoverageStoreException

Creates a simple writer which does not perform any pyramid or mosaic tiling. This writer is appropriate if the image is known to be small.

The output is typically a File, URL or String object, but other types (especially ImageOutputStream) may be accepted as well depending on the image format. The given output can also be an ImageWriter instance with its output initialized.

Parameters:

output - The output where to write (typically a File).

Returns:

A coverage writer for the given output.

Throws:

CoverageStoreException - If the writer can not be created for the given file.

Since:

3.20

createMosaicReader

public static GridCoverageReader createMosaicReader(Object input,
                                                    CoordinateReferenceSystem crs)
                                             throws CoverageStoreException

Creates a mosaic reader using the given tiles, which must exist. The input argument can be an instance of TileManager, a File to a serialized instance of TileManager, a directory, or an array or collection of Tile instances.

The crs argument is optional if the input is a File, in which case this method will attempt to parse a file of the same name with the ".prj" extension using PrjFiles. For all other cases, the CRS argument is mandatory.

Parameters:

input - The file, tiles or tile manager to use a input.

crs - The coordinate reference system of the mosaic image.

Returns:

A mosaic reader for the given tiles and CRS.

Throws:

CoverageStoreException - If the reader can not be created for the given tiles.

writeOrReuseMosaic

public static GridCoverageReader writeOrReuseMosaic(File input)
                                             throws CoverageStoreException

Creates a mosaic reader using a cache of tiles at different resolutions. Tiles will be created the first time this method is invoked for a given input. The tiles creation time depends on the available memory, the image size and its format. The creation time can range from a few seconds to several minutes or even hours if the given image is very large.

The tiles will be created in a sub-directory having the same name than the given input, with an additional ".tiles" extension.

Parameters:

input - The input to read.

Returns:

A coverage reader for the given file.

Throws:

CoverageStoreException - If the reader can not be created for the given file.