| gvSIG desktop 1

/* gvSIG. Sistema de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2007 IVER T.I. and Generalitat Valenciana.

 *

 * 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., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 */

package org.gvsig.raster.dataset;

import java.awt.geom.AffineTransform;

import java.awt.geom.Point2D;

import java.io.IOException;

import org.gvsig.raster.dataset.properties.DatasetColorInterpretation;

import org.gvsig.raster.dataset.properties.DatasetListStatistics;

import org.gvsig.raster.datastruct.ColorTable;

import org.gvsig.raster.datastruct.Extent;

import org.gvsig.raster.datastruct.Transparency;

import org.gvsig.raster.hierarchy.IHistogramable;

/**

 * 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.

 * 

 * @version 27/08/2007

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

 *

 */

public interface IRasterDataSource extends IHistogramable{

        /**

         * Obtiene el tipo de dato por banda

         * @return tipo de dato por banda

         */

        public int[] getDataType();

        /**

         * Obtiene la paleta correspondiente al nombre del fichero pasado por par?metro. 

         * @param fileName Nombre del fichero

         * @return Paleta o null si no la tiene

         */

        public ColorTable getColorTable(String fileName);

        /**

         * Obtiene el n?mero de bandas del raster

         * @return N?mero de bandas

         */

        public int getBandCount();

        /**

         * Obtiene la lista de bandas.

         * @return BandList

         */

        public BandList getBands();

        /**

         * Obtiene el n?mero de datasets con el extent completo del IRasterDataSource. El valor 

         * devuelto por esta llamada coincidir?a con el valor devuelto por getDatasetCount() de un

         * MultiRasterDataset que lo compone.

         * @return integer.

         */

        public int getDatasetCount();

        /**

         * Obtiene el extent de la ?ltima selecci?n hecha con alguna de las llamadas

         * setAreaOfInterest. Este extent es devuelto en coordenadas reales con las transformaciones

         * que se hayan aplicado sobre el/los dataset.

         * @return Extent Coordenadas reales que representan el ?ltimo ?rea de datos

         * solicitada.

         */

        public Extent getLastSelectedView();

        /**

         * Obtiene el dataset de la posici?n i. En un CompositeDataset devolver? la lista de 

         * todos los datasets en esa posici?n 

         * @param i Posici?n del dataset a obtener.

         * @return GeoRasterFileDataset.

         */

        public RasterDataset[] getDataset(int i);

        /**

         * Obtiene fichero de nombre fileName.

         * @param i Posici?n del dataset a obtener.

         * @return GeoRasterFile.

         */

        public RasterDataset getDataset(String fileName);

        /**

         * Elimina un fichero a la lista a partir de su nombre

         * @param fileName        Nombre del fichero a eliminar.

         */

        public void removeDataset(String fileName);

        /**

         * Elimina un fichero a la lista

         * @param file Fichero a eliminar

         */

        public void removeDataset(RasterDataset file);

        /**

         * A?ade un fichero a la lista de datasets a partir de su nombre. Si se trata de un multiRasterDataset

         * solo se necesita un fichero pero si es un CompositeDataset necesitaremos una lista de ellos. Tantos

         * como tenga el CompositeDataset 

         * @param f fichero a a?adir.

         * @throws RasterDriverException 

         */

        public void addDataset(RasterDataset[] f)throws FileNotFoundInListException;

        /**

         * A?ade un fichero a la lista de datasets a partir de su nombre. Si se trata de un multiRasterDataset

         * solo se necesita un fichero pero si es un CompositeDataset necesitaremos una lista de ellos. Tantos

         * como tenga el CompositeDataset 

         * @param f fichero a a?adir.

         * @throws RasterDriverException 

         */

        public void addDataset(String[] fileName)throws FileNotFoundInListException, NotSupportedExtensionException, RasterDriverException;

        /**

         * Obtiene la altura del raster.

         * @return altura

         */

        public double[] getHeight();

        /**

         * Obtiene la anchura del raster.

         * @return anchura

         */

        public double[] getWidth();

        /**

         * Cierra los raster asociados.

         */

        public void close();

        /**

         * Obtiene una ventana de datos de la imagen a partir de coordenadas reales. 

         * No aplica supersampleo ni subsampleo sino que devuelve una matriz de igual tama?o a los

         * pixeles de disco. 

         * @param x Posici?n X superior izquierda

         * @param y Posici?n Y superior izquierda

         * @param w Ancho en coordenadas reales

         * @param h Alto en coordenadas reales

         * @param adjustToExtent Flag que dice si el extent solicitado debe ajustarse al extent del raster o no.

         * @param bandList

         * @return Buffer de datos

         */

        public IBuffer getWindowRaster(double ulx, double uly, double lrx, double lry) throws InvalidSetViewException;

        /**

         * Obtiene una ventana de datos de la imagen a partir de coordenadas reales. 

         * No aplica supersampleo ni subsampleo sino que devuelve una matriz de igual tama?o a los

         * pixeles de disco. 

         * @param x Posici?n X superior izquierda

         * @param y Posici?n Y superior izquierda

         * @param w Ancho en coordenadas reales

         * @param h Alto en coordenadas reales

         * @param adjustToExtent Flag que dice si el extent solicitado debe ajustarse al extent del raster o no.

         * @param bandList

         * @return Buffer de datos

         */

        public IBuffer getWindowRaster(double ulx, double uly, double w, double h, boolean adjustToExtent) 

                throws InvalidSetViewException;

        /**

         * Obtiene una ventana de datos de la imagen a partir de coordenadas reales. 

         * Aplica supersampleo o subsampleo en funci?n del tama?o del buffer. Esta operaci?n la gestiona

         * el driver.

         * @param minX Valor m?nimo de la X en coordenadas reales

         * @param minY Valor m?nimo de la Y en coordenadas reales

         * @param maxX Valor m?ximo de la X en coordenadas reales

         * @param maxY Valor m?ximo de la Y en coordenadas reales

         * @param bufWidth ancho del buffer lde datos

         * @param bufHeight alto del buffer de datos

         * @param adjustToExtent Flag que dice si el extent solicitado debe ajustarse al extent del raster o no.

         * @param bandList

         * @return Buffer de datos

         */

        public IBuffer getWindowRaster(double ulx, double uly, double lrx, double lry, 

                                                                        int bufWidth, int bufHeight, boolean adjustToExtent) throws InvalidSetViewException;

        /**

         * Obtiene una ventana de datos de la imagen a partir de coordenadas reales. 

         * No aplica supersampleo ni subsampleo sino que devuelve una matriz de igual tama?o a los

         * pixeles de disco. 

         * @param x Posici?n X superior izquierda

         * @param y Posici?n Y superior izquierda

         * @param w Ancho en coordenadas pixel

         * @param h Alto en coordenadas pixel

         * @param bandList

         * @return Buffer de datos

         */

        public IBuffer getWindowRaster(int x, int y, int w, int h) throws InvalidSetViewException;

        /**

         * Obtiene una ventana de datos de la imagen a partir de coordenadas reales. 

         * Aplica supersampleo o subsampleo en funci?n del tama?o del buffer

         * @param x Posici?n X superior izquierda en pixels

         * @param y Posici?n Y superior izquierda en pixels

         * @param w Ancho en pixels

         * @param h Alto en pixels

         * @param bufWidth ancho del buffer de datos

         * @param bufHeight alto del buffer de datos

         * @param bandList

         * @return Buffer de datos

         */

        public IBuffer getWindowRaster(int x, int y, int w, int h, int bufWidth, int bufHeight) throws InvalidSetViewException ;

        /**

         * Obtiene el extent del raster.

         * @return Extent

         */

        public Extent getExtent();

        /**

         * 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);

        /**

         * Obtiene el objeto con las estadisticas

         * @return MultiFileStatistics

         */

        public DatasetListStatistics getStatistics();

        /**

         * 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();

        /**

         * 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 el objeto que contiene que contiene la interpretaci?n de 

         * color por banda para el dataset seleccionado

         * @param dataset Dataset del que se necesesita la informaci?n de color dentro del RasterMultiDataset

         * @return DatasetColorInterpretation

         */

        public DatasetColorInterpretation getColorInterpretation(int dataset);

        /**

         * 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;

        /**

         * Metodo que obtiene si un punto cae dentro de los l?mites de la extensi?n de la fuente de 

         * datos raster o fuera de ellos.

         * @param p Punto a calcular

         * @return true si est? dentro de los l?mites y false si est? fuera

         */

        public boolean isInside(Point2D p); 

        /**

         * Recupera del raster la matriz de transformaci?n que lo situa en cualquier parte de la vista

         * @return AffineTransform

         */

        public AffineTransform getAffineTransform();

        /**

         * Asigna al raster la matriz de transformaci?n para situarlo en cualquier parte de la vista

         * @param transf

         */

        public void setAffineTransform(AffineTransform transf);

        /**

         * Consulta de si un raster tiene rotaci?n o no.

         * @return true si tiene rotaci?n y false si no la tiene.

         */

        public boolean isRotated();

        /**

         * Crea una copia del objeto IRasterDataSource

         * @return IRasterDataSource

         */

        public IRasterDataSource copy();

        /**

         * 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 dos elementos con el desplazamiento en X e Y. 

         */

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

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

        /**

         * Obtiene en un array de String la lista de nombres de ficheros. 

         * @param i Columna para un CompositeDataset 

         * @param j Fila para un CompositeDataset

         * @return lista de nombres de los ficheros del GeoRasterMultiFile

         */

        public String[] getNameDatasetStringList(int i, int j);

        /**

         * 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 getTransparencyFilesStatus();

        /**

         * Obtiene la lista de tablas de color correspondiente a todos los ficheros que forman el raster

         * @return Paleta asociada a este o null si no tiene. Una posici?n null en el array tambi?n indica que

         * para ese fichero no hay paletas asociadas.

         */

        public ColorTable[] getColorTables();

        /**

         * Salva la georreferenciaci?n a fichero rmf.

         * @param fName

         * @throws IOException  

         */

        public void saveGeoToRmf() throws IOException;

        /**

         * Escribe sobre el rmf todos los cambios que haya para salvar, es decir, para cada

         * Objeto registrado en el manager volcar? su contenido al fichero rmf.

         * @throws IOException

         */

        public void saveRmfModification() throws IOException;

        /**

         * Calcula el tama?o en byte de los raster.

         * @return tama?o en bytes de todos los ficheros de la lista

         */

        public long getFileSize();

}