Application: gvSIG desktop » gvSIG raster

/* gvSIG. Geographic Information System of the Valencian Government

 *

 * Copyright (C) 2007-2008 Infrastructures and Transports Department

 * of the Valencian Government (CIT)

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

 * MA  02110-1301, USA.

 *

 */

package org.gvsig.raster.impl.provider;

import java.awt.Image;

import java.awt.geom.AffineTransform;

import java.awt.geom.Point2D;

import org.cresques.cts.IProjection;

import org.gvsig.compat.net.ICancellable;

import org.gvsig.fmap.dal.coverage.dataset.Buffer;

import org.gvsig.fmap.dal.coverage.datastruct.Extent;

import org.gvsig.fmap.dal.coverage.datastruct.NoData;

import org.gvsig.fmap.dal.coverage.exception.BandAccessException;

import org.gvsig.fmap.dal.coverage.exception.CloneException;

import org.gvsig.fmap.dal.coverage.exception.FileNotOpenException;

import org.gvsig.fmap.dal.coverage.exception.InfoByPointException;

import org.gvsig.fmap.dal.coverage.exception.InvalidSetViewException;

import org.gvsig.fmap.dal.coverage.exception.InvalidSourceException;

import org.gvsig.fmap.dal.coverage.exception.ProcessInterruptedException;

import org.gvsig.fmap.dal.coverage.exception.RasterDriverException;

import org.gvsig.fmap.dal.coverage.exception.RemoteServiceException;

import org.gvsig.fmap.dal.coverage.exception.RmfSerializerException;

import org.gvsig.fmap.dal.coverage.store.RasterQuery;

import org.gvsig.fmap.dal.coverage.store.parameter.RasterDataParameters;

import org.gvsig.fmap.dal.coverage.store.props.ColorInterpretation;

import org.gvsig.fmap.dal.coverage.store.props.ColorTable;

import org.gvsig.fmap.dal.coverage.store.props.Histogramable;

import org.gvsig.fmap.dal.coverage.store.props.Metadata;

import org.gvsig.fmap.dal.coverage.store.props.Statistics;

import org.gvsig.fmap.dal.coverage.store.props.TimeSeries;

import org.gvsig.fmap.dal.coverage.store.props.Transparency;

import org.gvsig.fmap.dal.raster.spi.CoverageStoreProvider;

import org.gvsig.raster.cache.tile.provider.TileServer;

/**

 * Interfaz que deben implementar cualquier fuente de datos raster. Estas pueden estar

 * compuestas por N datasets. B?sicamente hay dos fuentes que deben implementar este interfaz, 

 * MultiRasterDataset y CompositeDataset. La primera es un dataset compuesto por varios ficheros

 * con el mismo Extent de N bandas cada uno. MultiRasterDataset proporciona una encapsulaci?n al acceso

 * a datos de todos ellos. CompositeDataset es un dataset compuesto de N MultiRasterDatasets cuya extensi?n

 * es continua formando un Grid de datasets con continuidad espacial. IRasterDataSource proporciona

 * una visi?n de acceso a datos com?n para ambos.

 * 

 * @author Nacho Brodin (nachobrodin@gmail.com)

 *

 */

public interface RasterProvider extends CoverageStoreProvider, Histogramable {

        /**

         * Gets a list of sizes. If the provider doesn't have files it will return null.

         * If the provider has one file it will return an array of one element with the

         * size of this file. If the provider contains others with one file each one.

         * @return

         */

        public long[] getFileSizeByProvider();

        /**

         * Gets a list of file names or URI. Each element of this array is the name of a 

         * provider 

         * @return

         */

        public String[] getURIByProvider();

        /**

         * Gets the URI of the first provider.

         * @return String 

         *         File name or URI

         */

        public String getURIOfFirstProvider();

        /**

         * Gets the number of bands by provider. 

         * @return

         */

        public int[] getBandCountByProvider();

        /**

         * Selecting a number of band this function returns the number of band

         * inside the file. If this provider has only one file the result

         * will be band parameter.

         * @param band

         * @return

         */

        public int getBandPositionByProvider(int band);

        /**

         * Returns the number of internal providers that it has

         * @return

         */

        public int getInternalProviderCount();

        /**

         * Gets the internal provider of the i position

         * @param i

         * @return

         */

        public RasterProvider getInternalProvider(int i);

        /**

         * Gets the URI of the source. If the provider has only one band

         * the result will be the URI. If it is multifile will have to choose

         * among several sources.

         * @param band

         * @return

         */

        public String getURIByBand(int band);

        /**

         * Gets the uniform resource identifier

         * @return

         */

        public String getURI();

        /**

         * Gets the number of subdatasets

         * @return

         */

        public int getSubdatasetCount();

        /**

         * Adds a new file. The behavior of this function depends on 

         * the kind of provider and its implementation.

         * @param file

         * @throws InvalidSourceException 

         */

        public void addFile(String file) throws InvalidSourceException;

        /**

         * Removes a file. The behavior of this function depends on 

         * the kind of provider and its implementation.

         * @param file

         */

        public void removeFile(String file);

        /**

         * Obtiene el n?mero de bandas del raster

         * @return N?mero de bandas

         */

        public int getBandCount();

        /**

         * Obtiene el tipo de dato por banda

         * @return tipo de dato por banda

         */

        public int[] getDataType();

        /**

         * Obtiene la altura del raster en p?xeles.

         * @return altura

         */

        public double getHeight();

        /**

         * Obtiene la anchura del raster en p?xeles.

         * @return anchura

         */

        public double getWidth();

        /**

         * Devuelve si el Dataset es reproyectable

         * @return

         */

        public boolean isReproyectable();

        /**

         * Returns true if this raster has rotation and false if don't

         */

        public boolean isRotated();

        /**

         * Returns true if this provider is open and false if don't

         * @return

         */

        public boolean isOpen();

        /**

         * Returns true if this provider supports time.

         * @return

         */

        public boolean isTimeSupported();

        /**

         * Returns true if the provider support tiles

         * @return

         */

        public boolean isTiled();

        /**

         * Informa de si el dataset soporta overviews o no.

         * @return true si soporta overviews y false si no las soporta.

         */

        public boolean isOverviewsSupported();

        /**

         * Obtiene el n?mero de overviews de una banda

         * @return

         */

        public int getOverviewCount(int band) throws BandAccessException, RasterDriverException;

        /**

         * Obtiene el ancho de una overview de una banda

         * @return

         */

        public int getOverviewWidth(int band, int overview) throws BandAccessException, RasterDriverException;

        /**

         * Obtiene el alto de una overview de una banda

         * @return

         */

        public int getOverviewHeight(int band, int overview) throws BandAccessException, RasterDriverException;

        /**

         * Informa de si el punto en coordenadas del mundo real pasado por par?metro cae dentro del

         * raster o fuera. Para este calculo cogeremos el punto a averiguar si est? dentro del raster

         * y le aplicaremos la transformaci?n inversa de la transformaci?n af?n aplicada. Una vez hecho

         * esto ya se puede comprobar si est? dentro de los l?mites del extent del raster.

         * @param p Punto a comprobar en coordenadas reales

         * @return true si el punto est? dentro y false si est? fuera.

         */

        public boolean isInside(Point2D p);

        /**

         * Gets the nodata value.

         * @return

         */

        public NoData getNoDataValue();

        /**

         * Gets statistics of this provider

         * @return MultiFileStatistics

         */

        public Statistics getStatistics();

        /**

         * Sets the statistics of this provider. Be careful using this method. 

         * Statistics shouldn't be assigned unless you had cloned this provider. 

         */

        public void setStatistics(Statistics stats);

        /**

         * Obtiene el extent del raster.

         * @return Extent

         */

        public Extent getExtent();

        /**

         * Gets the suffix of the source file 

         * @return

         */

        public String getFileSuffix();

        /**

         * Este es el extent sobre el que se ajusta una petici?n para que esta no

         * exceda el extent m?ximo del raster. Para un raster sin rotar ser? igual al

         * extent pero para un raster rotado ser? igual al extent del raster como si

         * no tuviera rotaci?n. Esto ha de ser as? ya que la rotaci?n solo se hace

         * sobre la vista y las peticiones han de hacerse en coordenadas de la imagen

         * sin shearing aplicado.

         * @return Extent

         */

        public Extent getExtentWithoutRot();

        /**

         * Obtiene la matriz de transformaci?n del propio raster. Esta matriz es la

         * encargada de convertir las coordenadas de la petici?n en coordenadas a las

         * que se pide a la libreria. En gdal, por ejemplo, se piden las coordenadas a

         * la libreria en coordenadas pixel por lo que esta matriz tendr? la

         * georreferenciaci?n asociada en el worldfile o cabecera. Otras librerias

         * como ermapper la petici?n a la libreria se hace en coordenadas geograficas

         * que son las mismas en las que pide el usuario de gvSIG por lo que esta

         * matriz en este caso se inicializa con la identidad.

         * @return

         */

        public AffineTransform getOwnAffineTransform();

        /**

         * Obtiene la transformaci?n afin aplicada en las peticiones con coordenadas

         * reales. Esta corresponde al producto matricial entre la transformaci?n de

         * la propia georreferenciaci?n del raster (ownTransformation) y la

         * transformaci?n que se le aplique de forma externa. Si esta ?ltima no existe

         * ser? la matriz identidad.

         * @return Matriz de la transformaci?n af?n.

         */

        public AffineTransform getAffineTransform();

        /**

         * Obtiene la proyecci?n del dataset

         * @return IProjection

         */

        public IProjection getProjection();

        /**

         * Obtiene el extent asignado

         * @return        Extent

         */

        public Extent getView();

        /**

         * Gets a DatasetMetadata object

         * @return

         */

        public Metadata getMetadata();

        /**

         * Gets the object with the color interpretation by band

         * @return ColorInterpretation

         */

        public ColorInterpretation getColorInterpretation();

        /**

         * Assigns the object with the color interpretation by band

         * @param ci

         */

        public void setColorInterpretation(ColorInterpretation ci);

        /**

         * Define el objeto paleta. Si se define null quiere decir que no tiene paleta

         * para su visualizaci?n.

         * @param value

         */

        public void setColorTable(ColorTable value);

        /**

         * Gets the {@link ColorTable} or null if the raster

         * does not have

         * @return

         */

        public ColorTable getColorTable();

        /**

         * Gets the legend as a image. The store could not have implemented this method .

         * This is useful above all for WMS but whatever raster layer 

         * could return a legend as image.

         * @return

         */

        public Image getImageLegend();

        /**

         * Obtiene el estado de transparencia a partir de los estados de transparencia de todos

         * los ficheros que lo componen. Si varios de los ficheros que lo componen tienen banda de 

         * transparencia estas tendr?n que ser mezcladas sobre una banda de transparencia ?nica.

         * @return Objeto FileTransparency con el estado de transparencia

         */

        public Transparency getTransparency();

        /**

         * Cierra los raster asociados.

         */

        public void close();

        /**

         * Convierte un punto desde coordenadas pixel a coordenadas del mundo.

         * @param pt Punto a transformar

         * @return punto transformado en coordenadas del mundo

         */

        public Point2D rasterToWorld(Point2D pt);

        /**

         * Convierte un punto desde del mundo a coordenadas pixel.

         * @param pt Punto a transformar

         * @return punto transformado en coordenadas pixel

         */

        public Point2D worldToRaster(Point2D pt);

        /**

         * Asigna una transformaci?n al raster para que se tenga en cuenta en la

         * asignaci?n del setView. Esta asignaci?n recalcula el extent, el

         * requestExtent y asigna el AffineTransform que se usar? para la

         * transformaci?n. Esta transformaci?n ser? considerada como si la imagen

         * tuviera asociado un rmf.

         * @param t Transformaci?n af?n a aplicar

         */

        public void setAffineTransform(AffineTransform t);

        /**

         * Gets the pixel size

         * @return

         */

        public double getCellSize();

        /**

         * Obtiene el tama?o de pixel en X

         * @return tama?o de pixel en X

         */

        public double getPixelSizeX();

        /**

         * Obtiene el tama?o de pixel en Y

         * @return tama?o de pixel en Y

         */

        public double getPixelSizeY();

        /**

         * Obtiene el valor del raster en la coordenada que se le pasa.

         * El valor ser? Double, Int, Byte, etc. dependiendo del tipo de

         * raster.

         * @param x        coordenada X

         * @param y coordenada Y

         * @return

         */

        public Object getData(int x, int y, int band)throws InvalidSetViewException, FileNotOpenException, RasterDriverException;

        /**

         * Obtiene la proyecci?n asociada al raster. Como todos los dataset del 

         * multiDataset deben tener la misma proyecci?n obtenemos esta del primer

         * dataset.

         * @return Proyecci?n en formato cadena

         * @throws RasterDriverException

         */

        public String getWktProjection() throws RasterDriverException;

        /**

         * Dado unas coordenadas reales, un tama?o de buffer y un tama?o de raster. 

         * Si el buffer es de mayor tama?o que el raster (supersampleo) quiere decir que 

         * por cada pixel de buffer se repiten varios del raster. Esta funci?n calcula el 

         * n?mero de pixels de desplazamiento en X e Y que corresponden al primer pixel del

         * buffer en la esquina superior izquierda. Esto es necesario porque la coordenada

         * solicitada es real y puede no caer sobre un pixel completo. Este calculo es

         * util cuando un cliente quiere supersamplear sobre un buffer y que no se lo haga

         * el driver autom?ticamente.

         * @param dWorldTLX Coordenada real X superior izquierda

         * @param dWorldTLY Coordenada real Y superior izquierda

         * @param nWidth Ancho del raster

         * @param nHeight Alto del raster

         * @param bufWidth Ancho del buffer

         * @param bufHeight Alto del buffer

         * @return Array de cuatro. Los dos primeros elementos son el desplazamiento en X e Y y los dos segundos

         * el tama?o en pixels de buffer de un pixel de la imagen en ancho y alto.  

         */

        public double[] calcSteps(double dWorldTLX, double dWorldTLY, double dWorldBRX, double dWorldBRY,

                        double nWidth, double nHeight, int bufWidth, int bufHeight);

        /**

         * Sets the nodata value

         * @return

         */

        public void setNoDataValue(NoData value);

        /**

         * Obtiene el flag que dice si el raster est? o no georreferenciado

         * @return true si est? georreferenciado y false si no lo est?.

         */

        public boolean isGeoreferenced();

        /**

         * Returns true if the provider has several files and all of them has the same extension

         * @return

         */

        public boolean isMultiFile();

        /**

         * Returns true if the source of data is a mosaic of images

         * @return

         */

        public boolean isMosaic();

        /**

         * Deletes the cache of this layer composed by the files in the provider list

         */

        public void deleteLayerFromCache();

        /**

         * Clone this RasterProvider

         * @return

         */

        public RasterProvider cloneProvider() throws CloneException;

        /**

         * Returs the DataParameters

         * @return

         */

        public RasterDataParameters getDataParameters();

        /**

         * Lee un bloque completo de datos del raster y devuelve un array tridimensional del tipo correcto. Esta funci?n es util

         * para una lectura rapida de todo el fichero sin necesidad de asignar vista.

         * @param pos Posici?n donde se empieza  a leer

         * @param blockHeight Altura m?xima del bloque leido

         * @return Object que es un array tridimendional del tipo de datos del raster. (Bandas X Filas X Columnas)

         * @throws InvalidSetViewException

         * @throws FileNotOpenException

         * @throws RasterDriverException

         */

        public Object readBlock(int pos, int blockHeight, double scale)

                throws InvalidSetViewException, FileNotOpenException, RasterDriverException, ProcessInterruptedException;

        /**

         * Carga un objecto desde un serializador usando el tipo del mismo objeto pasado por parametro.

         * Usa value para iniciar dicho serializador

         * @param class1

         * @param value

         * @return

         * @throws RmfSerializerException

         */

        @SuppressWarnings("unchecked")

        public Object loadObjectFromRmf(Class class1, Object value) throws RmfSerializerException;

        /**

         * Guarda en el RMF el objecto actual en caso de que exista un serializador para el.

         * El tipo del objeto se especifica en el parametro class1.

         * Esto nos puede permitir poder poner a null un valor y encontrar su serializador.

         * @param class1

         * @param value

         * @throws RmfSerializerException 

         */

        @SuppressWarnings("unchecked")

        public void saveObjectToRmf(Class class1, Object value) throws RmfSerializerException;

        /**

         * Sets the status information using other provider of the same type. The first action

         * of this method should be to check the type of the parameter.

         * @param provider

         */

        public void setStatus(RasterProvider provider);

        /**

         * Gets the information in a real point

         * @param x

         * @param y

         * @return

         * @throws RemoteServiceException 

         */

        public String getInfoByPoint(double x, double y, ICancellable cancellable) throws InfoByPointException;

        /**

         * Gets the information in a pixel point. Some services need additional 

         * information as the window where the request is done 

         * @param x

         *        X Pixel position

         * @param y

         *        Y pixel position

         * @param bbox

         *        Bounding box of the window

         * @param w

         *        Width in pixels of the window

         * @param h

         *        Height in pixels of the window

         * @param cancellable

         * @return

         * @throws RemoteServiceException

         */

        public String getInfoByPoint(int x, int y, Extent bbox, int w, int h, ICancellable cancellable) throws InfoByPointException;

        /**

         * Gets the tile cache data server

         * @return

         */

        public TileServer getTileServer();

        /**

         * Some sevices has neither limits nor pixel size. For instance, WebMapService 

         * is a service of this type if the size is not fixed. Other services, like

         * WMTS are enclosed too but in this case it will have resolution by level.

         * This method returns true if the data source is enclosed.

         * @return

         */

        public boolean isRasterEnclosed();

        /**

         * Gets the rmf file path. This method will have to be redefined by providers

         * with a different path

         * @return

         */

        public String getRMFFile();

        /**

         * Selects the subdataset.

         */

        public void selectSubdataset();

        /**

         * Gets the list of supported formats

         * @return

         */

        public String[] getFormatList();

        /**

         * Returns the source type (FILE, POSTGIS, REMOTE,...)

         * @return

         */

        public int getSourceType();

        /**

         * This function returns true if the image to be loaded needs a enhanced filter or

         * doesn't. It depends on the format, number of bands, type of data and so on.

         * @return The default value is false but each driver can change this value.

         */

        public boolean needEnhanced();

        /**

         * Gets the time serial information

         * @return

         * @throws RmfSerializerException 

         */

        public TimeSeries getTimeSerials() throws RmfSerializerException;

        /**

         * Sets the time serial information

         * @throws RmfSerializerException 

         */

        public void setTimeSerials(TimeSeries serialInfo) throws RmfSerializerException;

        /**

         * Gets the set of data selected in the {@link RasterQuery}

         * @param q

         * @return

         * @throws RasterDriverException 

         * @throws ProcessInterruptedException 

         */

        public Buffer getDataSet(RasterQuery query) throws ProcessInterruptedException, RasterDriverException;

}