Merge pull request #1508 from pkturner/grid-scale-factor-lite

Calculate grid scale factor compatibly

doc/manual/pages/georeferencing.md

@@ -4,7 +4,7 @@ authors:
   - Peter Hoban
   - Thomas Schoeps
 keywords: Georeferencing
-edited: 25 February 2013
+edited: 25 January 2020
 ---
 
  - [Introduction](#introduction)
@@ -18,32 +18,35 @@ edited: 25 February 2013
 
 Georeferencing of a map is the best way for aligning templates (such as base maps or aerial imagery) and GPS tracks. In short, to georeference a map means to establish a known relationship between the paper coordinates of the map and the coordinates of a geographic coordinate reference system. This way, data which is known in a geographic coordinate reference system (such as GPS coordinates) can be transformed to map coordinates and thus displayed on the map, and vice versa the map can be transformed to geographic coordinates and e.g. be displayed on a world map. More information is available on [Wikipedia](https://en.wikipedia.org/wiki/Georeferencing).
 
-Georeferencing properties are set in a dialog which is available from the menu **Map > Georeferencing...**. The dialog is divided in three sections: Map coordinate reference system, Reference point and Map north.
+Georeferencing properties are set in a dialog which is available from the menu **Map > Georeferencing...**. The dialog is divided in four sections: Map coordinate reference system, Reference point, Map north, and Scale compensation.
 
 ![Georeferencing dialog](images/georeferencing.png)
 
 #### Map coordinate reference system
 
-This section defines in which kind of projected coordinates (real-world metric cartesian coordinates) the reference point relating map and geographic coordinates is defined. Projected coordinates are transformed to map coordinates by scaling and rotation. You should thus choose the coordinate reference system in which you know the real-world coordinates of a point on the map. In case you just want to load some GPS tracks, you can also just safely use UTM, which is widely used world-wide. Other choices are:
+This section specifies the projection which relates latitude/longitude (in degrees) to flat coordinates (in real-world meters). The coordinate reference system is one important step in relating coordinates on the round Earth to coordinates on the flat paper map (in actual map millimeters). The additional steps are scaling, rotation, and adding an offset.
+
+In case you just want to load some GPS tracks, you can safely use UTM, which is widely used world-wide. Other choices are:
 
  - **Gauss-Krüger**: this is similar to UTM and widely used in Germany, but is being superseded by UTM.
  - **From Proj.4 specification**: projections are internally handled by the [PROJ.4 Cartographic Projections library](https://proj4.org/), so coordinate reference systems can also be given in its internal specification format. Examples may be found at [http://www.remotesensing.org/geotiff/proj_list/ (Internet Archive)](https://web.archive.org/web/20160802172057/http://www.remotesensing.org/geotiff/proj_list/) and [http://spatialreference.org/](http://spatialreference.org/). When selecting this option, the specification field will be pre-filled with the specification of the previously selected coordinate reference system.
+ - **EPSG**: for any coordinate reference system in this extensive worldwide registry.
  - **Local**: this enables you to use local projected coordinates without a mapping to global geographic coordinates.
 
 Depending on the selected coordinate reference system more settings may show up. For example, for UTM the zone number must be given in addition.
 
 #### Reference point
 
-Settings in this section define the reference point, which is the point for which coordinates in all of the involved coordinate systems are known. Thus it acts as the anchor between the different coordinate reference systems.
+Settings in this section define the reference point, which is a point for which coordinates in all of the involved coordinate systems are known. It acts as the anchor between the different coordinate reference systems.
 
 In case the georeferencing dialog is triggered by loading a georeferenced template in a map which is not georeferenced yet, these settings are probably already pre-filled with sensible values (assuming that no other map objects exist yet), so they do not need to be changed in this case.
 
-The **Map coordinates** field shows the map paper coordinates of this point. To change them, use the **Select...** button. The georeferencing dialog will then be hidden until you select a point on the map (left mouse click) or cancel the selection process (another mouse button). Changing the reference point on the map will not affect the other sections.
+The **Map coordinates** field shows the map paper coordinates of this point. To change them, use the **Pick on map** button. The georeferencing dialog will then be hidden until you select a point on the map (left mouse click) or cancel the selection process (another mouse button). Changing the reference point on the map will not affect the other sections.
 
 The next set of coordinates gives the reference point east-west and north-south position in **projected coordinates**, for example in UTM or Gauss-Krüger coordinates. Unless working with local coordinates, changing easting or northing will update the geographic coordinates. Easting and northing are given in meters.
 
 The third set of coordinates gives the reference point position in **geographic coordinates**. Note that after the selection of a coordinate reference system other than local, projected and geographic coordinates are linked together, so changing one will also change the other. Geographic coordinates specify a location on the planet's surface by
-latitude and longitude. Latitude and longitude are measured in decimal degrees. Also note that according to convention, the first coordinate here is the latitude (northing) and the second the longitude (easting).
+latitude and longitude. Latitude and longitude are measured in decimal degrees. Also note that according to convention, the first coordinate here is the latitude and the second the longitude.
 
  - The **latitude** specifies the north-south position of the reference point as an angle relative to the equatorial plane. Negative values indicate the southern hemisphere.
  - The **longitude** specifies the east-west position as angle relative to a prime meridian. Negative values indicate a position west of the prime meridian.
@@ -59,11 +62,18 @@ The last option in this section determines which coordinates will be recalculate
 
 In the **Declination** field the angle between true north and magnetic north at the position of the map has to be entered to make magnetic north be at the top. This can be looked up from an online accessible model as soon as the reference point geographic coordinates are entered, however it should be checked with a precise compass if accuracy is required.
 
-**Grivation** determines the rotation which moves the magnetic north to the top of the map. Grivation is composed of magnetic declination (the angle between true north and magnetic north) and grid convergence (the angle between true north and grid north).
+**Grivation** determines the rotation which turns the projected grid so that magnetic north is at the top of the map. Grivation is composed of magnetic declination (the angle between true north and magnetic north) and grid convergence (the angle between true north and grid north).
+
+
+#### Scale compensation
+
+**Auxiliary scale factor** may be set to compensate when distances on the ground differ from distances on the Earth model, such as occurs when the terrain is at high altitude. It is the ratio of model distance to ground distance. The default factor of 1.0 has no effect. Beside that, Mapper automatically calculates the grid scale factor, which accounts for the difference between projected distance and model distance. Mapper puts this together with the auxiliary scale factor, to form the **combined scale factor**.
 
 
 #### Related functions
 
+The default, basic Georeferencing dialog is lacking a few of the above-described options that are not generally needed. The settings (menu File > Settings > Georeferencing) can enable these advanced features.
+
 The (mouse) cursor position of the map editor can be displayed in map coordinates, projected coordinates or geographic coordinates (decimal or as degrees/minutes/seconds, DMS). The coordinates of the cursor on the map sheet are discussed [here](view_menu.md#coorddisplay).
 
 #### Further reading

examples/complete map.omap

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <map xmlns="http://openorienteering.org/apps/mapper/xml/v2" version="9">
 <notes></notes>
-<georeferencing scale="4000" declination="2.35" grivation="0.37"><ref_point x="10" y="35"/><projected_crs id="UTM"><spec language="PROJ.4">+proj=utm +datum=WGS84 +zone=32</spec><parameter>32 N</parameter><ref_point x="696686.398978" y="5347699.134904"/></projected_crs><geographic_crs id="Geographic coordinates"><spec language="PROJ.4">+proj=latlong +datum=WGS84</spec><ref_point_deg lat="48.25195669" lon="11.64973926"/></geographic_crs></georeferencing>
+<georeferencing scale="4000" auxiliary_scale_factor="0.999925" declination="2.35" grivation="0.37"><ref_point x="10" y="35"/><projected_crs id="UTM"><spec language="PROJ.4">+proj=utm +datum=WGS84 +zone=32</spec><parameter>32 N</parameter><ref_point x="696686.398978" y="5347699.134904"/></projected_crs><geographic_crs id="Geographic coordinates"><spec language="PROJ.4">+proj=latlong +datum=WGS84</spec><ref_point_deg lat="48.25195669" lon="11.64973926"/></geographic_crs></georeferencing>
 <colors count="39">
 <color priority="0" name="Purple" c="0.2" m="1" y="0" k="0" opacity="1"><spotcolors><namedcolor>PURPLE</namedcolor></spotcolors><cmyk method="custom"/><rgb method="cmyk" r="0.8" g="0" b="1"/></color>
 <color priority="1" name="Purple 50%" c="0.1" m="0.5" y="0" k="0" opacity="1"><spotcolors><component factor="0.5" spotcolor="0"/></spotcolors><cmyk method="spotcolor"/><rgb method="spotcolor" r="0.9" g="0.5" b="1"/></color>

examples/src/complete map.xmap

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <map xmlns="http://openorienteering.org/apps/mapper/xml/v2" version="9">
     <notes></notes>
-    <georeferencing scale="4000" declination="2.35" grivation="0.37">
+    <georeferencing scale="4000" auxiliary_scale_factor="0.999925" declination="2.35" grivation="0.37">
         <ref_point x="10" y="35"/>
         <projected_crs id="UTM">
             <spec language="PROJ.4">+proj=utm +datum=WGS84 +zone=32</spec>

src/CMakeLists.txt

@@ -113,6 +113,7 @@ set(Mapper_Common_SRCS
   gui/map/new_map_dialog.cpp
   gui/map/map_dialog_rotate.cpp
   gui/map/map_dialog_scale.cpp
+  gui/map/map_dialog_stretch.cpp
   gui/map/map_editor.cpp
   gui/map/map_editor_activity.cpp
   gui/map/map_find_feature.cpp