001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.data.projection.proj;
003
004import org.openstreetmap.josm.data.projection.ProjectionConfigurationException;
005
006/**
007 * A projection (in the narrow sense).
008 *
009 * Converts lat/lon the east/north and the other way around.
010 *
011 * Datum conversion, false easting / northing, origin of longitude
012 * and general scale factor is already applied when the projection is invoked.
013 *
014 * Lat/lon is not in degrees, but in radians (unlike other parts of JOSM).
015 * Additional parameters in the constructor arguments are usually still in
016 * degrees. So to avoid confusion, you can follow the convention, that
017 * coordinates in radians are called lat_rad/lon_rad or phi/lambda.
018 *
019 * East/north values are not in meters, but in meters divided by the semi major
020 * axis of the ellipsoid (earth radius). (Usually this is what you get anyway,
021 * unless you multiply by 'a' somehow implicitly or explicitly.)
022 *
023 */
024public interface Proj {
025
026    /**
027     * Replies a human readable name of this projection.
028     * @return The projection name. must not be null.
029     */
030    String getName();
031
032    /**
033     * Replies the Proj.4 identifier.
034     *
035     * @return The Proj.4 identifier (as reported by cs2cs -lp).
036     * If no id exists, return {@code null}.
037     */
038    String getProj4Id();
039
040    /**
041     * Initialize the projection using the provided parameters.
042     * @param params The projection parameters
043     *
044     * @throws ProjectionConfigurationException in case parameters are not suitable
045     */
046    void initialize(ProjParameters params) throws ProjectionConfigurationException;
047
048    /**
049     * Convert lat/lon to east/north.
050     *
051     * @param lat_rad the latitude in radians
052     * @param lon_rad the longitude in radians
053     * @return array of length 2, containing east and north value in meters,
054     * divided by the semi major axis of the ellipsoid.
055     */
056    double[] project(double lat_rad, double lon_rad);
057
058    /**
059     * Convert east/north to lat/lon.
060     *
061     * @param east east value in meters, divided by the semi major axis of the ellipsoid
062     * @param north north value in meters, divided by the semi major axis of the ellipsoid
063     * @return array of length 2, containing lat and lon in radians.
064     */
065    double[] invproject(double east, double north);
066}