001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.data.projection;
003
004import org.openstreetmap.josm.data.Bounds;
005import org.openstreetmap.josm.data.coor.EastNorth;
006import org.openstreetmap.josm.data.coor.LatLon;
007
008/**
009 * A projection, i.e. a class that supports conversion from lat/lon
010 * to east/north and back.
011 *
012 * The conversion from east/north to the screen coordinates is simply a scale
013 * factor and x/y offset.
014 */
015public interface Projection {
016    /**
017     * The default scale factor in east/north units per pixel
018     * ({@link org.openstreetmap.josm.gui.NavigatableComponent#scale})).
019     * FIXME: misnomer
020     * @return the scale factor
021     */
022    double getDefaultZoomInPPD();
023
024    /**
025     * Convert from lat/lon to easting/northing.
026     *
027     * @param ll the geographical point to convert (in WGS84 lat/lon)
028     * @return the corresponding east/north coordinates
029     */
030    EastNorth latlon2eastNorth(LatLon ll);
031
032    /**
033     * Convert from easting/norting to lat/lon.
034     *
035     * @param en the geographical point to convert (in projected coordinates)
036     * @return the corresponding lat/lon (WGS84)
037     */
038    LatLon eastNorth2latlon(EastNorth en);
039
040    /**
041     * Describe the projection in one or two words.
042     * @return the name / description
043     */
044    String toString();
045
046    /**
047     * Return projection code.
048     *
049     * This should be a unique identifier.
050     * If projection supports parameters, return a different code
051     * for each set of parameters.
052     *
053     * The EPSG code can be used (if defined for the projection).
054     *
055     * @return the projection identifier
056     */
057    String toCode();
058
059    /**
060     * Get a filename compatible string (for the cache directory).
061     * @return the cache directory name (base name)
062     */
063    String getCacheDirectoryName();
064
065    /**
066     * Get the bounds of the world.
067     * @return the supported lat/lon rectangle for this projection
068     */
069    Bounds getWorldBoundsLatLon();
070
071    /**
072     * Get the number of meters per unit of this projection. This more
073     * defines the scale of the map, than real conversion of unit to meters
074     * as this value is more less correct only along great circles.
075     *
076     * Used by WMTS to properly scale tiles
077     * @return meters per unit of projection
078     *
079     */
080    double getMetersPerUnit();
081
082    /**
083     * Does this projection natural order of coordinates is North East,
084     * instead of East North
085     *
086     * @return true if natural order of coordinates is North East, false if East North
087     */
088    boolean switchXY();
089}