From 6b247775e6669263d5f9998427f2c88266e9ba0a Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 29 Apr 2026 20:00:12 +0800 Subject: [PATCH 1/4] Improve the intro tutorial for figure elements --- examples/intro/03_figure_element.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/examples/intro/03_figure_element.py b/examples/intro/03_figure_element.py index 61d552c4243..ac99b51eab5 100644 --- a/examples/intro/03_figure_element.py +++ b/examples/intro/03_figure_element.py @@ -23,6 +23,7 @@ # %% import pygmt +from pygmt.params import Axis, Frame fig = pygmt.Figure() @@ -33,7 +34,12 @@ fig.basemap( region=[0, 10, 0, 20], projection="X10c/8c", - frame=["WStr+tTitle", "xa2f1g2+lxlabel", "ya5f1g5+lylabel"], + frame=Frame( + axes="WSrt", + title="Title", + xaxis=Axis(annot=2, tick=1, grid=2, label="xlabel"), + yaxis=Axis(annot=5, tick=1, grid=5, label="ylabel"), + ), ) fig.plot(x=x, y=y_1, style="t0.3c", label="fig.plot (style)") fig.plot(x=x, y=y_2, pen="1.5p,red", label="fig.plot (pen)") From f68f2fe2926d081652b5ae1bc10ec37141a71b1f Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 29 Apr 2026 20:02:41 +0800 Subject: [PATCH 2/4] Remove annotations for commands/parameters --- examples/intro/03_figure_element.py | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/examples/intro/03_figure_element.py b/examples/intro/03_figure_element.py index ac99b51eab5..99713530c1f 100644 --- a/examples/intro/03_figure_element.py +++ b/examples/intro/03_figure_element.py @@ -49,44 +49,29 @@ # ============ Figure fig.text(x=12, y=22, text="Figure", **mainexplain) fig.text(x=12, y=20.8, text="pygmt.Figure()", **minorexplain) -# ============ Title -fig.text(x=7.5, y=22, text='frame="+tTitle"', **minorexplain) -# ============ xlabel -fig.text(x=5, y=-3, text='frame="x+lxlabel"', **minorexplain) -# ============ ylabel -fig.text(x=-1.7, y=10, text='frame="y+lylabel"', angle=90, **minorexplain) # ============ x-majorticks fig.plot(x=10, y=-0.2, style="c1c", pen="2p,darkblue", no_clip=True) fig.text(x=10, y=-1.6, text="Annotation", **mainexplain) -fig.text(x=10, y=-2.8, text='frame="xa2"', **minorexplain) # ============ y-majorticks fig.plot(x=-0.2, y=20, style="c1c", pen="2p,darkblue", no_clip=True) fig.text(x=0, y=23.4, text="Annotation", **mainexplain) -fig.text(x=0, y=22.2, text='frame="ya5"', **minorexplain) # ============ x-minorticks fig.plot(x=1, y=-0.2, style="c0.7c", pen="2p,darkblue", no_clip=True) fig.text(x=1, y=-1.4, text="Frame", **mainexplain) -fig.text(x=1, y=-2.6, text='frame="xf1"', **minorexplain) # ============ y-minorticks fig.plot(x=0, y=2, style="c0.7c", pen="2p,darkblue", no_clip=True) -fig.text(x=-1.5, y=1, text='frame="yf1"', **minorexplain) # ============ Grid fig.plot(x=2, y=15, style="c0.5c", pen="2p,darkblue") fig.text(x=2, y=17, text="Grid", **mainexplain) -fig.text(x=2.4, y=18, text='frame=["xg2", "yg5"]', **minorexplain) # ============ Plot Boundaries fig.plot(x=10, y=9, style="c0.5c", pen="2p,darkblue", no_clip=True) fig.text(x=11.5, y=8, text="Plot Boundary", **mainexplain) -fig.text(x=11.5, y=6.8, text='frame="WStr"', **minorexplain) # ============ fig.plot (style) fig.plot(x=6, y=8, style="c0.7c", pen="2p,darkblue") -fig.text(x=7, y=6.5, text="fig.plot(style)", **minorexplain) # ============ fig.plot (pen) fig.plot(x=4, y=6, style="c0.7c", pen="2p,darkblue") -fig.text(x=3, y=4.5, text="fig.plot(pen)", **minorexplain) # ============ Legend fig.legend() fig.text(x=8, y=16.9, text="Legend", **mainexplain) -fig.text(x=8, y=15.8, text="fig.legend()", **minorexplain) fig.show() From 24b30637e9cbe4715d433bcbd7d54b8900269057 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 29 Apr 2026 20:03:38 +0800 Subject: [PATCH 3/4] Focus on figure elements rather than specific PyGMT commmands --- examples/intro/03_figure_element.py | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/examples/intro/03_figure_element.py b/examples/intro/03_figure_element.py index 99713530c1f..4f068ad633e 100644 --- a/examples/intro/03_figure_element.py +++ b/examples/intro/03_figure_element.py @@ -3,22 +3,6 @@ ================== The figure below shows the naming of figure elements in PyGMT. - -- :meth:`pygmt.Figure()`: having a number of plotting methods. Every new - figure must start with the creation of a :meth:`pygmt.Figure()` instance -- ``frame``: setting plot boundaries (a combination of the single - letters of **WSNE**, **wsne**, or **lbtr**), adding annotations, ticks, - gridlines (**afg**), axis labels (**+l**), and title (**+t**), e.g., - in :meth:`pygmt.Figure.basemap`. Detailed examples can be found at - :doc:`frame and axes attributes ` -- :meth:`pygmt.Figure.plot`: plotting lines or symbols based on ``pen`` - or ``style`` parameters, respectively -- :meth:`pygmt.Figure.text`: plotting text strings whereby the ``font`` - parameter adjusts fontsize, fontstyle, and color -- :meth:`pygmt.Figure.legend`: showing the naming of lines or symbols while - the ``label`` is given in :meth:`pygmt.Figure.plot` -- :meth:`pygmt.Figure.show`: previewing the content added to the current - figure instance """ # %% From 622183e9da033f6b0a51037d920d17c629af4add Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 2 May 2026 13:15:53 +0800 Subject: [PATCH 4/4] Expand figure elements intro tutorial --- examples/intro/03_figure_element.py | 117 +++++++++++++++++++++++++++- 1 file changed, 116 insertions(+), 1 deletion(-) diff --git a/examples/intro/03_figure_element.py b/examples/intro/03_figure_element.py index 4f068ad633e..122a224bd24 100644 --- a/examples/intro/03_figure_element.py +++ b/examples/intro/03_figure_element.py @@ -7,7 +7,7 @@ # %% import pygmt -from pygmt.params import Axis, Frame +from pygmt.params import Axis, Box, Frame, Position fig = pygmt.Figure() @@ -59,3 +59,118 @@ fig.text(x=8, y=16.9, text="Legend", **mainexplain) fig.show() + +# %% +# 3-D plot example +# ---------------- +# +# Figure elements are also important in 3-D views. Here we use a perspective plot of +# Earth relief and add a title, axis annotations, and a colorbar aligned with the 3-D +# view. + +grid = pygmt.datasets.load_earth_relief( + resolution="10m", region=[-108, -103, 35, 40] +) + +fig = pygmt.Figure() +fig.grdview( + grid=grid, + projection="M12c", + perspective=[130, 30], + zsize="1.5c", + surftype="surface", + cmap="gmt/geo", + frame=Frame( + axes="WSnEZ", + title="3-D relief view", + xaxis=Axis(annot=True, label="Longitude"), + yaxis=Axis(annot=True, label="Latitude"), + zaxis=Axis(annot=1000, tick=500, label="Elevation", unit="m"), + ), + plane=1000, + facade_fill="gray", +) +fig.colorbar(perspective=True, annot=500, label="Elevation", unit="m") +fig.show() + +# %% +# Subplot example +# --------------- +# +# Figure elements can also be organized across multiple panels. The example below uses +# a 2x1 subplot layout, where each panel has its own title and frame annotations. + +fig = pygmt.Figure() +with fig.subplot( + nrows=2, + ncols=1, + figsize=("10c", "12c"), + frame=Frame( + axes="WSrt", + xaxis=Axis(annot=2, tick=1, grid=2, label="x"), + yaxis=Axis(annot=5, tick=1, grid=5, label="y"), + ), + margins="0.4c", +): + fig.basemap(region=[0, 10, 0, 20], projection="X?", panel=[0, 0], frame="+tPanel A") + fig.plot(x=x, y=y_1, style="c0.25c", fill="steelblue", panel=[0, 0]) + fig.text(x=8.5, y=17, text="Top panel", font="12p,Helvetica-Bold", panel=[0, 0]) + + fig.basemap(region=[0, 10, 0, 20], projection="X?", panel=[1, 0], frame="+tPanel B") + fig.plot(x=x, y=y_2, pen="1.5p,firebrick", panel=[1, 0]) + fig.text( + x=8.5, + y=17, + text="Bottom panel", + font="12p,Helvetica-Bold", + panel=[1, 0], + ) + +fig.show() + +# %% +# Geographic map example +# ---------------------- +# +# Figure elements are also commonly used on geographic maps. The example below uses +# Earth relief as the main map, then adds a colorbar, a directional rose, and an inset +# map to show where the study area is located in a broader regional context. + +region = [137.5, 141, 34, 37] +grid = pygmt.datasets.load_earth_relief(resolution="01m", region=region) + +fig = pygmt.Figure() +fig.grdimage( + grid=grid, + projection="M12c", + cmap="gmt/geo", + shading=True, + frame=Frame( + axes="WSne", + title="Central Japan", + xaxis=Axis(annot=True, label="Longitude"), + yaxis=Axis(annot=True, label="Latitude"), + ), +) +fig.coast(shorelines="0.5p,black") +fig.colorbar(annot=1000, label="Elevation", unit="m") +fig.directional_rose( + position=Position("TL", offset=0.2), + width="1.5c", + labels=True, +) + +with fig.inset( + position=Position("BR", offset=0.1), + box=Box(fill="white", pen="0.8p"), + region=[129, 146, 30, 46], + projection="M3.5c", +): + fig.coast(land="gray85", water="white", shorelines="0.25p") + fig.plot( + data=[[region[0], region[2], region[1], region[3]]], + style="r+s", + pen="1p,blue", + ) + +fig.show()