001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2005-2007, Geotools Project Managment Committee (PMC)
005: * (C) 2001, Institut de Recherche pour le Développement
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2.1 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: */
017: package org.geotools.coverage.io;
018:
019: // J2SE dependencies
020: import java.awt.Dimension;
021: import java.awt.image.RenderedImage;
022: import java.io.File;
023: import java.io.IOException;
024: import java.io.PrintWriter;
025: import java.io.StringWriter;
026: import java.net.URL;
027: import java.util.Arrays;
028: import java.util.Iterator;
029: import java.util.Locale;
030: import java.util.MissingResourceException;
031: import java.util.logging.Level;
032: import java.util.logging.Logger;
033: import javax.imageio.ImageIO;
034: import javax.imageio.ImageReadParam;
035: import javax.imageio.ImageReader;
036: import javax.imageio.stream.ImageInputStream;
037:
038: // OpenGIS dependencoes
039: import org.opengis.coverage.grid.GridRange;
040: import org.opengis.coverage.grid.GridCoverage;
041: import org.opengis.geometry.Envelope;
042: import org.opengis.referencing.operation.MathTransform;
043: import org.opengis.referencing.crs.CoordinateReferenceSystem;
044:
045: // Geotools dependencies
046: import org.geotools.factory.Hints;
047: import org.geotools.coverage.FactoryFinder;
048: import org.geotools.coverage.GridSampleDimension;
049: import org.geotools.coverage.grid.GeneralGridRange;
050: import org.geotools.coverage.grid.GridCoverageFactory;
051: import org.geotools.image.io.RawBinaryImageReadParam;
052: import org.geotools.referencing.operation.builder.GridToEnvelopeMapper;
053: import org.geotools.io.LineWriter;
054: import org.geotools.io.TableWriter;
055: import org.geotools.resources.i18n.Errors;
056: import org.geotools.resources.i18n.ErrorKeys;
057: import org.geotools.resources.i18n.Vocabulary;
058: import org.geotools.resources.i18n.VocabularyKeys;
059:
060: /**
061: * Interface for reading {@link GridCoverage} objects. Reading is a two steps process:
062: * The input file must be set first, then the actual reading is performed with the
063: * {@link #getGridCoverage}. Example:
064: *
065: * <blockquote><pre>
066: * GridCoverageReader reader = ...
067: * reader.{@linkplain #setInput setInput}(new File("MyCoverage.dat"), true);
068: * GridCoverage coverage = reader.{@linkplain #getGridCoverage getGridCoverage}(0);
069: * </pre></blockquote>
070: *
071: * @since 2.4
072: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/unsupported/coverageio/src/main/java/org/geotools/coverage/io/GridCoverageReader.java $
073: * @version $Id: GridCoverageReader.java 25699 2007-05-31 15:55:07Z desruisseaux $
074: * @author Martin Desruisseaux
075: */
076: public interface GridCoverageReader {
077: /**
078: * Sets the input source to the given object. The input is usually a
079: * {@link java.io.File} or an {@link java.net.URL} object. But some
080: * other types (e.g. {@link javax.imageio.stream.ImageInputStream})
081: * may be accepted as well.
082: *
083: * @param input The {@link java.io.File} or {@link java.net.URL} to be read.
084: * @param seekForwardOnly if {@code true}, grid coverages
085: * and metadata may only be read in ascending order from
086: * the input source.
087: * @throws IOException if an I/O operation failed.
088: * @throws IllegalArgumentException if input is not a valid instance.
089: */
090: void setInput(Object input, boolean seekForwardOnly)
091: throws IOException;
092:
093: /**
094: * Returns the number of images available from the current input source.
095: * Note that some image formats do not specify how many images are present
096: * in the stream. Thus determining the number of images will require the
097: * entire stream to be scanned and may require memory for buffering.
098: * The {@code allowSearch} parameter may be set to {@code false}
099: * to indicate that an exhaustive search is not desired.
100: *
101: * @param allowSearch If {@code true}, the true number of images will
102: * be returned even if a search is required. If {@code false},
103: * the reader may return -1 without performing the search.
104: * @return The number of images, or -1 if {@code allowSearch} is
105: * {@code false} and a search would be required.
106: * @throws IllegalStateException If the input source has not been set, or if
107: * the input has been specified with {@code seekForwardOnly} set to {@code true}.
108: * @throws IOException If an error occurs reading the information from the input source.
109: */
110: int getNumImages(boolean allowSearch) throws IOException;
111:
112: /**
113: * Gets the {@link GridCoverage} name at the specified index.
114: *
115: * @param index The index of the image to be queried.
116: * @return The name for the {@link GridCoverage} at the specified index.
117: * @throws IllegalStateException if the input source has not been set.
118: * @throws IndexOutOfBoundsException if the supplied index is out of bounds.
119: * @throws IOException if an error occurs reading the information from the input source.
120: */
121: String getName(int index) throws IOException;
122:
123: /**
124: * Returns the coordinate reference system for the {@link GridCoverage} to be read.
125: *
126: * @param index The index of the image to be queried.
127: * @return The coordinate reference system for the {@link GridCoverage} at the specified index.
128: * @throws IllegalStateException if the input source has not been set.
129: * @throws IndexOutOfBoundsException if the supplied index is out of bounds.
130: * @throws IOException if an error occurs reading the width information from the input source.
131: */
132: CoordinateReferenceSystem getCoordinateReferenceSystem(int index)
133: throws IOException;
134:
135: /**
136: * Returns the envelope for the {@link GridCoverage} to be read.
137: * The envelope must have the same number of dimensions than the
138: * coordinate reference system.
139: *
140: * @param index The index of the image to be queried.
141: * @return The envelope for the {@link GridCoverage} at the specified index.
142: * @throws IllegalStateException if the input source has not been set.
143: * @throws IndexOutOfBoundsException if the supplied index is out of bounds.
144: * @throws IOException if an error occurs reading the width information from the input source.
145: */
146: Envelope getEnvelope(int index) throws IOException;
147:
148: /**
149: * Returns the grid range for the {@link GridCoverage} to be read.
150: * The grid range must have the same number of dimensions than the
151: * envelope.
152: *
153: * @param index The index of the image to be queried.
154: * @return The grid range for the {@link GridCoverage} at the specified index.
155: * @throws IllegalStateException if the input source has not been set.
156: * @throws IndexOutOfBoundsException if the supplied index is out of bounds.
157: * @throws IOException if an error occurs reading the width information from the input source.
158: */
159: GridRange getGridRange(int index) throws IOException;
160:
161: /**
162: * Returns the transform from {@linkplain #getGridRange grid range} to
163: * {@linkplain #getCoordinateReferenceSystem CRS} coordinates.
164: */
165: MathTransform getMathTransform(int index) throws IOException;
166:
167: /**
168: * Returns the sample dimensions for each band of the {@link GridCoverage}
169: * to be read. If sample dimensions are not known, then this method returns
170: * {@code null}.
171: *
172: * @param index The index of the image to be queried.
173: * @return The category lists for the {@link GridCoverage} at the specified index.
174: * This array's length must be equals to the number of bands in {@link GridCoverage}.
175: * @throws IllegalStateException if the input source has not been set.
176: * @throws IndexOutOfBoundsException if the supplied index is out of bounds.
177: * @throws IOException if an error occurs reading the width information from the input source.
178: */
179: GridSampleDimension[] getSampleDimensions(int index)
180: throws IOException;
181:
182: /**
183: * Reads the grid coverage.
184: *
185: * @param index The index of the image to be queried.
186: * @return The {@link GridCoverage} at the specified index.
187: * @throws IllegalStateException if the input source has not been set.
188: * @throws IndexOutOfBoundsException if the supplied index is out of bounds.
189: * @throws IOException if an error occurs reading the width information from the input source.
190: */
191: GridCoverage getGridCoverage(int index) throws IOException;
192:
193: /**
194: * Restores the {@code GridCoverageReader} to its initial state.
195: *
196: * @throws IOException if an error occurs while disposing resources.
197: */
198: void reset() throws IOException;
199: }
|