Application: gvSIG desktop » gvSIG projections

/**

 * gvSIG. Desktop Geographic Information System.

 *

 * Copyright (C) 2007-2012 gvSIG Association.

 *

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

 *

 * For any additional information, do not hesitate to contact us

 * at info AT gvsig.com, or visit our website www.gvsig.com.

 */

package org.gvsig.proj.catalog;

import java.io.File;

import java.text.ParseException;

import java.util.Collection;

import java.util.List;

import org.gvsig.proj.catalog.exception.CoordinateReferenceSystemException;

import org.gvsig.proj.catalog.exception.UnsupportedCoordinateReferenceSystemException;

import org.gvsig.proj.catalog.exception.UnsupportedFormatException;

import org.gvsig.proj.catalog.exception.UnsupportedTransformationException;

import org.gvsig.proj.catalog.extent.Extent;

import org.gvsig.proj.catalog.extent.GeographicBoundingBox;

import org.gvsig.proj.catalog.extent.VerticalExtent;

/**

 * This class is responsible of the management of the CRSCatalog

 * library's business logic.

 * 

 * It is the library's main entry point, and provides all the services to manage

 * {@link CRSDefinition}s and {@link TransformationDefinition}s.

 * 

 * @author gvSIG team

 * @author Cesar Martinez Izquierdo

 */

public interface CRSCatalogManager {

        /**

         * Returns a List of String values with the available authority names.

         * 

         * @return the available authority names

         */

        List<String> getAuthorityNames();

        /**

         * Returns a List of String values with the codes available for all the

         * available authorities

         *

         * @return the list of available codes, using the AUTHORITY:CODE format

         */

        List<String> getCodes();

        /**

         * Returns a List of String values with the codes available for a given

         * Authority,

         * 

         * @param authorityName

         *            name of the authority to get the codes of

         * @return the list of available codes, using the AUTHORITY:CODE format

         */

        List<String> getCodes(String authorityName);

        /**

         * Returns a list of codes that match the provided search string.

         * Examples of valid searchString: "4326", "EPSG:4326", "ESRI:4326", etc.

         * Depending on the implementation of the catalogue, it may search only

         * codes or it may search on several CRS fields (name, description,

         * area description, etc)

         * 

         * @param searchString

         * @return

         */

        List<String> search(String searchString);

        /**

         * Returns a list of codes that match the provided search string.

         * Examples of valid searchString: "4326", "EPSG:4326", "ESRI:4326", etc.

         * Depending on the implementation of the catalog, it may only search for

         * codes or it may search on several CRS fields (name, description,

         * area description, etc)

         *

         * @param authority Include only CRSs of the provided authority

         * @param searchString

         * @return

         */

        List<String> search(String authority, String searchString);

        /**

         * Returns a list of codes that match the provided search string.

         * Examples of valid searchString: "4326", "EPSG:4326", "ESRI:4326", etc.

         * Depending on the implementation of the catalog, it may only search for

         * codes or it may search on several CRS fields (name, description,

         * area description, etc)

         * 

         * @param authority Include only CRSs of the provided authority

         * @param searchString

         * @param includeTypes Include only CRSs whose type is one of the provided {@code CRSType}s. If {@code null} or

         * an empty array is provided, all CRSs are included

         * @param excludeTypes Exclude CRSs whose type is one of the provided {@code CRSType}s. If a CRS is provided in

         * both {@code includeTypes} and {@code excludeTypes}, then it is excluded from results. 

         * conflict with 

         * @return

         */

        List<String> search(String authority, String searchString, CRSType[] includeTypes, CRSType[] excludeTypes);

        /**

         * Gets the CRSDefinition for the provided code

         * @param code The CRS code (e.g. "EPSG:4326", "ESRI:4326")

         * 

         * @return

         * @throws UnsupportedCoordinateReferenceSystemException 

         */

        CRSDefinition getCRSDefinition(String code) throws UnsupportedCoordinateReferenceSystemException;

        /**

         * Parses the provided CRS definition to create a {@link CRSDefinition} object

         *  

         * @param def A string containing the definition to parse (e.g. a WKT

         * CRS definition, a GML CRS definition, etc)

         * @return A {@link CRSDefinition} object

         * @throws UnsupportedCoordinateReferenceSystemException if the reference system is not supported by

         * this implementation

         * @throws ParseException  if the provided string can't be parsed (for instance because it is not

         * a valid document in any of the supported formats)

         */

        CRSDefinition parseCRSDefinition(String def)

                        throws UnsupportedCoordinateReferenceSystemException, ParseException;

        /**

         * Parses the provided CRS definition to create a {@link CRSDefinition} object

         * 

         * @param def A string containing the definition to parse (e.g. a WKT

         * definition, a GML definition, etc)

         * @param format The format of the definition to parse

         * @return A {@link CRSDefinition} object

         * @throws UnsupportedCoordinateReferenceSystemException if the reference system is not supported by

         * this implementation

         * @throws ParseException if the provided string can't be parsed (for instance, because it is not

         * a valid document in the specified format)

         * @throws UnsupportedFormatException if the format is not supported

         */

        CRSDefinition parseCRSDefinition(String def, TextSerialization.Format format)

                        throws UnsupportedCoordinateReferenceSystemException, ParseException, UnsupportedFormatException;

        /**

         * Creates a compound CRS by combining the provided individual

         * CRSDefinitions. 

         * 

         * @param crsList The list of CRSDefinitions to compound

         * @return The definition of the compound CRS

         * @throws CoordinateReferenceSystemException 

         * 

         * @see CRSType#CompoundCRSType

         * @see CRSDefinition#getComponents()

         * @see CRSDefinition#getType()

         */

        CRSDefinition getCompoundCRS(CRSDefinition... crsList) throws CoordinateReferenceSystemException;

        /**

         * Gets the TransformationDefinition for the provided code. Most of the time it is preferable to use

         * {@link #getCoordinateTransformations(CRSDefinition, CRSDefinition), since it will automatically construct

         * complex transformation paths which are not accounted in this method.

         * 

         * @param code The operation code (e.g. "EPSG:1633", "EPSG:1632")

         * @return The requested transformation

         * @see {@link #getCoordinateTransformations(CRSDefinition, CRSDefinition)

         */

        TransformationDefinition getTransformationDefinition(String code) throws UnsupportedTransformationException;

        /**

         * Parses the provided transformation definition to create a {@link TransformationDefinition} object.

         * Note that some {@link TextSerialization.Format formats} don't encode the source and target CRSs, so

         * this method will fail for these formats. Use {@link #parseTransformationDefinition(String, String, String)

         * or #parseTransformationDefinition(String, String, String, org.gvsig.proj.catalog.TextSerialization.Format)

         * instead.

         *  

         * @param def A string containing the definition to parse (e.g. a WKT

         * definition, a GML definition, etc)

         * @return A {@link TransformationDefinition} object

         * @throws UnsupportedCoordinateReferenceSystemException if the transformation is not supported by

         * this implementation

         * @throws ParseException if the provided string can't be parsed (for instance because it is not

         * a valid document in any of the supported formats)

         * @throws CoordinateReferenceSystemException if the format does not provide enough information to

         * construct the CRS. Use {@link #parseTransformationDefinition(String, String, String)} instead

         */

        TransformationDefinition parseTransformationDefinition(String def)

                        throws UnsupportedTransformationException, ParseException, CoordinateReferenceSystemException;

        /**

         * Parses the provided transformation definition to create a {@link TransformationDefinition} object.

         * This method also requires the source and target CRSs of the operation, since some serialization

         * formats don't encode this information (e.g. {@link TextSerialization.Format#WKT1} only encodes

         * the math transform). 

         *  

         * @param def A string containing the definition to parse (e.g. a WKT

         * definition, a GML definition, etc)

         * @param sourceCRS the source CRS for this operation, encoded as a {@link CRSDefinition#getIdentifier() identifier}

         * or as a WKT CRS string.

         * @param targetCRS the target CRS for this operation, encoded as a {@link CRSDefinition#getIdentifier() identifier}

         * or as a WKT CRS string.

         * @return A {@link TransformationDefinition} object

         * @throws UnsupportedCoordinateReferenceSystemException if the transformation is not supported by

         * this implementation

         * @throws ParseException if the provided string can't be parsed (for instance because it is not

         * a valid document in any of the supported formats)

         */

        TransformationDefinition parseTransformationDefinition(String def, String sourceCRS, String targetCRS)

                                        throws UnsupportedTransformationException, ParseException;

        /**

         * Parses the provided CRS definition to create a {@link TransformationDefinition} object.

         * Note that some {@link TextSerialization.Format formats} don't encode the source and target CRSs, so

         * this method will fail for these formats. Use {@link #parseTransformationDefinition(String, String, String)

         * or #parseTransformationDefinition(String, String, String, org.gvsig.proj.catalog.TextSerialization.Format)

         * instead.

         * 

         * @param def A string containing the definition to parse (e.g. a WKT

         * definition, a GML definition, etc)

         * @param format The format of the definition to parse

         * @return A {@link TransformationDefinition} object

         * @throws UnsupportedCoordinateReferenceSystemException if the transformation is not supported by

         * this implementation

         * @throws ParseException if the provided string can't be parsed (for instance, because it is not

         * a valid document in the specified format)

         * @throws UnsupportedFormatException if the format is not supported

         * @throws CoordinateReferenceSystemException  if the format does not provide enough information to

         * construct the CRS. Use {@link #parseTransformationDefinition(String, String, String)} instead

         */

        TransformationDefinition parseTransformationDefinition(String def, TextSerialization.Format format)

                        throws UnsupportedTransformationException, ParseException, UnsupportedFormatException, CoordinateReferenceSystemException;

        /**

         * Parses the provided CRS definition to create a {@link TransformationDefinition} object. 

         * This method also requires the source and target CRSs of the operation, since some serialization

         * formats don't encode this information (e.g. {@link TextSerialization.Format#WKT1} only encodes

         * the math transform). 

         * 

         * @param def A string containing the definition to parse (e.g. a WKT

         * definition, a GML definition, etc)?

         * @param sourceCRS the source CRS for this operation, encoded as a {@link CRSDefinition#getIdentifier() identifier}

         * or as a WKT CRS string.

         * @param targetCRS the target CRS for this operation, encoded as a {@link CRSDefinition#getIdentifier() identifier}

         * or as a WKT CRS string.

         * @param format The format of the definition to parse

         * @return A {@link TransformationDefinition} object

         * @throws UnsupportedCoordinateReferenceSystemException if the transformation is not supported by

         * this implementation

         * @throws ParseException if the provided string can't be parsed (for instance, because it is not

         * a valid document in the specified format)

         * @throws UnsupportedFormatException if the format is not supported

         */

        TransformationDefinition parseTransformationDefinition(String def, String sourceCRS, String targetCRS,

                        TextSerialization.Format format)

                        throws UnsupportedTransformationException, ParseException, UnsupportedFormatException;

        /**

         * Register a user-defined CRS from an WKT definition

         * 

         * @param wktDefinition The WKT definition of the CRS to register

         * @param description A human-readable description of the CRS

         * @return The code assigned to the registered CRS on the USER

         * namespace

         */

        String registerCoordinateReferenceSystem(String wktDefinition, String description)

                        throws UnsupportedCoordinateReferenceSystemException, ParseException;

        /**

         * Register a user-defined coordinate operation

         * 

         * @param wktDefinition The WKT definition of the operation to register

         * @param sourceCRS the source CRS for this operation, encoded as a {@link CRSDefinition#getIdentifier() identifier}

         * or as a WKT CRS string.

         * @param targetCRS the target CRS for this operation, encoded as a {@link CRSDefinition#getIdentifier() identifier}

         * or as a WKT CRS string.

         * @param description A human-readable description of the CRS

         * @return The code assigned to the registered CRS on the USER

         * namespace

         */

        String registerTransformation(String wktDefinition, String sourceCRS, String targetCRS, String description)

                        throws UnsupportedTransformationException, ParseException;

        /**

         * Register a user-defined coordinate transformation using the Position

         * Vector Transformation method

         * 

         * @param definition The WKT definition of the operation to register

         * @return The code assigned to the registered CRS on the USER

         * namespace

         * @see #registerCoordinateTransformationCFR(String, String, String, float, float, float, float, float, float, float)

         */

        String registerCoordinateTransformationPVT(String sourceCRS, String targetCRS,

                        String description,

                        float xTraslation, float yTraslation, float zTraslation,

                        float xRotation, float yRotation, float zRotation,

                        float scaleDifference)

                                        throws UnsupportedTransformationException, ParseException;

        /**

         * Register a user-defined coordinate transformation using the Coordinate

         * Frame Rotation method

         * 

         * @param definition The WKT definition of the operation to register

         * @return The code assigned to the registered CRS on the USER

         * namespace

         * @see #registerCoordinateTransformationPVT(String, String, String, float, float, float, float, float, float, float)

         */

        String registerCoordinateTransformationCFR(String sourceCRS, String targetCRS,

                        String description,

                        float xTraslation, float yTraslation, float zTraslation,

                        float xRotation, float yRotation, float zRotation,

                        float scaleDifference)

                                        throws UnsupportedTransformationException, ParseException;

        /**

         * Register a user-defined coordinate transformation using a

         * transformation grid in NTv2 format

         * 

         * @param definition The WKT definition of the operation to register

         * @return The code assigned to the registered CRS on the USER

         * namespace

         */

        String registerCoordinateTransformation(String sourceCRS, String targetCRS,

                        String description, File ntv2Grid)

                                        throws UnsupportedTransformationException, ParseException;

        /**

         * Gets the list of available TransformationDefinition to transform or

         * convert coordinates from the source CoordinateReferenceSystem to

         * the target one. 

         * @param source

         * @param target

         * @return

         * @throws CoordinateReferenceSystemException 

         */

        List<TransformationDefinition> getCoordinateTransformations(CRSDefinition source, CRSDefinition target) throws CoordinateReferenceSystemException;

        /**

         * Gets the list of available TransformationDefinition to transform or

         * convert coordinates from the source CoordinateReferenceSystem to

         * the target one.

         * 

         * @param source The code of the source CRS (e.g. "ESPG:25830")

         * @param target The code of the target CRS (e.g. "ESPG:4230")

         * @return

         */

        List<TransformationDefinition> getCoordinateTransformations(String source, String target) throws CoordinateReferenceSystemException;

        /**

         * Sets the path to the folder to be used by the library to load the CRS and

         * transformation definitions. The structure and format of the definitions contained in

         * the folder is implementation-dependent, so it must be prepared for a particular

         * CRS catalog implementation.

         * 

         * This method only has effect when it is called before any other method in the manager

         * (before instantiating any CRS, transformation, etc). 

         * 

         * @param path The path to the folder containing the system CRS and transformation

         * definitions

         */

        void setSystemDataPath(File path);

        /**

         * Sets the path to the folder to be used by the library to load the user defined

         * CRS and transformation definitions. The structure and format of the definitions

         * contained in the folder is implementation-dependent, so it must be prepared for

         * a particular CRS catalog implementation.

         * 

         * This method only has effect when it is called before any other method in the manager

         * (before instantiating any CRS, transformation, etc).

         * 

         * @param path The path to the folder containing the user defined CRS and transformation

         * definitions

         */

        void setUserDataPath(File path);

        /**

         * Gets the formats (WKT, GML, etc) for text serialization of CRSs and transformations

         * which are supported by this particular implementation

         * 

         * @return

         */

        List<TextSerialization.Format> getSupportedFormats();

        /**

         * Creates a GeographicBoundingBox, defining a rectangular extent in WGS84

         * coordinates.

         * 

         * @param westBoundLongitude

         * @param eastBoundLongitude

         * @param northBoundLatitude

         * @param southBoundLatitude

         * @return

         */

        GeographicBoundingBox createBoundingBox(

                        double westBoundLongitude,

                        double eastBoundLongitude,

                        double northBoundLatitude,

                        double southBoundLatitude

                        );

        /**

         * Creates a vertical extent

         * @param crs The coordinate reference system that the vertical coordinates are

         * referred to.

         * @param minValue The minimum coordinate value

         * @param maxValue The maximum coordinate value

         * @return

         */

        VerticalExtent createVerticalExtent(

                        CRSDefinition crs,

                        double minValue,

                        double maxValue);

        /**

         * Creates an extent definition, which can be composed of a textual description,

         * a collection of horizontal bounding box and a collection of vertical extents.

         * 

         * @param description

         * @param horizontalBoundingBoxList

         * @param verticalBoundingBoxList

         * @return

         */

        Extent createExtent(String description, Collection<GeographicBoundingBox> horizontalBoundingBoxList,

                        Collection<VerticalExtent> verticalBoundingBoxList);

}