Package net.buildtheearth.terraminusminus.projection

Interface GeographicProjection

All Known Implementing Classes:
AzimuthalEquidistantProjection, BTEDymaxionProjection, CenteredMercatorProjection, ClampProjectionTransform, ConformalDynmaxionProjection, DymaxionProjection, EqualEarthProjection, EquirectangularProjection, FlipHorizontalProjectionTransform, FlipVerticalProjectionTransform, LambertAzimuthalProjection, OffsetProjectionTransform, ProjectionTransform, RotateProjectionTransform, ScaleProjectionTransform, SinusoidalProjection, StereographicProjection, SwapAxesProjectionTransform, TransverseMercatorProjection, WebMercatorProjection
public interface GeographicProjection
Support for various projection types.

The geographic space is the surface of the earth, parameterized by the usual spherical coordinates system of latitude and longitude. The projected space is a plane on to which the geographic space is being projected, and is parameterized by a 2D Cartesian coordinate system (x and y).

A projection as defined here is something that projects a point in the geographic space to a point of the projected space (and vice versa).

All geographic coordinates are in degrees.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    GeographicProjection.Deserializer
     
    static class 
    GeographicProjection.Serializer
     

  • Method Summary

    Modifier and Type
    Method
    Description
    default float
    azimuth(double x, double y, float angle)
    Converts an angle in the projected space to an azimuth in the geographic space, at a specific point.
    default float
    azimuth(double x, double y, float angle, double d)
    Deprecated.
    Prefer using azimuth(double, double, float) for a default differential of 10^-7.
    default double[]
    bounds()
    Indicates the minimum and maximum X and Y coordinates on the projected space.
    double[]
    fromGeo(double longitude, double latitude)
    Converts geographic coordinates to map coordinates
    double
    metersPerUnit()
    Gives an estimation of the scale of this projection.
    static GeographicProjection
    parse(@NonNull String config)
     
    default Map<String,Object>
    properties()
     
    default double[]
    tissot(double longitude, double latitude)
    Computes the Tissot's indicatrix of this projection at the given point (i.e.
    default double[]
    tissot(double longitude, double latitude, double d)
    Deprecated.
    Prefer using tissot(double, double) for a default differential of 10^-7.
    double[]
    toGeo(double x, double y)
    Converts map coordinates to geographic coordinates
    default boolean
    upright()
    Indicates whether or not the north pole is projected to the north of the south pole on the projected space, assuming Minecraft's coordinate system cardinal directions for the projected space (north is negative Z).
    default double[]
    vector(double x, double y, double north, double east)
    Calculates the vector that goes a given distance north and a given distance east from the given point in the projected space.

  • Method Details

    • parse

      static GeographicProjection parse(@NonNull @NonNull String config)

    • toGeo

      double[] toGeo(double x, double y) throws OutOfProjectionBoundsException
      Converts map coordinates to geographic coordinates
      Parameters:
      x - - x map coordinate
      y - - y map coordinate
      Returns:
      {longitude, latitude} in degrees
      Throws:
      OutOfProjectionBoundsException - if the specified point on the projected space cannot be mapped to a point of the geographic space

    • fromGeo

      double[] fromGeo(double longitude, double latitude) throws OutOfProjectionBoundsException
      Converts geographic coordinates to map coordinates
      Parameters:
      longitude - - longitude, in degrees
      latitude - - latitude, in degrees
      Returns:
      {x, y} map coordinates
      Throws:
      OutOfProjectionBoundsException - if the specified point on the geographic space cannot be mapped to a point of the projected space

    • metersPerUnit

      double metersPerUnit()
      Gives an estimation of the scale of this projection. This is just an estimation, as distortion is inevitable when projecting a sphere onto a flat surface, so this value varies from places to places in reality.
      Returns:
      an estimation of the scale of this projection

    • bounds

      default double[] bounds()
      Indicates the minimum and maximum X and Y coordinates on the projected space.
      Returns:
      {minimum X, minimum Y, maximum X, maximum Y}

    • upright

      default boolean upright()
      Indicates whether or not the north pole is projected to the north of the south pole on the projected space, assuming Minecraft's coordinate system cardinal directions for the projected space (north is negative Z).
      Returns:
      north pole Z <= south pole Z

    • vector

      default double[] vector(double x, double y, double north, double east) throws OutOfProjectionBoundsException
      Calculates the vector that goes a given distance north and a given distance east from the given point in the projected space. This is useful to get a direction in the projected space, e.g. it is used to calculate the north vector used when sending eyes of ender.
      Parameters:
      x - - x coordinate in the projected space
      y - - y coordinate in the projected space
      north - - how far north to go, in meters on the geographic space
      east - - how far east to go, in meters on the geographic space
      Returns:
      {distance x, distance y} on the projected space
      Throws:
      OutOfProjectionBoundsException

    • tissot

      @Deprecated default double[] tissot(double longitude, double latitude, double d) throws OutOfProjectionBoundsException
      Deprecated.
      Prefer using tissot(double, double) for a default differential of 10^-7.
      Computes the Tissot's indicatrix of this projection at the given point (i.e. the distortion).
      Parameters:
      longitude - - longitude in degrees
      latitude - - latitude in degrees
      d - - a length differential in meters (a small quantity used to approximate partial derivatives)
      Returns:
      {area inflation, maximum angular distortion, maximum scale factor, minimum scale factor}
      Throws:
      OutOfProjectionBoundsException
      See Also:

    • tissot

      default double[] tissot(double longitude, double latitude) throws OutOfProjectionBoundsException
      Computes the Tissot's indicatrix of this projection at the given point (i.e. the distortion).
      Parameters:
      longitude - - longitude in degrees
      latitude - - latitude in degrees
      Returns:
      {area inflation, maximum angular distortion, maximum scale factor, minimum scale factor}
      Throws:
      OutOfProjectionBoundsException
      See Also:

    • azimuth

      @Deprecated default float azimuth(double x, double y, float angle, double d) throws OutOfProjectionBoundsException
      Deprecated.
      Prefer using azimuth(double, double, float) for a default differential of 10^-7. Smaller tends to give less accurate results.
      Converts an angle in the projected space to an azimuth in the geographic space, at a specific point. This is useful to get the direction an entity is looking at, i.e. it will be used by Terramap to show the direction entities are facing. With conformal projections, this should be equivalent to using vector(double, double, double, double) and computing the facing azimuth in the projected space, but on non-conformal projections angles are not preserved when projecting and this will be right when using vector(double, double, double, double) is likely to be wrong.
      Parameters:
      x - - x coordinate of the point in the projected space
      y - - y coordinate of the point in the projected space
      angle - - the angle to convert, in degrees, in minecraft's coordinate system (angular origin at the positive side of the Z axis, positive clockwise)
      d - - a length differential on the projected space
      Returns:
      the corresponding azimuth, in degrees, counted positively clockwise, between 0° and 360°.
      Throws:
      OutOfProjectionBoundsException - if the given point is outside the projection domain

    • azimuth

      default float azimuth(double x, double y, float angle) throws OutOfProjectionBoundsException
      Converts an angle in the projected space to an azimuth in the geographic space, at a specific point. This is useful to get the direction an entity is looking at, i.e. it will be used by Terramap to show the direction entities are facing. With conformal projections, this should be equivalent to using vector(double, double, double, double) and computing the facing azimuth in the projected space, but on non-conformal projections angles are not preserved when projecting and this will be right when using vector(double, double, double, double) is likely to be wrong.
      Parameters:
      x - - x coordinate of the point in the projected space
      y - - y coordinate of the point in the projected space
      angle - - the angle to convert, in degrees, in minecraft's coordinate system (angular origin at the positive side of the Z axis, positive clockwise)
      Returns:
      the corresponding azimuth, in degrees, counted positively clockwise, between 0° and 360°.
      Throws:
      OutOfProjectionBoundsException - if the given point is outside the projection domain

    • properties

      default Map<String,Object> properties()
      Returns:
      any additional configuration properties used by this projection