Package org.geotools.referencing.operation.projection

Class MapProjection

    • Field Detail

      • SKIP_SANITY_CHECKS

        public static boolean SKIP_SANITY_CHECKS
        A global variable use to disable the reciprocal distance checks made when assertions are enabled. This allows tests to work in "real world" conditions, where users often ask for points that are way to far from the correct area of usage of projections

      • LOGGER

        protected static final Logger LOGGER
        The projection package logger

      • semiMajor

        protected final double semiMajor
        Length of semi-major axis, in metres. This is named 'a' or 'R' (Radius in spherical cases) in Snyder.
        See Also:
        excentricity, semiMinor

      • semiMinor

        protected final double semiMinor
        Length of semi-minor axis, in metres. This is named 'b' in Snyder.
        See Also:
        excentricity, semiMajor

      • centralMeridian

        protected double centralMeridian
        Central longitude in radians. Default value is 0, the Greenwich meridian. This is called 'lambda0' in Snyder.

        Consider this field as final. It is not final only because some classes need to modify it at construction time.

      • latitudeOfOrigin

        protected double latitudeOfOrigin
        Latitude of origin in radians. Default value is 0, the equator. This is called 'phi0' in Snyder.

        Consider this field as final. It is not final only because some classes need to modify it at construction time.

      • scaleFactor

        protected double scaleFactor
        The scale factor. Default value is 1. Named 'k' in Snyder.

        Consider this field as final. It is not final only because some classes need to modify it at construction time.

      • falseEasting

        protected final double falseEasting
        False easting, in metres. Default value is 0.

      • falseNorthing

        protected final double falseNorthing
        False northing, in metres. Default value is 0.

      • globalScale

        protected double globalScale
        Global scale factor. Default value globalScale is equal to semiMajor×scaleFactor.

        Consider this field as final. It is not final only because some classes need to modify it at construction time.

      • en0

        protected double en0
        Constant needed for the mlfn method. Setup at construction time.

      • en1

        protected double en1
        Constant needed for the mlfn method. Setup at construction time.

      • en2

        protected double en2
        Constant needed for the mlfn method. Setup at construction time.

      • en3

        protected double en3
        Constant needed for the mlfn method. Setup at construction time.

      • en4

        protected double en4
        Constant needed for the mlfn method. Setup at construction time.

      • invertible

        protected boolean invertible
        Marks if the projection is invertible. The vast majority is, subclasses can override.

    • Constructor Detail

      • MapProjection

        protected MapProjection​(ParameterValueGroup values)
                 throws ParameterNotFoundException
        Constructs a new map projection from the suplied parameters.
        Parameters:
        values - The parameter values in standard units. The following parameter are recognized:
        • "semi_major" (mandatory: no default)
        • "semi_minor" (mandatory: no default)
        • "central_meridian" (default to 0°)
        • "latitude_of_origin" (default to 0°)
        • "scale_factor" (default to 1 )
        • "false_easting" (default to 0 )
        • "false_northing" (default to 0 )
        Throws:
        ParameterNotFoundException - if a mandatory parameter is missing.

    • Method Detail

      • orthodromicDistance

        protected double orthodromicDistance​(Point2D source,
                                     Point2D target)
        Returns the orthodromic distance between the two specified points using a spherical approximation. This is used for assertions only.

      • checkReciprocal

        protected boolean checkReciprocal​(Point2D point,
                                  Point2D target,
                                  boolean inverse)
                           throws ProjectionException
        Check if the transform of point is close enough to target. "Close enough" means that the two points are separated by a distance shorter than getToleranceForAssertions(double, double). This method is used for assertions with J2SE 1.4.
        Parameters:
        point - Point to transform, in decimal degrees if inverse is false.
        target - Point to compare to, in metres if inverse is false.
        inverse - true for an inverse transform instead of a direct one.
        Returns:
        true if the two points are close enough.
        Throws:
        ProjectionException

      • inverseTransformNormalized

        protected abstract Point2D inverseTransformNormalized​(double x,
                                                      double y,
                                                      Point2D ptDst)
                                               throws ProjectionException
        Transforms the specified coordinate and stores the result in ptDst. This method returns longitude as x values in the range [-PI..PI] and latitude as y values in the range [-PI/2..PI/2]. It will be checked by the caller, so this method doesn't need to performs this check.

        Input coordinates have the falseEasting and falseNorthing removed and are divided by globalScale before this method is invoked. After this method is invoked, the centralMeridian is added to the x results in ptDst. This means that projections that implement this method are performed on an ellipse (or sphere) with a semi-major axis of 1.

        In PROJ.4, the same standardization, described above, is handled by pj_inv.c. Therefore when porting projections from PROJ.4, the inverse transform equations can be used directly here with minimal change. In the equations of Snyder, falseEasting, falseNorthing and scaleFactor are usually not given. When implementing these equations here, you will not need to add the centralMeridian to the output longitude or remove the semiMajor (a or R).

        Parameters:
        x - The easting of the coordinate, linear distance on a unit sphere or ellipse.
        y - The northing of the coordinate, linear distance on a unit sphere or ellipse.
        ptDst - the specified coordinate point that stores the result of transforming ptSrc, or null. Ordinates will be in radians.
        Returns:
        the coordinate point after transforming x, y and storing the result in ptDst.
        Throws:
        ProjectionException - if the point can't be transformed.

      • transformNormalized

        protected abstract Point2D transformNormalized​(double lambda,
                                               double phi,
                                               Point2D ptDst)
                                        throws ProjectionException
        Transforms the specified coordinate and stores the result in ptDst. This method is usually (but not guaranteed) to be invoked with values of x in the range [-PI..PI] and values of y in the range [-PI/2..PI/2]. Values outside those ranges are accepted (sometime with a warning logged) on the assumption that most implementations use those values only in trigonometric functions like sin and cos.

        Coordinates have the centralMeridian removed from lambda before this method is invoked. After this method is invoked, the results in ptDst are multiplied by globalScale, and the falseEasting and falseNorthing are added. This means that projections that implement this method are performed on an ellipse (or sphere) with a semi-major axis of 1.

        In PROJ.4, the same standardization, described above, is handled by pj_fwd.c. Therefore when porting projections from PROJ.4, the forward transform equations can be used directly here with minimal change. In the equations of Snyder, falseEasting, falseNorthing and scaleFactor are usually not given. When implementing these equations here, you will not need to remove the centralMeridian from lambda or apply the semiMajor (a or R).

        Parameters:
        lambda - The longitude of the coordinate, in radians.
        phi - The latitude of the coordinate, in radians.
        ptDst - the specified coordinate point that stores the result of transforming ptSrc, or null. Ordinates will be in a dimensionless unit, as a linear distance on a unit sphere or ellipse.
        Returns:
        the coordinate point after transforming (lambda, phi) and storing the result in ptDst.
        Throws:
        ProjectionException - if the point can't be transformed.

      • transform

        public final void transform​(double[] srcPts,
                            int srcOff,
                            double[] dstPts,
                            int dstOff,
                            int numPts)
                     throws ProjectionException
        Transforms a list of coordinate point ordinal values. Ordinates must be (longitude,latitude) pairs in decimal degrees.
        Specified by:
        transform in interface MathTransform
        Parameters:
        srcPts - the array containing the source point coordinates.
        srcOff - the offset to the first point to be transformed in the source array.
        dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.
        dstOff - the offset to the location of the first transformed point that is stored in the destination array.
        numPts - the number of point objects to be transformed.
        Throws:
        ProjectionException - if a point can't be transformed. This method tries to transform every points even if some of them can't be transformed. Non-transformable points will have value Double.NaN. If more than one point can't be transformed, then this exception may be about an arbitrary point.

      • transform

        public final void transform​(float[] srcPts,
                            int srcOff,
                            float[] dstPts,
                            int dstOff,
                            int numPts)
                     throws ProjectionException
        Transforms a list of coordinate point ordinal values. Ordinates must be (longitude,latitude) pairs in decimal degrees.
        Specified by:
        transform in interface MathTransform
        Overrides:
        transform in class AbstractMathTransform
        Parameters:
        srcPts - the array containing the source point coordinates.
        srcOff - the offset to the first point to be transformed in the source array.
        dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.
        dstOff - the offset to the location of the first transformed point that is stored in the destination array.
        numPts - the number of point objects to be transformed.
        Throws:
        ProjectionException - if a point can't be transformed. This method tries to transform every points even if some of them can't be transformed. Non-transformable points will have value Float.NaN. If more than one point can't be transformed, then this exception may be about an arbitrary point.

      • getToleranceForAssertions

        protected double getToleranceForAssertions​(double longitude,
                                           double latitude)
        Maximal error (in metres) tolerated for assertions, if enabled. When assertions are enabled, every direct projection is followed by an inverse projection, and the result is compared to the original coordinate. If a distance greater than the tolerance level is found, then an ProjectionException will be thrown. Subclasses should override this method if they need to relax the tolerance level.
        Parameters:
        longitude - The longitude in decimal degrees.
        latitude - The latitude in decimal degrees.
        Returns:
        The tolerance level for assertions, in meters.

      • resetWarnings

        public static void resetWarnings()
        Resets the warning status of all projections in the current JVM. Every MapProjection instance may log a warning the first time they are given coordinates outside their area of validity. Subsequent coordinates outside the area of validity are silently projected in order to avoid flowing the log with warnings. In case of suspicion, this method may be invoked in order to force all projections to log again their first out-of-bounds coordinates.

        Multi-threading
        Calls to this method have immediate effect in the invoker's thread. The effect in other threads may be delayed by some arbitrary amount of time. This method works only on a "best effort" basis.

        Since:
        2.5
        See Also:
        CRS.reset(java.lang.String)

      • equals

        public boolean equals​(Object object)
        Compares the specified object with this map projection for equality.
        Overrides:
        equals in class AbstractMathTransform
        Parameters:
        object - The object to compare with this transform.
        Returns:
        true if the given object is a transform of the same class and if, given identical source position, the transformed position would be the equals.

      • mlfn

        protected final double mlfn​(double phi,
                            double sphi,
                            double cphi)
        Calculates the meridian distance. This is the distance along the central meridian from the equator to phi. Accurate to < 1e-5 meters when used in conjuction with typical major axis values.
        Parameters:
        phi - latitude to calculate meridian distance for.
        sphi - sin(phi).
        cphi - cos(phi).
        Returns:
        meridian distance for the given latitude.

      • inv_mlfn

        protected final double inv_mlfn​(double arg)
                         throws ProjectionException
        Calculates the latitude (phi) from a meridian distance. Determines phi to TOL (1e-11) radians, about 1e-6 seconds.
        Parameters:
        arg - meridian distance to calulate latitude for.
        Returns:
        the latitude of the meridian distance.
        Throws:
        ProjectionException - if the itteration does not converge.