Package org.opengis.test.coverage.image

Class ImageReaderTestCase

Object

TestCase

ImageIOTestCase

ImageReaderTestCase

All Implemented Interfaces:

Closeable, AutoCloseable

public abstract class ImageReaderTestCase
extends ImageIOTestCase
implements Closeable

Base class for testing ImageReader implementations. This test reads different regions and bands of an image at different sub-sampling levels, and compares the results with the complete image. If the image reader can also provide GeoAPI metadata objects, then this class will verify the consistency of some basic attributes. For example it will verify that the grid envelope (if any) is consistent with the image width and height.

To use this test, subclasses need to set the reader field to a non-null value in the prepareImageReader(boolean) method. The reader input shall be set by the subclass when requested by the caller. Example:

public class MyImageReaderTest extends ImageReaderTestCase {
    @Override
    protected void prepareImageReader(boolean setInput) throws IOException {
        if (reader == null) {
            reader = new MyImageReader();
        }
        if (setInput) {
            reader.setInput(ImageIO.createImageInputStream(new File("MyTestImage")));
        }
    }
}

Subclasses inherit the following tests:

Inherited method	Tested method
testStreamMetadata()	ImageReader.getStreamMetadata()
testImageMetadata()	ImageReader.getImageMetadata(int)
testReadAsBufferedImage()	ImageReader.read(int, ImageReadParam)
testReadAsRenderedImage()	ImageReader.readAsRenderedImage(int, ImageReadParam)
testReadAsRaster()	ImageReader.readRaster(int, ImageReadParam)

In addition, subclasses may consider to override the following methods:

• getMetadata(Class, IIOMetadata) - to extract metadata objects from specific nodes.
• close() - to modify the policy of reader disposal.

Since:

3.1

Field Summary

Fields

Modifier and Type	Field	Description
protected ImageReader	reader	The image reader to test.

Fields inherited from class ImageIOTestCase

isSourceBandsSupported, isSubregionSupported, isSubsamplingOffsetSupported, isSubsamplingSupported, sampleToleranceThreshold

Fields inherited from class TestCase

configurationTip, listener, units, validators

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ImageReaderTestCase()	Creates a new test case using a default random number generator.
protected	ImageReaderTestCase(long seed)	Creates a new test case using a random number generator initialized to the given seed.

Method Summary

Modifier and Type	Method	Description
void	close()	Disposes the reader (if non-null) after each test.
protected <T> T	getMetadata(Class<T> type, IIOMetadata metadata)	Returns the user object of the given type found in the given Image I/O metadata, or null if none.
protected abstract void	prepareImageReader(boolean setInput)	Invoked when the image reader is about to be used for the first time, or when its input needs to be reinitialized.
void	testImageMetadata()	Tests ImageReader.getImageMetadata(int).
void	testReadAsBufferedImage()	Tests the ImageReader.read method.
void	testReadAsRaster()	Tests the ImageReader.readRaster method.
void	testReadAsRenderedImage()	Tests the ImageReader.readAsRenderedImage method.
void	testStreamMetadata()	Tests ImageReader.getStreamMetadata().

Methods inherited from class TestCase

configuration, factories, factories, getEnabledFlags

Methods inherited from class Object

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

Field Detail

reader

protected ImageReader reader

The image reader to test. This field must be set by subclasses in the prepareImageReader(boolean) method.

Constructor Detail

ImageReaderTestCase

protected ImageReaderTestCase()

Creates a new test case using a default random number generator. The sub-regions, sub-samplings and source bands will be different for every test execution. If reproducible subsetting sequences are needed, use the ImageReaderTestCase(long) constructor instead.

ImageReaderTestCase

protected ImageReaderTestCase(long seed)

Creates a new test case using a random number generator initialized to the given seed.

Parameters:

seed - the initial seed for the random numbers generator. Use a constant value if the tests need to be reproduced with the same sequence of image read parameters.

Method Detail

prepareImageReader

protected abstract void prepareImageReader(boolean setInput)
                                    throws IOException

Invoked when the image reader is about to be used for the first time, or when its input needs to be reinitialized. Subclasses need to create a new ImageReader instance if needed and set its input in this method.

This method may be invoked more than once during the same test if the input became invalid. This may occur because the tests will read the same image many time in different ways, and not all input streams can seek back to the beginning of the image stream. In such case, ImageReaderTestCase will close the input and invoke this method in order to get a fresh ImageInputStream.

Example:

@Override
protected void prepareImageReader(boolean setInput) throws IOException {
    if (reader == null) {
        reader = new MyImageReader();
    }
    if (setInput) {
        reader.setInput(ImageIO.createImageInputStream(new File("MyTestImage")));
    }
}

This method may be invoked with a false argument value when the methods to be tested don't need an input, for example ImageReader.canReadRaster().

Parameters:

setInput - true if this method shall set the reader input, or false if this is not yet necessary.

Throws:

IOException - if an error occurred while preparing the reader.

getMetadata

protected <T> T getMetadata(Class<T> type,
                            IIOMetadata metadata)
                     throws IOException

Returns the user object of the given type found in the given Image I/O metadata, or null if none. The default implementation gets the tree of nodes for all metadata formats except the standard format, then iterates down the tree in search for a user object of the given type. If an ambiguity is found, this method conservatively returns true.

Implementors are encouraged to override this method if they can look for metadata in a more accurate way.

See testStreamMetadata() and testImageMetadata() for a list of types requested by the default ImageReaderTestCase implementation.

Type Parameters:

T - the compile-time type of the object to search.

Parameters:

type - the type of the object to search.

metadata - the metadata where to search for the object.

Returns:

the user object of the given type, or null if not found.

Throws:

IOException - if this method requires an I/O operation and that operation failed.

testStreamMetadata

public void testStreamMetadata()
                        throws IOException

Tests ImageReader.getStreamMetadata(). The default implementation invokes getMetadata(Metadata.class, stream metadata), then validates the following properties:

• Metadata.getIdentificationInfo()
  • Identification.getCitation()
  • Identification.getExtents()

Throws:

IOException - if an error occurred while reading the metadata.

testImageMetadata

public void testImageMetadata()
                       throws IOException

Tests ImageReader.getImageMetadata(int). The default implementation invokes getMetadata(Class, IIOMetadata) for the types listed below, then validates their properties:

• Metadata.getIdentificationInfo(): see testStreamMetadata()
• Extent: Validate the spatial extent, if any.
• Grid.getExtent()
  • GridEnvelope: Verify that the span in at least one dimension is equals to the image width, and a span in another dimension is equals to the image height.

Throws:

IOException - if an error occurred while reading the metadata.

testReadAsBufferedImage

public void testReadAsBufferedImage()
                             throws IOException

Tests the ImageReader.read method. First, this method reads the full image with a call to ImageReader.read(int). Then, this method invokes ImageReader.read(int, ImageReadParam) an arbitrary amount of time for the following configurations (note: any isXXXSupported field which was set to false prior the execution of this test will stay false):

• Reads the full image once (all isXXXSupported fields set to false).
• Reads various sub-regions (only isSubregionSupported may be true)
• Reads at various sub-sampling (only isSubsamplingSupported may be true)
• Reads various bands (only isSourceBandsSupported may be true)
• A mix of sub-regions, sub-sampling and source bands

The pixel values for each image resulting from the above read operations are compared with the corresponding pixel values of the complete image.

Note: in the spirit of JUnit, this test should have been splitted in smaller test cases: one for sub-regions, one for sub-samplings, etc. However in this particular case, consolidation of those tests in a single method provides the following benefits:

• The potentially large complete image is read only once.
• If the tests for subregions or subsamplings fails, avoid the test mixing both.
• Less methods to override if the implementor want to provide his own test.

Throws:

IOException - if an error occurred while reading the image.

testReadAsRenderedImage

public void testReadAsRenderedImage()
                             throws IOException

Tests the ImageReader.readAsRenderedImage method. This method performs the same test than testReadAsBufferedImage(), except that the ImageReader.readAsRenderedImage(int, ImageReadParam) method is invoked instead than ImageReader.read(int, ImageReadParam).

Throws:

IOException - if an error occurred while reading the image.

testReadAsRaster

public void testReadAsRaster()
                      throws IOException

Tests the ImageReader.readRaster method. This method performs the same test than testReadAsBufferedImage(), except that the ImageReader.readRaster(int, ImageReadParam) method is invoked instead than ImageReader.read(int, ImageReadParam).

This test is ignored if ImageReader.canReadRaster() returns false.

Throws:

IOException - if an error occurred while reading the raster.

close

public void close()
           throws IOException

Disposes the reader (if non-null) after each test. The default implementation performs the following cleanup:

• If the reader input is closeable, closes it.
• Invokes ImageReader.reset() for clearing the input and listeners.
• Invokes ImageReader.dispose() for performing additional resource disposal, if any.
• Sets the reader field to null for preventing accidental use.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if an error occurred while closing the input stream.

See Also:

ImageReader.reset(), ImageReader.dispose()