Skip to content

Commit

Permalink
Update GMT.jl doc links.
Browse files Browse the repository at this point in the history
  • Loading branch information
joa-quim committed Apr 28, 2024
1 parent 6bb6378 commit 7a9b878
Show file tree
Hide file tree
Showing 5 changed files with 36 additions and 32 deletions.
6 changes: 4 additions & 2 deletions doc/rst/source/tutorial/julia/intro.rst
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ Alternatively, you can build GMT from source by following the

See also the general information about `Julia <https://julialang.org/learning/getting-started/>`_
as well as the introduction to the Julia wrapper at
https://www.generic-mapping-tools.org/GMT.jl/dev/usage/ and the very recommendable
`Quick Learn <https://www.generic-mapping-tools.org/GMT.jl/dev/quick_learn/>`_. Complement with the instructions on how to
`Introduction <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/general/introduction/index.html#introduction>`_
and the very recommendable
`Quick Learn <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/general/quick_learn/index.html#quick_learn/>`_.
Complement with the instructions on how to
install `GMT.jl <https://github.com/GenericMappingTools/GMT.jl#install>`_
6 changes: 3 additions & 3 deletions doc/rst/source/tutorial/julia/session-1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Tutorial setup
--------------

#. GMT man pages, documentation, and gallery example scripts are available from the GMT.jl documentation web page
available from https://www.generic-mapping-tools.org/GMT.jl/dev/.
available from https://www.generic-mapping-tools.org/GMTjl_doc/.

#. We recommend you create a sub-directory called *tutorial*,
cd into that directory, and run the commands there to keep things tidy.
Expand Down Expand Up @@ -92,7 +92,7 @@ Laboratory Exercises
We will begin our adventure by making some simple plot axes and coastline basemaps. We will do this in order
to introduce the all-important common options **frame**, **proj**, and **region** and to familiarize ourselves
with a few selected GMT projections. The GMT modules we will utilize are :doc:`/basemap` and
`basemap <https://www.generic-mapping-tools.org/GMT.jl/dev/coast/>`_.
`basemap <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/coast/>`_.
Please consult their manual pages for reference.

Linear projection
Expand Down Expand Up @@ -165,7 +165,7 @@ projections offered by GMT; here we will only have time to focus on one such pro

**proj=:merc**

To make coastline maps we use `basemap <https://www.generic-mapping-tools.org/GMT.jl/dev/coast/>`_ which automatically
To make coastline maps we use `coast <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/coast/>`_ which automatically
will access the GMT coastline, river and border data base derived from the GSHHG database [See *Wessel and Smith*, 1996].
In addition to the common switches we may need to use some of several coast-specific options:

Expand Down
22 changes: 12 additions & 10 deletions doc/rst/source/tutorial/julia/session-2.rst
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,11 @@ colorbar Plot gray scale or color scale bar
text Plot text strings
======================== ====================================================================

Plotting lines and symbols, `plot <https://www.generic-mapping-tools.org/GMT.jl/dev/plot/>`_ is one of the most frequently
Plotting lines and symbols, `plot <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/plot>`_ is one of the most frequently
used modules in GMT. In addition to the common command line switches
it has numerous specific options, and expects different file formats
depending on what action has been selected. These circumstances make
`plot <https://www.generic-mapping-tools.org/GMT.jl/dev/plot/>`_ harder to master than most GMT tools. The table below
`plot <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/plot>`_ harder to master than most GMT tools. The table below
shows an abbreviated list of the options:

================================================================== ===================================================================
Expand Down Expand Up @@ -123,7 +123,8 @@ us are shown in the table below:
| **marker**\ ="y-dash" | vertical dash; *size* is length of dash |
+------------------------------------+-------------------------------------------------------------------------------------------+

The symbol option in `plot <https://www.generic-mapping-tools.org/GMT.jl/dev/plot/>`_. Lower case symbols (**a, c, d, g, h, i, n, s, t, x**)
The symbol option in `plot <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/plot>`_.
Lower case symbols (**a, c, d, g, h, i, n, s, t, x**)
will fit inside a circle of given diameter. Upper case symbols (**A, C, D, G, H, I, N, S, T, X**)
will have area equal to that of a circle of given diameter.

Expand Down Expand Up @@ -215,8 +216,8 @@ Exercises:
#. Try using a predefined pattern.

A common question is : "How can I plot symbols connected by a line
with plot?". The surprising answer is that we must call `plot <https://www.generic-mapping-tools.org/GMT.jl/dev/plot/>`_ twice.
While this sounds cumbersome there is a reason for this: Basically,
with plot?". The surprising answer is that we must call `plot <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/plot>`_
twice. While this sounds cumbersome there is a reason for this: Basically,
polygons need to be kept in memory since they may need to be clipped,
hence computer memory places a limit on how large polygons we may plot.
Symbols, on the other hand, can be plotted one at a time so there
Expand All @@ -240,7 +241,7 @@ instead of symbols over the line, as here.

Result of GMT Tutorial example 8

Our final `plot <https://www.generic-mapping-tools.org/GMT.jl/dev/plot/>`_ example involves a more complicated scenario in
Our final `plot <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/plot>`_ example involves a more complicated scenario in
which we want to plot the epicenters of several earthquakes over the background of a coastline basemap. We want the symbols
to have a size that reflects the magnitude of the earthquakes, and that their color should reflect the depth of the hypocenter.
The first few lines in the remote tut_quakes.ngdc looks like this:
Expand All @@ -255,7 +256,7 @@ The first few lines in the remote tut_quakes.ngdc looks like this:
Thus the file has three header records (including the blank line), but we are only interested in columns
5, 4, 6, and 7. In addition to extract those columns we must also scale the magnitudes into symbols sizes
in centimeters. Given their range it looks like multiplying the magnitude by 0.1 will work well for symbol
sizes in cm. Reformatting this file to comply with the `plot <https://www.generic-mapping-tools.org/GMT.jl/dev/plot/>`_
sizes in cm. Reformatting this file to comply with the `plot <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/plot>`_
input format can be done in a number of ways. Here, we simply use the common column selection option **incol**
and its :ref:`scaling/offset capabilities <-icols_full>`. To skip the first 3 header records and then select
the 5th, 4rd, 6th, and 7th column and scale the 7th column by 0.1, we would use
Expand Down Expand Up @@ -314,7 +315,7 @@ Plotting text strings
---------------------

In many situations we need to annotate plots or maps with text strings;
in GMT this is done using `text <https://www.generic-mapping-tools.org/GMT.jl/dev/text/>`_. Apart from the common
in GMT this is done using `text <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/text>`_. Apart from the common
switches, there are 8 options that are particularly useful.

===================================================================== ===================================================
Expand All @@ -330,7 +331,8 @@ Option Purpose
**pen**\ =\ *pen* Draw the outline of text box
===================================================================== ===================================================

The input data to `text <https://www.generic-mapping-tools.org/GMT.jl/dev/text/>`_ is expected to contain the following information:
The input data to `text <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/text>`_
is expected to contain the following information:

::

Expand Down Expand Up @@ -366,7 +368,7 @@ A chart of octal codes can be found in Appendix F in the GMT
Technical Reference. For accented European characters you must
set :term:`PS_CHAR_ENCODING` to ISOLatin1 in your :doc:`/gmt.conf` file.

We will demonstrate `text <https://www.generic-mapping-tools.org/GMT.jl/dev/text/>`_ with the following script:
We will demonstrate `text <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/text>`_ with the following script:

.. code-block:: julia
Expand Down
12 changes: 6 additions & 6 deletions doc/rst/source/tutorial/julia/session-3.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ We first use the GMT module :doc:`/grdinfo` to see what's in this file::
grdinfo(G)

The file contains bathymetry for the Bermuda region and has depth values from -5475 to -89 meters. We want to
make a contour map of this data; this is a job for `grdcontour <https://www.generic-mapping-tools.org/GMT.jl/dev/grdcontour/>`_.

As with previous plot commands we need to set up the map projection with **proj**. Here, however, we do not have
to specify the region since that is by default assumed to be the extent of the grid file. To generate any plot we
will in addition need to supply information about which contours to draw. Unfortunately,
`grdcontour <https://www.generic-mapping-tools.org/GMT.jl/dev/grdcontour/>`_ is a complicated module with too
`grdcontour <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/grdcontour>`_ is a complicated module with too
many options. We put a positive spin on this situation by touting its flexibility. Here are the most useful options:

+-----------------------------------------------------------------+----------------------------------------------------------------------+
Expand Down Expand Up @@ -201,9 +201,9 @@ Preprocessing

The :doc:`/surface` module assumes that the data have been preprocessed to eliminate aliasing,
hence we must ensure that this step is completed prior to gridding. GMT comes with three preprocessors, called
`blockmean <https://www.generic-mapping-tools.org/GMT.jl/dev/blockmean/>`_,
`blockmedian <https://www.generic-mapping-tools.org/GMT.jl/dev/blockmedian/>`_, and
`blockmode <https://www.generic-mapping-tools.org/GMT.jl/dev/blockmode/>`_. The first averages values inside the
`blockmean <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/blockmean>`_,
`blockmedian <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/blockmedian/>`_, and
`blockmode <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/blockmode/>`_. The first averages values inside the
grid-spacing boxes, the second returns median values, wile the latter returns modal values. As a rule of thumb,
we use means for most smooth data (such as potential fields) and medians (or modes) for rough, non-Gaussian data
(such as topography). In addition to the required **region** and **inc** switches, these preprocessors all take
Expand All @@ -223,7 +223,7 @@ The output data can now be used with surface::

G = surface(D, region=(245,255,20,30), inc="5m", verbose=true);

If you rerun `grdcontour <https://www.generic-mapping-tools.org/GMT.jl/dev/grdcontour/>`_ on the new grid file
If you rerun `grdcontour <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/grdcontour/>`_ on the new grid file
(try it!) you will notice a big difference compared to the grid made by :doc:`/nearneighbor`: since surface is a
global method it will evaluate the solution at all nodes, even if there are no data constraints. There are numerous
options available to us at this point:
Expand Down
22 changes: 11 additions & 11 deletions doc/rst/source/tutorial/julia/session-4.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,13 @@ CPTs can be created in any number of ways. GMT provides two mechanisms:

#. Create simple, linear color tables given a master color table
(several are built-in) and the desired *z*-values at color boundaries
(`makecpt <https://www.generic-mapping-tools.org/GMT.jl/dev/makecpt/>`_)
(`makecpt <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/makecpt/>`_)

#. Create color tables based on a master CPT color table and the histogram-equalized distribution of *z*-values
in a gridded data file (`grd2cpt <https://www.generic-mapping-tools.org/GMT.jl/dev/#GMT.grd2cpt>`_)
in a gridded data file (`grd2cpt <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/grd2cpt>`_)

One can also make these files manually. Here we will limit our discussion to
`makecpt <https://www.generic-mapping-tools.org/GMT.jl/dev/makecpt/>`_.
`makecpt <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/makecpt/>`_.
Its main argument is the name of the master color table (a list is
shown if you run the module with no arguments) and the equidistant
*z*-values to go with it. The main options are given below.
Expand All @@ -47,12 +47,12 @@ from -20 to 60, with color changes at every 10, try these two variants:
makecpt(cmap=:rainbow, range=(-20,60,10), write="disc.cpt")
makecpt(cmap=:rainbow, range=(-20,60,10), continuous=true, write="cont.cpt")

We can plot these color tables with `colorbar <https://www.generic-mapping-tools.org/GMT.jl/dev/colorbar/>`_;
We can plot these color tables with `colorbar <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/colorbar/>`_;
the options worth mentioning here are listed below. The placement of the color bar is particularly important
and we refer you to the :ref:`Plot embellishments <GMT_Embellishments>` section for all the details. In addition,
the **frame** option can be used to set the title and unit label (and optionally to set the annotation-, tick-,
and grid-line intervals for the color bars.). Note that the makecpt commands above are done in classic mode.
If you run `makecpt <https://www.generic-mapping-tools.org/GMT.jl/dev/makecpt/>`_ in modern mode then you usually
If you run `makecpt <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/makecpt/>`_ in modern mode then you usually
do not specify an output file via standard output since modern mode maintains what is known as the current CPT.
However, if you must explicitly name an output CPT then you will need to add the -H option for modern mode to
allow output to standard output.
Expand Down Expand Up @@ -90,7 +90,7 @@ Your plot should look like :ref:`our example 14 below <gmt_tut_14_jl>`

Exercises:

#. Redo the `makecpt <https://www.generic-mapping-tools.org/GMT.jl/dev/makecpt/>`_ exercise using the
#. Redo the `makecpt <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/makecpt/>`_ exercise using the
master table *hot* and redo the bar plot.

#. Try specifying **frame**\ =(annot=10, grid=5).
Expand Down Expand Up @@ -140,7 +140,7 @@ Here, we will extract a subset of the global 30" DEM called SRTM30+:
Using :doc:`/grdinfo` we find that the data ranges from about 1000m to
about 4300m so we need to make a CPT with that range.

Color images are made with `grdimage <https://www.generic-mapping-tools.org/GMT.jl/dev/grdimage/>`_
Color images are made with `grdimage <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/grdimage/>`_
which takes the usual common command options (by default the **region** is taken from the data set) and a CPT;
the main other options are:

Expand Down Expand Up @@ -173,7 +173,7 @@ Your plot should look like :ref:`our example 15 below <gmt_tut_15_jl>`
The plain color map lacks detail and fails to reveal the topographic complexity of this Rocky Mountain region.
What it needs is artificial illumination. We want to simulate shading by a sun source in the east, hence we
derive the required intensities from the gradients of the topography in the N90°E direction using
`grdgradient <https://www.generic-mapping-tools.org/GMT.jl/dev/grdgradient/>`_.
`grdgradient <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/grdgradient/>`_.
Other than the required input and output filenames, the available options are

+----------------------------------------------+-----------------------------------------------------------------------------+
Expand Down Expand Up @@ -239,7 +239,7 @@ Exercises:

#. Force a gray-shade image.

#. Rerun `grdgradient <https://www.generic-mapping-tools.org/GMT.jl/dev/grdgradient/>`_ with **norm**\ =1.
#. Rerun `grdgradient <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/grdgradient/>`_ with **norm**\ =1.

Multi-dimensional maps
----------------------
Expand Down Expand Up @@ -297,7 +297,7 @@ Perspective views
-----------------

Our final undertaking in this tutorial is to examine three-dimensional perspective views. The GMT module that
produces perspective views of gridded data files is `grdview <https://www.generic-mapping-tools.org/GMT.jl/dev/grdview/>`_.
produces perspective views of gridded data files is `grdview <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/grdview/>`_.
It can make two kinds of plots:

#. Mesh or wire-frame plot (with or without superimposed contours)
Expand Down Expand Up @@ -384,7 +384,7 @@ Exercises:

#. Choose another vantage point and scaling.

#. Redo `grdgradient <https://www.generic-mapping-tools.org/GMT.jl/dev/grdgradient/>`_ with another illumination
#. Redo `grdgradient <https://www.generic-mapping-tools.org/GMTjl_doc/documentation/module/grdgradient/>`_ with another illumination
direction and plot again.

#. Select a higher *dpi*, e.g., 200.

0 comments on commit 7a9b878

Please sign in to comment.