001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.data.projection;
003
004import java.util.Map;
005
006import org.openstreetmap.josm.data.ProjectionBounds;
007import org.openstreetmap.josm.data.coor.EastNorth;
008import org.openstreetmap.josm.data.coor.LatLon;
009
010/**
011 * Classes implementing this are able to project between screen (east/north) and {@link LatLon} coordinates.
012 * <p>
013 * Each instance is backed by a base projection but may e.g. offset the resulting position.
014 * @author Michael Zangl
015 * @since 10805
016 */
017public interface Projecting {
018
019    /**
020     * Convert from lat/lon to easting/northing.
021     *
022     * @param ll the geographical point to convert (in WGS84 lat/lon)
023     * @return the corresponding east/north coordinates
024     */
025    EastNorth latlon2eastNorth(LatLon ll);
026
027    /**
028     * Convert a east/north coordinate to the {@link LatLon} coordinate.
029     * This method clamps the lat/lon coordinate to the nearest point in the world bounds.
030     * @param en east/north
031     * @return The lat/lon coordinate.
032     */
033    LatLon eastNorth2latlonClamped(EastNorth en);
034
035    /**
036     * Gets the base projection instance used.
037     * @return The projection.
038     */
039    Projection getBaseProjection();
040
041    /**
042     * Returns an map or (subarea, projecting) paris that contains projecting instances to convert the coordinates inside the given area.
043     * This can be used by projections to support continuous projections.
044     *
045     * It is possible that the area covered by the map is bigger than the one given as area. There may be holes.
046     * @param area The base area
047     * @return a map of non-overlapping {@link ProjectionBounds} instances mapped to the {@link Projecting} object to use for that area.
048     */
049    Map<ProjectionBounds, Projecting> getProjectingsForArea(ProjectionBounds area);
050}