Doc updates from jidanni (#3858)

* Update nzmg.rst Here I am taking a guess at which grid this is referring to and thus trying to make it clearer. * Update transformation.rst Note: I have only mentioned that the +'s went away. Apparently the author is using +init files here, and showing only their contents. However even if the user placed the example snippets seen in the boxes into files in the current directory, there is no complete working example! I am saying that earlier in this book, the user was able to run the examples shown. But now if the user wishes to continue running them, he has to put the +'s back, or use some special syntax that you haven't shown yet in a complete working example! * Always use the cleanest examples. Move repetitive default into text explanation. P.S., maybe one day even consider changing the default +ellps=GRS80 to +ellps=WGS84... but no big deal... * Update docs/source/apps/proj.rst * Update x_0.rst These are meters and one cannot just use e.g., +units to change it. * Remove redundant optional default parameters! We get the exact same answer without the clutter that doesn't make things any more clearer. * 50 U.S. isn't grammatical P.S., perhaps add a reference to where this projection came from. * Remove parameter that is default anyway Make example less cluttered. * Update cart.rst Simplify via defaults. * Can remove default parameter. Shorten string by removing redundancies. * Update som.rst showing relation of the two lines Mentioning how the two lines are related. * Update rhealpix.rst Got rid of - default -f setting Eliminated ellipse emphasis and just used the default. * Update geoc.rst Defaults shown clear as day at the bottom of the page already. * Update topocentric.rst Wipe off items that aren't the focus of the issue and don't affect outcome here. * Update unitconvert.rst Use and explain defaults. One day this page should mention what the default time etc. units are too. * Update set.rst Simplify by removing default parameters. * Update push.rst Eliminate default reuse, getting same calculation. * Update xyzgridshift.rst Don't repeat defaults. * Update vertoffset.rst GRS80 already implied and documented. * Update hgridshift.rst Reduce chance of too wide example going off the screen! * Update geogoffset.rst Add '+' to match rest of book. * Update differences.rst Add actual EOF notation. * Update helmert.rst Reduce horizontal scrolling, at least on desktop. Also one day maybe add '+' before each... or maybe not. * Update defmodel.rst Example causes scrolling horizontally, even on desktop. * Update bertin1953.rst Remove src. * Update cass.rst - Less horizontal scrolling, which was seen even on desktop. - Zapped default meter parameter. * Update s2.rst Clean off testing residue. Perhaps one day also hyperlink "Quadrilateralized Spherical Cube" page. * Update tmerc.rst Trimming defaults reduces horizontal scrolling. * Update y_0.rst These are meters and one cannot just use e.g., +units to change it. * Update unitconvert.rst Mention defaults. I only listed the ones I know. The rest I didn't list. --------- Co-authored-by: 積丹尼 Dan Jacobson <[email protected]>
OSGeo · Sep 3, 2023 · 7b3b638 · 7b3b638
1 parent e5169f9
commit 7b3b638
Show file tree

Hide file tree

Showing 28 changed files with 69 additions and 56 deletions.
diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst
@@ -49,8 +49,6 @@ file referenced by the {object_reference} must contain a valid
 
     .. versionadded:: 8.0.0
 
-
-
 Description
 ***********
 

diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst
@@ -206,6 +206,7 @@ The following script
     EOF
 
 will perform UTM zone 12 forward projection.
+The default +ellps=GRS80 is used as no +ellps was specified.
 The geographic values of this example are equivalent
 and meant as examples of various forms of DMS input. The x-y output
 data will appear as three lines of::

diff --git a/docs/source/operations/conversions/cart.rst b/docs/source/operations/conversions/cart.rst
@@ -27,9 +27,9 @@ longitude=90, latitude=0 and the third axis (Z) points to the North pole.
 Usage
 ################################################################################
 
-Convert geodetic coordinates to GRS80 cartesian coordinates::
+Convert geodetic coordinates to cartesian (uses default +ellps=GRS80)::
 
-    echo 17.7562015132 45.3935192042 133.12 2017.8 | cct +proj=cart +ellps=GRS80
+    echo 17.7562015132 45.3935192042 133.12 2017.8 | cct +proj=cart
     4272922.1553   1368283.0597  4518261.3501     2017.8000
 
 Parameters

diff --git a/docs/source/operations/conversions/geoc.rst b/docs/source/operations/conversions/geoc.rst
@@ -63,11 +63,11 @@ Usage
 
 Converting from geodetic latitude to geocentric latitude::
 
-    +proj=geoc +ellps=GRS80
+    +proj=geoc
 
 Converting from geocentric latitude to geodetic latitude::
 
-    +proj=pipeline +step +proj=geoc +inv +ellps=GRS80
+    +proj=pipeline +step +proj=geoc +inv
 
 Parameters
 ################################################################################

diff --git a/docs/source/operations/conversions/push.rst b/docs/source/operations/conversions/push.rst
@@ -46,10 +46,10 @@ operation but the vertical part is kept exactly as the input was.
 
    $ echo 12 56 12.3 2020 | cct +proj=pipeline  \
    +step +proj=push +v_3                        \
-   +step +proj=cart +ellps=GRS80                \
+   +step +proj=cart                             \
    +step +proj=helmert +x=3000 +y=1000 +z=2000  \
-   +step +proj=cart +ellps=GRS80 +inv           \
-   +step +proj=pop +v_3                         \
+   +step +proj=cart +inv                        \
+   +step +proj=pop +v_3
 
     12.0056753463   55.9866540552       12.3000     2000.0000
 
@@ -58,9 +58,9 @@ Note that the third coordinate component in the output is the same as the input.
 The same transformation without the push and pop operations would look like this::
 
    $ echo 12 56 12.3 2020 | cct +proj=pipeline  \
-   +step +proj=cart +ellps=GRS80                \
+   +step +proj=cart                             \
    +step +proj=helmert +x=3000 +y=1000 +z=2000  \
-   +step +proj=cart +ellps=GRS80 +inv           \
+   +step +proj=cart +inv
 
          12.0057        55.9867     3427.7404     2000.0000
 

diff --git a/docs/source/operations/conversions/set.rst b/docs/source/operations/conversions/set.rst
@@ -47,7 +47,7 @@ the reverse direction.
         +step +proj=vgridshift +grids=nlgeo2018.gtx \
         +step +proj=push +v_3 \
         +step +proj=set +v_3=43 \
-        +step +proj=cart +ellps=GRS80 \
+        +step +proj=cart \
         +step +proj=helmert +x=-565.7346 +y=-50.4058 +z=-465.2895 +rx=-0.395023 +ry=0.330776 +rz=-1.876073 +s=-4.07242 +convention=coordinate_frame +exact \
         +step +proj=cart +inv +ellps=bessel \
         +step +proj=hgridshift +inv +grids=rdcorr2018.gsb,null \

diff --git a/docs/source/operations/conversions/topocentric.rst b/docs/source/operations/conversions/topocentric.rst
@@ -57,16 +57,16 @@ Convert geocentric coordinates to topocentric coordinates, with the topocentric
 origin specified in geocentric coordinates::
 
     echo 3771793.968 140253.342 5124304.349 2020 | \
-        cct -d 3 +proj=topocentric +ellps=WGS84 +X_0=3652755.3058 +Y_0=319574.6799 +Z_0=5201547.3536
+        cct -d 3 +proj=topocentric +X_0=3652755.3058 +Y_0=319574.6799 +Z_0=5201547.3536
 
     -189013.869    -128642.040     -4220.171     2020.0000
 
 Convert geographic coordinates to topocentric coordinates, with the topocentric
 origin specified in geographic coordinates::
 
     echo 2.12955 53.80939444 73 2020 | cct -d 3 +proj=pipeline \
-        +step +proj=cart +ellps=WGS84 \
-        +step +proj=topocentric +ellps=WGS84 +lon_0=5 +lat_0=55 +h_0=200
+        +step +proj=cart \
+        +step +proj=topocentric +lon_0=5 +lat_0=55 +h_0=200
 
     -189013.869    -128642.040     -4220.171     2020.0000
 

diff --git a/docs/source/operations/conversions/unitconvert.rst b/docs/source/operations/conversions/unitconvert.rst
@@ -26,16 +26,16 @@ of that.
 Many North American systems are defined with coordinates in feet. For example
 in Vermont::
 
-    +proj=pipeline
-    +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k_0=0.999964286 +x_0=500000.00001016 +y_0=0
-    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+    +proj=pipeline \
+    +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k_0=0.999964286 +x_0=500000.00001016 \
+    +step +proj=unitconvert +xy_out=us-ft
 
 Often when working with GNSS data the timestamps are presented in GPS-weeks,
 but when the data transformed with the `helmert` operation timestamps are
 expected to be in units of decimalyears. This can be fixed with `unitconvert`::
 
-    +proj=pipeline
-    +step +proj=unitconvert +t_in=gps_week +t_out=decimalyear
+    +proj=pipeline \
+    +step +proj=unitconvert +t_in=gps_week +t_out=decimalyear \
     +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ...
 
 Parameters
@@ -44,16 +44,16 @@ Parameters
 .. option:: +xy_in=<unit> or <conversion_factor>
 
     Horizontal input units. See :ref:`distance_units` and :ref:`angular_units`
-    for a list of available units. `<conversion_factor>` is the conversion factor
+    for a list of available units. Default: meter. `<conversion_factor>` is the conversion factor
     from the input unit to metre for linear units, or to radian for angular
-    units.
+    units. Default if not given: meters.
 
 .. option:: +xy_out=<unit> or <conversion_factor>
 
     Horizontal output units. See :ref:`distance_units` and :ref:`angular_units`
-    for a list of available units. `<conversion_factor>` is the conversion factor
+    for a list of available units. Deault: meter. `<conversion_factor>` is the conversion factor
     from the output unit to metre for linear units, or to radian for angular
-    units.
+    units. Default if not given: meters.
 
 .. option:: +z_in=<unit> or <conversion_factor>
 

diff --git a/docs/source/operations/options/x_0.rst b/docs/source/operations/options/x_0.rst
@@ -1,5 +1,5 @@
 .. option:: +x_0=<value>
 
-    False easting.
+    False easting, in meters.
 
     *Defaults to 0.0.*
diff --git a/docs/source/operations/projections/bertin1953.rst b/docs/source/operations/projections/bertin1953.rst
@@ -44,7 +44,7 @@ Usage
 The Bertin 1953 projection has no special options. Its rotation parameters
 are fixed. Here is an example of a forward projection with scale 1::
 
-    $ echo 122 47 | src/proj +proj=bertin1953 +R=1
+    $ echo 122 47 | proj +proj=bertin1953 +R=1
     0.72    0.73
 
 Parameters

diff --git a/docs/source/operations/projections/cass.rst b/docs/source/operations/projections/cass.rst
@@ -40,12 +40,18 @@ The Cassini-Soldner was also used for the detailed mapping of many German states
 
 Example using EPSG 30200 (Trinidad 1903, units in clarke's links)::
 
-    $ echo 0.17453293 -1.08210414 | proj +proj=cass +lat_0=10.44166666666667 +lon_0=-61.33333333333334 +x_0=86501.46392051999 +y_0=65379.0134283 +a=6378293.645208759 +b=6356617.987679838 +to_meter=0.201166195164
+    $ echo 0.17453293 -1.08210414 | proj +proj=cass \
+      +lat_0=10.44166666666667 +lon_0=-61.33333333333334 \
+      +x_0=86501.46392051999 +y_0=65379.0134283 \
+      +a=6378293.645208759 +b=6356617.987679838 \
+      +to_meter=0.201166195164
     66644.94    82536.22
 
 Example using EPSG 3068 (Soldner Berlin)::
 
-    $ echo 13.5 52.4 | proj +proj=cass +lat_0=52.41864827777778 +lon_0=13.62720366666667 +x_0=40000 +y_0=10000 +ellps=bessel +units=m
+    $ echo 13.5 52.4 | proj +proj=cass \
+      +lat_0=52.41864827777778 +lon_0=13.62720366666667 \
+      +x_0=40000 +y_0=10000 +ellps=bessel
     31343.05    7932.76
 
 Options

diff --git a/docs/source/operations/projections/gall.rst b/docs/source/operations/projections/gall.rst
@@ -49,12 +49,12 @@ Unlike the Mercator, the Gall shows the poles as lines running across the top an
 
 Example using Gall Stereographic  ::
 
-    $ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +units=m
+    $ echo 9 51 | proj +proj=gall
     708432.90   5193386.36
 
 Example using Gall Stereographic (Central meridian 90°W) ::
 
-    $ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +units=m
+    $ echo 9 51 | proj +proj=gall +lon_0=90w
     7792761.91  5193386.36
 
 Parameters

diff --git a/docs/source/operations/projections/gs50.rst b/docs/source/operations/projections/gs50.rst
@@ -1,7 +1,7 @@
 .. _gs50:
 
 ********************************************************************************
-Modified Stereographic of 50 U.S.
+Modified Stereographic of the 50 U.S. states
 ********************************************************************************
 
 +---------------------+----------------------------------------------------------+
@@ -24,7 +24,7 @@ Modified Stereographic of 50 U.S.
 .. figure:: ./images/gs50.png
    :width: 500 px
    :align: center
-   :alt:   Modified Stereographic of 50 U.S.
+   :alt:   Modified Stereographic of the 50 U.S. states
 
    proj-string: ``+proj=gs50``
 

diff --git a/docs/source/operations/projections/healpix.rst b/docs/source/operations/projections/healpix.rst
@@ -40,7 +40,7 @@ Usage
 
 To run a forward HEALPix projection on a unit sphere model, use the following command::
 
-    proj +proj=healpix +lon_0=0 +a=1 -E <<EOF
+    proj +proj=healpix +a=1 -E <<EOF
     0 0
     EOF
     # output

diff --git a/docs/source/operations/projections/lsat.rst b/docs/source/operations/projections/lsat.rst
@@ -34,7 +34,7 @@ satellites like those of the Landsat program.
    :align: center
    :alt:   Space oblique for LANDSAT
 
-   proj-string: ``+proj=lsat +ellps=GRS80 +lat_1=-60 +lat_2=60 +lsat=2 +path=2``
+   proj-string: ``+proj=lsat +lat_1=-60 +lat_2=60 +lsat=2 +path=2``
 
 Parameters
 ################################################################################

diff --git a/docs/source/operations/projections/nzmg.rst b/docs/source/operations/projections/nzmg.rst
@@ -1,13 +1,13 @@
 .. _nzmg:
 
 ********************************************************************************
-New Zealand Map Grid
+New Zealand Map Grid (EPSG:27200)
 ********************************************************************************
 
 .. figure:: ./images/nzmg.png
    :width: 500 px
    :align: center
-   :alt:   New Zealand Map Grid
+   :alt:   New Zealand Map Grid (EPSG:27200)
 
    proj-string: ``+proj=nzmg``
 

diff --git a/docs/source/operations/projections/rhealpix.rst b/docs/source/operations/projections/rhealpix.rst
@@ -34,10 +34,10 @@ Environment (SCENZGrid).
 Usage
 ###############################################################################
 
-To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following
+To run a rHEALPix projection (on the default GRS80 ellipsoidal model,) use the following
 command::
 
-    proj +proj=rhealpix -f '%.2f' +ellps=WGS84 +south_square=0 +north_square=2  -E << EOF
+    proj +proj=rhealpix +north_square=2 -E << EOF
     > 55 12
     > EOF
     55 12   6115727.86  1553840.13

diff --git a/docs/source/operations/projections/s2.rst b/docs/source/operations/projections/s2.rst
@@ -82,7 +82,7 @@ Usage
 
 The following example uses S2 on the right face::
 
-    echo 90 0 | ../bin/proj +proj=s2 +lat_0=0 +lon_0=90 +ellps=WGS84 +UVtoST=linear 
+    echo 90 0 | proj +proj=s2 +lat_0=0 +lon_0=90 +ellps=WGS84 +UVtoST=linear 
 
     0.5 0.5
 

diff --git a/docs/source/operations/projections/som.rst b/docs/source/operations/projections/som.rst
@@ -40,7 +40,7 @@ satellite data to be represented accurately as a rectangular array.
 
    proj-string: ``+proj=som +inc_angle=98.303820000243860022 +ps_rev=0.06866666666666667 +asc_lon=64.412896137498847793``
 
-   proj-string: ``+proj=som +inc_angle=1.7157253262878522r +ps_rev=0.06866666666666667 +asc_lon=1.1242171183417042r``
+   (gives same results as: ``+proj=som +inc_angle=1.7157253262878522r +ps_rev=0.06866666666666667 +asc_lon=1.1242171183417042r``)
 
 Parameters
 ################################################################################

diff --git a/docs/source/operations/projections/tmerc.rst b/docs/source/operations/projections/tmerc.rst
@@ -64,12 +64,12 @@ The following table gives special cases of the Transverse Mercator projection.
 
 Example using Gauss-Kruger on Germany area (aka EPSG:31467) ::
 
-    $ echo 9 51 | proj +proj=tmerc +lat_0=0 +lon_0=9 +k_0=1 +x_0=3500000 +y_0=0 +ellps=bessel +units=m
+    $ echo 9 51 | proj +proj=tmerc +lon_0=9 +x_0=3500000 +ellps=bessel
     3500000.00  5651505.56
 
 Example using Gauss Boaga on Italy area (EPSG:3004) ::
 
-    $ echo 15 42 | proj +proj=tmerc +lat_0=0 +lon_0=15 +k_0=0.9996 +x_0=2520000 +y_0=0 +ellps=intl +units=m
+    $ echo 15 42 | proj +proj=tmerc +lon_0=15 +k_0=0.9996 +x_0=2520000 +ellps=intl
     2520000.00  4649858.60
 
 Parameters

diff --git a/docs/source/operations/transformations/defmodel.rst b/docs/source/operations/transformations/defmodel.rst
@@ -62,4 +62,5 @@ Transforming a point with the LINZ NZGD2000 deformation model:
 
 ::
 
-    echo 166.7133850980 -44.5105886020 293.3700 2007.689 | cct +proj=defmodel +model=nzgd2000-20180701.json
+    echo 166.7133850980 -44.5105886020 293.3700 2007.689 | 
+         cct +proj=defmodel +model=nzgd2000-20180701.json
diff --git a/docs/source/operations/transformations/geogoffset.rst b/docs/source/operations/transformations/geogoffset.rst
@@ -39,15 +39,15 @@ Examples
 
 Geographic offset from the old Greek geographic 2D CRS to the newer GGRS87 CRS::
 
-    proj=geogoffset dlon=0.28 dlat=-5.86
+    +proj=geogoffset +dlon=0.28 +dlat=-5.86
 
 Conversion from Tokyo + JSLD69 height to WGS 84::
 
-    proj=geogoffset dlon=-13.97 dlat=7.94 dh=26.9
+    +proj=geogoffset +dlon=-13.97 +dlat=7.94 +dh=26.9
 
 Conversion from Baltic 1977 height to Black Sea height::
 
-    proj=geogoffset dh=0.4
+    +proj=geogoffset +dh=0.4
 
 
 Parameters

diff --git a/docs/source/operations/transformations/helmert.rst b/docs/source/operations/transformations/helmert.rst
@@ -50,7 +50,8 @@ Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert:
 
 ::
 
-    proj=helmert convention=coordinate_frame x=-9597.3572 y=.6112 s=0.304794780637 theta=-1.244048
+    proj=helmert convention=coordinate_frame x=-9597.3572 y=.6112 \
+        s=0.304794780637 theta=-1.244048
 
 Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters:
 

diff --git a/docs/source/operations/transformations/hgridshift.rst b/docs/source/operations/transformations/hgridshift.rst
@@ -63,7 +63,9 @@ the coordinate is part of the coordinate tuple.
 Suppose we want to model the deformation of the 2008 earthquake in Iceland in
 a transformation of data from 2005 to 2009::
 
-    echo 63.992 -21.014 10.0 2005.0 | cct +proj=hgridshift +grids=iceland2008.gsb +t_epoch=2008.4071 +t_final=2009.0
+    echo 63.992 -21.014 10.0 2005.0 | 
+        cct +proj=hgridshift +grids=iceland2008.gsb \
+        +t_epoch=2008.4071 +t_final=2009.0
     63.9920021 -21.0140013 10.0 2005.0
 
 .. note::

diff --git a/docs/source/operations/transformations/vertoffset.rst b/docs/source/operations/transformations/vertoffset.rst
@@ -30,7 +30,7 @@ Examples
 Vertical offset from LN02 height to EVRF2000 height with horizontal coordinates in ETRS89::
 
     +proj=vertoffset +lat_0=46.9166666666666666 +lon_0=8.183333333333334 \
-        +dh=-0.245 +slope_lat=-0.210 +slope_lon=-0.032 +ellps=GRS80
+        +dh=-0.245 +slope_lat=-0.210 +slope_lon=-0.032
 
 Parameters
 ################################################################################

diff --git a/docs/source/operations/transformations/xyzgridshift.rst b/docs/source/operations/transformations/xyzgridshift.rst
@@ -45,8 +45,8 @@ NTF to RGF93 transformation using :file:`gr3df97a.tif` grid
     +proj=pipeline
         +step +proj=push +v_3
         +step +proj=cart +ellps=clrk80ign
-        +step +proj=xyzgridshift +grids=gr3df97a.tif +grid_ref=output_crs +ellps=GRS80
-        +step +proj=cart +ellps=GRS80 +inv
+        +step +proj=xyzgridshift +grids=gr3df97a.tif +grid_ref=output_crs
+        +step +proj=cart +inv
         +step +proj=pop +v_3
 
 Parameters

diff --git a/docs/source/usage/differences.rst b/docs/source/usage/differences.rst
@@ -37,19 +37,21 @@ PROJ 5, this was handled incorrectly when a custom central meridian was set with
 :option:`+lon_0`. This caused a change in sign on the resulting easting as seen
 below::
 
-    $ proj +proj=merc +lon_0=110
+    $ proj +proj=merc +lon_0=110 <<EOF
     -70 0
-    -20037508.34    0.00
     290 0
+    EOF
     20037508.34     0.00
+    -20037508.34    0.00
 
 From PROJ 5 on onwards, the same input now results in same coordinates, as seen
 from the example below where PROJ 5 is used::
 
-    $ proj +proj=merc +lon_0=110
+    $ proj +proj=merc +lon_0=110 <<EOF
     -70 0
-    -20037508.34    0.00
     290 0
+    EOF
+    -20037508.34     0.00
     -20037508.34    0.00
 
 The change is made on the basis that :math:`\lambda=290^{\circ}` is a full

diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst
@@ -70,7 +70,9 @@ solutions for a wide spectrum of geodetic tasks.
 
 As a first example, let us take a look at the iconic
 *geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in
-the introduction). In PROJ it can be implemented as
+the introduction). 
+(Note, for the rest of this book the "+"s are removed from the examples.)
+In PROJ it can be implemented as
 
 ::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -49,8 +49,6 @@ file referenced by the {object_reference} must contain a valid

		.. versionadded:: 8.0.0



		Description
		***********

Expand Down
-Original file line number
+Diff line change
@@ Expand Up / @@ -82,7 +82,7 @@ Usage @@
     The following example uses S2 on the right face::
-        echo 90 0 | ../bin/proj +proj=s2 +lat_0=0 +lon_0=90 +ellps=WGS84 +UVtoST=linear
+        echo 90 0 | proj +proj=s2 +lat_0=0 +lon_0=90 +ellps=WGS84 +UVtoST=linear
 .5 0.5
@@ Expand Down @@