Merge branch 'master' into 4.0.x

Author: dvdoug

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [4.1.0] - 2021-03-03
+### Added
+- Added `UTMPoint` as a better way of handling UTM zones than the EPSG model does it
+- Improved conversion chaining for `CompoundPoint`s
+### Changed
+- moved `verticalOffsetAndSlope` method from `CompoundPoint` to `VerticalPoint`. This is technically a breaking change, but since the code is only 2 days old shouldn't affect anyone.
+
 ## [4.0.1] - 2021-03-01
 ### Fixed
 - Documentation issues

docs/builtin_units_angles.rst

@@ -2,7 +2,7 @@ Units of angle
 ==============
 
 .. tip::
-    All angle units have helper methods ``->asDegrees()``, ``->asRadians()``, ``->add()``, ``->substract()``,
+    All angle units have helper methods ``->asDegrees()``, ``->asRadians()``, ``->add()``, ``->subtract()``,
     ``->multiply()`` and ``->divide()``
 
 Degree

docs/builtin_units_lengths.rst

@@ -2,7 +2,7 @@ Units of length
 ===============
 
 .. tip::
-    All length units have helper methods ``->asMetres()``, ``->add()``, ``->substract()``,
+    All length units have helper methods ``->asMetres()``, ``->add()``, ``->subtract()``,
     ``->multiply()`` and ``->divide()``
 
 Metre

docs/builtin_units_scales.rst

@@ -2,7 +2,7 @@ Units of scale
 ==============
 
 .. tip::
-    All scale units have helper methods ``->asUnity()``, ``->add()``, ``->substract()``,
+    All scale units have helper methods ``->asUnity()``, ``->add()``, ``->subtract()``,
     ``->multiply()`` and ``->divide()``
 
 Unity

docs/builtin_units_times.rst

@@ -2,7 +2,7 @@ Units of time
 =============
 
 .. tip::
-    All time units have helper methods ``->asYears()``, ``->add()``, ``->substract()``,
+    All time units have helper methods ``->asYears()``, ``->add()``, ``->subtract()``,
     ``->multiply()`` and ``->divide()``
 
 Year

docs/coordinate_conversions.rst

@@ -2,17 +2,17 @@ Coordinate conversions
 ======================
 PHPCoord can convert coordinates representing a point from one *Coordinate Reference System (CRS)* to another one. In
 this simplest case this might just be converting units (e.g. feet to metres or vice versa), but in most cases involves
-running one or more complex algorithms involving a **lot** of trigonometry on the numbers.
+running one or more complex algorithms on the numbers.
 
-Most algorithms are not standalone, but require parameters to be work - for instance many require the origin point
+Most such algorithms are not standalone, but require parameters to work - for instance many require an origin point
 to be specified and these points differ across mapping systems even when they utilise the same algorithm. Knowing both
-the algorithm(s) to be used and the parameters used to tune them is essential for high-accuracy conversions.
+the algorithm(s) to be used and the parameters used to tune them is essential to perform high-accuracy conversions.
 
 .. note::
     If the Earth were actually the shape of an ellipsoid, algorithms could be devised so that conversions between systems
     could be performed with no absolutely no loss of accuracy - systems would in effect be mathematically equivalent.
 
-    Unfortunately the Earth isn't an ellipsoid and (pre-GPS) all coordinates were calculated by individual humans
+    Unfortunately the Earth isn't an ellipsoid and coordinates are determined by individual humans
     operating on the Earth's actual, irregular surface using instruments subject to observation error. That means
     that conversions between CRSs are not just converting between mathematical ideals but often convert between
     *sets of observations*. When this happens it means that the conversions between the CRSs can only ever be
@@ -28,7 +28,7 @@ PHPCoord offers two models of operation for coordinate conversion:
 * The hard way in which you can directly utilise one of the many implemented algorithms along with the parameters of your
   choice to keep full control over the conversion
 * The easy way in which PHPCoord consults the built-in EPSG dataset for the relevant algorithm(s) to use and best
-  parameters to use for your chosen conversion and executes them behind the scenes on your behalf. Recommended.
+  parameters to use for your chosen conversion and executes them behind the scenes on your behalf.
 
 .. toctree::
     :maxdepth: 1

docs/coordinate_conversions_easy.rst

@@ -18,9 +18,9 @@ coordinates in the target CRS.
 
 Although PHPCoord has knowledge of thousands of different conversions, this does not cover many scenarios. For example
 there is no published direct conversion between a British National Grid reference and a UTM Grid reference. In these
-scenarios PHPCoord can "chain" conversions it does know about to achieve the desired result. For that scenario, it would
+scenarios PHPCoord can "chain" conversions it does know about to achieve the desired result, for example it would
 automatically calculate British National Grid -> OSGB36 -> WGS84 -> UTM. This ability to chain means conversion
-between almost any two CRSs is possible as long as they have a common linkage.
+between almost any two CRSs is possible as long as they have a common link.
 
 .. code-block:: php
 
@@ -29,7 +29,7 @@ between almost any two CRSs is possible as long as they have a common linkage.
         new Metre(69741),
         Projected::fromSRID(Projected::EPSG_OSGB_1936_BRITISH_NATIONAL_GRID)
     );
-    $toCRS = Projected::fromSRID(Projected::EPSG_WGS_84_UTM_GRID_SYSTEM_NORTHERN_HEMISPHERE);
+    $toCRS = Projected::fromSRID(Projected::EPSG_WGS_84_UTM_ZONE_31N);
     $to = $from->convert($toCRS);
 
 .. note::
@@ -63,6 +63,45 @@ to ``true``.
 
     In practice this should not affect you as a ``VerticalPoint`` will normally be used as part of a ``CompoundPoint``.
 
+Universal Transverse Mercator (UTM)
+-----------------------------------
+PHPCoord has 3 different ways of handling UTM references (:ref:`see here for details<utm_points>`).
+
+For conversions that *do not* involve a ``UTMPoint``, use the ``->convert()`` method as described above.
+
+For conversions from a ``GeographicPoint`` to a ``UTMPoint``, call the ``->asUTMPoint()`` method.
+
+.. code-block:: php
+
+    $from = GeographicPoint::create(
+        new Degree(43.642567),
+        new Degree(-79.387139),
+        null,
+        Geographic2D::fromSRID(Geographic2D::EPSG_WGS_84)
+    );
+    $to = $from->asUTMPoint();
+
+.. note::
+    You cannot directly convert to a ``UTMPoint`` from a different kind of ``ProjectedPoint`` or a ``GeocentricPoint``,
+    you must convert to the relevant ``GeographicPoint`` first. This is because the projection parameters are calculated
+    dynamically at runtime and are not available to take part in chain creation.
+
+For conversions from a ``UTMPoint`` back to the associated ``GeographicPoint``, call the ``->asGeographicPoint()`` method.
+
+.. code-block:: php
+
+    $from = new UTMPoint(
+        new Metre(630084),
+        new Metre(4833439),
+        17,
+        UTMPoint::HEMISPHERE_NORTH,
+        Geographic2D::fromSRID(Geographic2D::EPSG_WGS_84)
+    );
+    $to = $from->asGeographicPoint();
+
+The ``->convert()`` method *is* present on ``UTMPoint``\s and can be used as normal to convert to any desired CRS
+(including the base CRS).
+
 .. rubric:: Footnotes
 
-.. [#f1] There are over 36 million possible combinations of source and target CRS. They have not all been tested...
+.. [#f1] There are over 36 million possible combinations of source and target CRS. They haven't *all* been tested...

docs/coordinate_conversions_hard.rst

@@ -6,7 +6,7 @@ They are listed in detail on the following pages.
 
 .. tip::
     The first parameter of every method is always a ``CoordinateReferenceSystem`` object representing the target
-    CRS. For guidance on remaining parameters, please see a textbook, explaining those is far outside the
+    CRS. For guidance on remaining parameters, please see a textbook as explaining them is far outside the
     scope of this documentation.
 
 .. toctree::

docs/coordinate_conversions_hard_compound.rst

@@ -13,18 +13,3 @@ Geographic2D with Height Offsets
         Angle $longitudeOffset,
         Length $geoidUndulation
     ); // returns a new GeographicPoint
-
-Vertical Offset and Slope
--------------------------
-
-.. code-block:: php
-
-    $point = CompoundPoint::create(...);
-    $newPoint = $point->verticalOffset(
-        Compound $to,
-        Angle $ordinate1OfEvaluationPoint,
-        Angle $ordinate2OfEvaluationPoint,
-        Length $verticalOffset,
-        Angle $inclinationInLatitude,
-        Angle $inclinationInLongitude
-    ); // returns a new CompoundPoint

docs/coordinate_conversions_hard_vertical.rst

@@ -21,3 +21,19 @@ Vertical Offset
         Vertical $to,
         Length $verticalOffset
     ); // returns a new VerticalPoint
+
+Vertical Offset and Slope
+-------------------------
+
+.. code-block:: php
+
+    $point = VerticalPoint::create(...);
+    $newPoint = $point->verticalOffsetAndSlope(
+        Vertical $to,
+        Angle $ordinate1OfEvaluationPoint,
+        Angle $ordinate2OfEvaluationPoint,
+        Length $verticalOffset,
+        Angle $inclinationInLatitude,
+        Angle $inclinationInLongitude,
+        GeographicPoint $horizontalPoint
+    ); // returns a new VerticalPoint