Module org.opengis.geoapi.conformance

Package org.opengis.test.coverage.image

Class ImageWriterTestCase

Object

TestCase

ImageIOTestCase

ImageWriterTestCase

All Implemented Interfaces:

Closeable, AutoCloseable

public abstract class ImageWriterTestCase
extends ImageIOTestCase
implements Closeable

Base class for testing ImageWriter implementations. This test writes different regions and bands of an image at different sub-sampling levels, then read back the images and compare the sample values.

To use this test, subclasses need to set the writer field to a non-null value in the prepareImageWriter(boolean) method. Example:

public class MyImageWriterTest extends ImageWriterTestCase {
    @Override
    protected void prepareImageWriter(boolean optionallySetOutput) throws IOException {
        if (writer == null) {
            writer = new MyImageWriter();
        }
    }
}

The writer shall accept at least one of the following output types, in preference order:

• ImageOutputStream - mandatory according Image I/O specification.
• File - fallback if the writer doesn't support ImageOutputStream. This fallback exists because ImageOutputStream is hard to support when the writer is implemented by a native library.

Since:

3.1

Field Summary

Fields

Modifier and Type	Field	Description
protected ImageReader	reader	The reader to use for verifying the writer output.
protected ImageWriter	writer	The image writer to test.

Fields inherited from class org.opengis.test.coverage.image.ImageIOTestCase

isSourceBandsSupported, isSubregionSupported, isSubsamplingOffsetSupported, isSubsamplingSupported, sampleToleranceThreshold

Fields inherited from class org.opengis.test.TestCase

configurationTip, units, validators

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ImageWriterTestCase()	Creates a new test case using a default random number generator.
protected	ImageWriterTestCase(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 and the writer (if non-null) after each test.
protected void	completeImageMetadata(IIOMetadata metadata, RenderedImage image)	Completes stream or image metadata to be given to the tested writer.
protected abstract void	prepareImageWriter(boolean optionallySetOutput)	Invoked when the image writer is about to be used for the first time.
void	testOneByteBand()	Tests the ImageWriter.write method for a single band of byte values.
void	testOneDoubleBand()	Same test as testOneByteBand(), but using the signed double type.
void	testOneFloatBand()	Same test as testOneByteBand(), but using the signed float type.
void	testOneIntBand()	Same test as testOneByteBand(), but using the signed int type.
void	testOneShortBand()	Same test as testOneByteBand(), but using the signed short type.
void	testOneUnsignedShortBand()	Same test as testOneByteBand(), but using the unsigned short type.
void	testThreeByteBands()	Same test as testOneByteBand(), but using RGB values in three bands.

Methods inherited from class org.opengis.test.TestCase

configuration, getEnabledFlags

Methods inherited from class java.lang.Object

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

Field Details

writer

protected ImageWriter writer

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

reader

protected ImageReader reader

The reader to use for verifying the writer output. By default, this field is null until a reader is first needed, in which case the field is assigned to a reader instance created by ImageIO.getImageReader(ImageWriter). Subclasses can set explicitly a value to this field if they need the tests to use another reader instead.

ImageWriterTestCase will use only the ImageReader.read(int) method. Consequently, this reader doesn't need to support ImageReadParam usage.

Constructor Details

ImageWriterTestCase

protected ImageWriterTestCase()

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 ImageWriterTestCase(long) constructor instead.

ImageWriterTestCase

protected ImageWriterTestCase(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 write parameters.

Method Details

prepareImageWriter

protected abstract void prepareImageWriter(boolean optionallySetOutput)
                                    throws IOException

Invoked when the image writer is about to be used for the first time. Subclasses need to create a new ImageWriter instance if needed.

If the optionallySetOutput argument is true, then subclasses can optionally set the output to a temporary file or other object suitable to the writer. This operation is optional: if no output has been explicitly set, ImageWriterTestCase will automatically set the output to an in-memory stream or to a temporary file.

Example:

@Override
protected void prepareImageWriter(boolean optionallySetOutput) throws IOException {
    if (writer == null) {
        writer = new MyImageWriter();
    }
    if (optionallySetOutput) {
        writer.setOutput(output);                  // Optional operation.
    }
}

This method may be invoked with a false argument value when the methods to be tested do not need an output, for example ImageWriter.canWriteRasters().

Parameters:

optionallySetOutput - true if this method can set the writer output (optional operation), or false if this is not yet necessary.

Throws:

IOException - if an error occurred while preparing the writer.

completeImageMetadata

protected void completeImageMetadata(IIOMetadata metadata,
 RenderedImage image)
                              throws IOException

Completes stream or image metadata to be given to the tested writer. This method is invoked after the default metadata have been created, and before they are given to the tested image writer, as below:

For stream metadata:

IIOMetadata metadata = writer.getDefaultStreamMetadata

(param); if (metadata != null) { completeImageMetadata(metadata, null); }}

For image metadata:

IIOMetadata metadata = writer.getDefaultImageMetadata(ImageTypeSpecifier.createFromRenderedImage(image), param);
if (metadata != null) {
    completeImageMetadata(metadata, image);
}

The default implementation does nothing (note: this may change in a future version). Subclasses can override this method for providing custom metadata.

Parameters:

metadata - the stream or image metadata to complete before to be given to the tested image writer.

image - the image for which to create image metadata, or null for stream metadata.

Throws:

IOException - if the implementation needs to perform an I/O operation and that operation failed.

See Also:

• ImageWriter.getDefaultStreamMetadata(ImageWriteParam)
• ImageWriter.getDefaultImageMetadata(ImageTypeSpecifier, ImageWriteParam)

testOneByteBand

@Test
public void testOneByteBand()
                     throws IOException

Tests the ImageWriter.write method for a single band of byte values. First, this method creates an single-banded image filled with random byte values. Then, this method invokes write the image 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):

• Writes the full image once (all isXXXSupported fields set to false).
• Writes various sub-regions (only isSubregionSupported may be true)
• Writes 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

Then the image is read again and the pixel values are compared with the corresponding pixel values of the original image.

Throws:

IOException - if an error occurred while writing the image or or reading it back.

testThreeByteBands

@Test
public void testThreeByteBands()
                        throws IOException

Same test as testOneByteBand(), but using RGB values in three bands.

Throws:

IOException - if an error occurred while writing the image or or reading it back.

testOneShortBand

@Test
public void testOneShortBand()
                      throws IOException

Same test as testOneByteBand(), but using the signed short type.

Throws:

IOException - if an error occurred while writing the image or or reading it back.

testOneUnsignedShortBand

@Test
public void testOneUnsignedShortBand()
                              throws IOException

Same test as testOneByteBand(), but using the unsigned short type.

Throws:

IOException - if an error occurred while writing the image or or reading it back.

testOneIntBand

@Test
public void testOneIntBand()
                    throws IOException

Same test as testOneByteBand(), but using the signed int type.

Throws:

IOException - if an error occurred while writing the image or or reading it back.

testOneFloatBand

@Test
public void testOneFloatBand()
                      throws IOException

Same test as testOneByteBand(), but using the signed float type.

Throws:

IOException - if an error occurred while writing the image or or reading it back.

testOneDoubleBand

@Test
public void testOneDoubleBand()
                       throws IOException

Same test as testOneByteBand(), but using the signed double type.

Throws:

IOException - if an error occurred while writing the image or or reading it back.

close

@AfterEach
public void close()
           throws IOException

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

• If the writer output is closeable, closes it.
• Invokes ImageWriter.reset() for clearing the output and listeners.
• Invokes ImageWriter.dispose() for performing additional resource disposal, if any.
• Sets the writer field to null for preventing accidental use.
• Performs the same steps as above for the reader, if non-null.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

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

See Also:

• ImageWriter.reset()
• ImageWriter.dispose()