From 501bf69f5e95583734846e2172831f000c2842a0 Mon Sep 17 00:00:00 2001 From: chuan Date: Sat, 21 Mar 2026 22:56:11 +0800 Subject: [PATCH 01/18] tutorial:Plotting features on a 3-D surface --- .../advanced/features_on_3d_surface.py | 216 ++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 examples/tutorials/advanced/features_on_3d_surface.py diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py new file mode 100644 index 00000000000..590a347d3e6 --- /dev/null +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -0,0 +1,216 @@ +""" +Plotting features on a 3-D surface +================================== + +In addition to draping a dataset (grid or image) on top of a topographic surface, +you may want to add additional features like coastlines, symbols, and text +annotations. This tutorial shows how to use :meth:`pygmt.Figure.coast`, +:meth:`pygmt.Figure.plot3d`, and :meth:`pygmt.Figure.text` to add these features +on a 3-D surface created by :meth:`pygmt.Figure.grdview`. + +This tutorial consists of three examples: + +1. Adding coastlines on a 3-D surface +2. Adding symbols on a 3-D surface +3. Adding text annotations on a 3-D surface +""" + +# %% + +# Load the required packages +import pandas as pd +import pygmt + +# %% +# 1. Adding coastlines on a 3-D surface +# ------------------------------------- +# +# In the first example, we plot coastlines on top of a 3-D topographic surface. + +# Load sample earth relief data for the region of Taiwan +# ------------------------------------------------------ +# +# We use a region around Taiwan to demonstrate adding features on a 3-D surface. + +# Define the study area in degrees East or North +region_2d = [119, 123, 21, 26] # [lon_min, lon_max, lat_min, lat_max] + +# Download elevation grid for the study region with a resolution of 5 arc-minutes. +# 5m provides clearer terrain than 10m while still being reasonably fast. +grd_relief = pygmt.datasets.load_earth_relief(resolution="05m", region=region_2d) + +# Determine the 3-D region from the minimum and maximum values of the relief grid +region_3d = [*region_2d, grd_relief.min().to_numpy(), grd_relief.max().to_numpy()] + +# Set up a colormap for topography and bathymetry +pygmt.makecpt( + cmap="geo", series=[grd_relief.min().to_numpy(), grd_relief.max().to_numpy()] +) + +# %% +# Create a 3-D surface and add coastlines +# --------------------------------------- +# +# First, we create a 3-D surface using :meth:`pygmt.Figure.grdview`. Then we add +# coastlines using :meth:`pygmt.Figure.coast` with a matching ``perspective`` setting. +# Here we set the z-level to 0 so coastlines are drawn at sea level. + +fig = pygmt.Figure() + +# Create a 3-D surface +fig.grdview( + projection="M12c", # Mercator projection with a width of 12 cm + region=region_3d, + grid=grd_relief, + cmap=True, + surftype="surface", + shading="+a0/270+ne0.6", + perspective=[157.5, 30], # Azimuth and elevation for the 3-D plot + zsize="1.5c", + facade_fill="darkgray", + frame=["xaf", "yaf", "WSnE"], +) + +# Add coastlines on top of the 3-D surface +# Using perspective=True to inherit the viewing angle from grdview +fig.coast( + perspective=[157.5, 30, 0], + resolution="f", + shorelines="1/1.5p,black", +) + +# Add a colorbar +fig.colorbar(perspective=True, annot=1000, tick=500, label="Elevation", unit="m") + +fig.show() + +# %% +# 2. Adding symbols on a 3-D surface +# ---------------------------------- +# +# In the second example, we add star symbols on top of the same 3-D surface. To plot +# symbols on a 3-D surface, use :meth:`pygmt.Figure.plot3d`. The z-coordinate should be +# set to a value at or above the maximum elevation to ensure the symbols are visible. + +# Sample point data: five coastal cities around Taiwan +cities = pd.DataFrame( + { + "longitude": [ + 121.74, + 121.61, + 121.14, + 120.30, + 120.53, + ], # Keelung, Hualien, Taitung, Kaohsiung, Taichung Port + "latitude": [25.13, 23.99, 22.76, 22.63, 24.27], + "name": ["Keelung", "Hualien", "Taitung", "Kaohsiung", "Taichung Port"], + } +) + +# Use one common z-level so all stars share the same shape and size. +z_stars = [grd_relief.max().to_numpy() + 1500] * len(cities.index) + +fig = pygmt.Figure() + +# Create a 3-D surface +fig.grdview( + projection="M12c", + region=region_3d, + grid=grd_relief, + cmap=True, + surftype="surface", + shading="+a0/270+ne0.6", + perspective=[157.5, 30], + zsize="1.5c", + facade_fill="darkgray", + frame=["xaf", "yaf", "WSnE"], +) + +# Add coastlines +fig.coast( + perspective=[157.5, 30, 0], + resolution="f", + shorelines="1/1.5p,black", +) + +# Add five identical star symbols on top of the 3-D surface +fig.plot3d( + x=cities.longitude, + y=cities.latitude, + z=z_stars, + style="a0.65c", + fill="gold", + pen="0.8p,black", + perspective=True, + zsize="1.5c", # Use the same zsize as grdview + no_clip=True, +) + +# Add a colorbar +fig.colorbar(perspective=True, annot=500, label="Elevation", unit="m") + +fig.show() + +# %% +# 3. Adding text annotations on a 3-D surface +# ------------------------------------------- +# +# In the third example, we add text labels to the same 3-D figure. To add text +# annotations on a 3-D surface, use :meth:`pygmt.Figure.text` with +# ``perspective=True``. Note that the current implementation of ``text`` does not +# support a ``z`` parameter for controlling the vertical position of text labels. +# The text will be placed at the base of the 3-D plot (z=0). + +fig = pygmt.Figure() + +# Create a 3-D surface +fig.grdview( + projection="M12c", + region=region_3d, + grid=grd_relief, + cmap=True, + surftype="surface", + shading="+a0/270+ne0.6", + perspective=[157.5, 30], + zsize="1.5c", + facade_fill="darkgray", + frame=["xaf", "yaf", "WSnE"], +) + +# Add coastlines +fig.coast( + perspective=[157.5, 30, 0], + resolution="f", + shorelines="1/1.5p,black", +) + +# Add symbols for cities +fig.plot3d( + x=cities.longitude, + y=cities.latitude, + z=z_stars, + style="a0.55c", + fill="gold", + pen="0.8p,black", + perspective=True, + zsize="1.5c", + no_clip=True, +) + +# Add text labels for cities +# Note: text is placed at z=0 (base level) since z parameter is not yet supported +fig.text( + x=cities.longitude, + y=cities.latitude, + text=cities.name, + perspective=True, + font="11p,Helvetica-Bold,red", + no_clip=True, # Prevent text from being clipped at the frame boundaries +) + +# Add a colorbar +fig.colorbar(perspective=True, annot=500, label="Elevation", unit="m") + +fig.show() + +# sphinx_gallery_thumbnail_number = 3 From 44d5c3804699d60e69677e19feb8dadd614269e6 Mon Sep 17 00:00:00 2001 From: Xingchen He Date: Sun, 22 Mar 2026 11:31:16 +0800 Subject: [PATCH 02/18] Update examples/tutorials/advanced/features_on_3d_surface.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- examples/tutorials/advanced/features_on_3d_surface.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 590a347d3e6..c5256c42911 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -180,7 +180,7 @@ # Add coastlines fig.coast( perspective=[157.5, 30, 0], - resolution="f", + resolution="full", shorelines="1/1.5p,black", ) From b9c9c4d4ce8ccf60331660a2539c6a8e62f11b15 Mon Sep 17 00:00:00 2001 From: Xingchen He Date: Sun, 22 Mar 2026 11:31:28 +0800 Subject: [PATCH 03/18] Update examples/tutorials/advanced/features_on_3d_surface.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- examples/tutorials/advanced/features_on_3d_surface.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index c5256c42911..61d698758ed 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -75,7 +75,7 @@ # Using perspective=True to inherit the viewing angle from grdview fig.coast( perspective=[157.5, 30, 0], - resolution="f", + resolution="full", shorelines="1/1.5p,black", ) From 0b69c19f87248ad4257acd1c53ea83197845a044 Mon Sep 17 00:00:00 2001 From: Xingchen He Date: Sun, 22 Mar 2026 11:31:43 +0800 Subject: [PATCH 04/18] Update examples/tutorials/advanced/features_on_3d_surface.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- examples/tutorials/advanced/features_on_3d_surface.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 61d698758ed..06dc90dc9d3 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -108,7 +108,8 @@ ) # Use one common z-level so all stars share the same shape and size. -z_stars = [grd_relief.max().to_numpy() + 1500] * len(cities.index) +max_elevation = float(grd_relief.max().to_numpy()) +z_stars = [max_elevation + 1500] * len(cities.index) fig = pygmt.Figure() From 72cc47dca7b7d8aced92f93257359f5517d3542b Mon Sep 17 00:00:00 2001 From: Xingchen He Date: Sun, 22 Mar 2026 11:31:52 +0800 Subject: [PATCH 05/18] Update examples/tutorials/advanced/features_on_3d_surface.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- examples/tutorials/advanced/features_on_3d_surface.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 06dc90dc9d3..708a454e692 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -72,7 +72,8 @@ ) # Add coastlines on top of the 3-D surface -# Using perspective=True to inherit the viewing angle from grdview +# Use an explicit perspective to match grdview (azimuth=157.5, elevation=30) +# and set the z-level to 0 so the coastlines are drawn at sea level. fig.coast( perspective=[157.5, 30, 0], resolution="full", From 2ede333ba006845f4ba0c29babce18462d80ba8f Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 12:26:36 +0800 Subject: [PATCH 06/18] change cpt --- examples/tutorials/advanced/features_on_3d_surface.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 708a454e692..916a26532e3 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -43,9 +43,7 @@ region_3d = [*region_2d, grd_relief.min().to_numpy(), grd_relief.max().to_numpy()] # Set up a colormap for topography and bathymetry -pygmt.makecpt( - cmap="geo", series=[grd_relief.min().to_numpy(), grd_relief.max().to_numpy()] -) +pygmt.makecpt(cmap="geo", series=[-8000, 8000]) # %% # Create a 3-D surface and add coastlines From f55325b847c82354776112879437d1d7aa6f08d3 Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 12:31:35 +0800 Subject: [PATCH 07/18] Refactor example --- .../advanced/features_on_3d_surface.py | 67 +------------------ 1 file changed, 1 insertion(+), 66 deletions(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 916a26532e3..c1c216a560c 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -75,7 +75,7 @@ fig.coast( perspective=[157.5, 30, 0], resolution="full", - shorelines="1/1.5p,black", + shorelines="1/2p,black", ) # Add a colorbar @@ -110,29 +110,6 @@ max_elevation = float(grd_relief.max().to_numpy()) z_stars = [max_elevation + 1500] * len(cities.index) -fig = pygmt.Figure() - -# Create a 3-D surface -fig.grdview( - projection="M12c", - region=region_3d, - grid=grd_relief, - cmap=True, - surftype="surface", - shading="+a0/270+ne0.6", - perspective=[157.5, 30], - zsize="1.5c", - facade_fill="darkgray", - frame=["xaf", "yaf", "WSnE"], -) - -# Add coastlines -fig.coast( - perspective=[157.5, 30, 0], - resolution="f", - shorelines="1/1.5p,black", -) - # Add five identical star symbols on top of the 3-D surface fig.plot3d( x=cities.longitude, @@ -146,9 +123,6 @@ no_clip=True, ) -# Add a colorbar -fig.colorbar(perspective=True, annot=500, label="Elevation", unit="m") - fig.show() # %% @@ -161,42 +135,6 @@ # support a ``z`` parameter for controlling the vertical position of text labels. # The text will be placed at the base of the 3-D plot (z=0). -fig = pygmt.Figure() - -# Create a 3-D surface -fig.grdview( - projection="M12c", - region=region_3d, - grid=grd_relief, - cmap=True, - surftype="surface", - shading="+a0/270+ne0.6", - perspective=[157.5, 30], - zsize="1.5c", - facade_fill="darkgray", - frame=["xaf", "yaf", "WSnE"], -) - -# Add coastlines -fig.coast( - perspective=[157.5, 30, 0], - resolution="full", - shorelines="1/1.5p,black", -) - -# Add symbols for cities -fig.plot3d( - x=cities.longitude, - y=cities.latitude, - z=z_stars, - style="a0.55c", - fill="gold", - pen="0.8p,black", - perspective=True, - zsize="1.5c", - no_clip=True, -) - # Add text labels for cities # Note: text is placed at z=0 (base level) since z parameter is not yet supported fig.text( @@ -208,9 +146,6 @@ no_clip=True, # Prevent text from being clipped at the frame boundaries ) -# Add a colorbar -fig.colorbar(perspective=True, annot=500, label="Elevation", unit="m") - fig.show() # sphinx_gallery_thumbnail_number = 3 From a30ee4fe1f612898f56e1e517d00bbcba607a409 Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 12:44:37 +0800 Subject: [PATCH 08/18] limit cpt range --- examples/tutorials/advanced/features_on_3d_surface.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index c1c216a560c..c77bf05c23c 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -43,7 +43,7 @@ region_3d = [*region_2d, grd_relief.min().to_numpy(), grd_relief.max().to_numpy()] # Set up a colormap for topography and bathymetry -pygmt.makecpt(cmap="geo", series=[-8000, 8000]) +pygmt.makecpt(cmap="gmt/globe", series=[-6000, 3000]) # %% # Create a 3-D surface and add coastlines From ad6a50933cdc58a361e92b5f3e4bddcf6768aa12 Mon Sep 17 00:00:00 2001 From: Xingchen He Date: Sun, 22 Mar 2026 16:57:24 +0800 Subject: [PATCH 09/18] Update examples/tutorials/advanced/features_on_3d_surface.py Co-authored-by: Dongdong Tian --- examples/tutorials/advanced/features_on_3d_surface.py | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index c77bf05c23c..109f6223123 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -17,7 +17,6 @@ # %% -# Load the required packages import pandas as pd import pygmt From 0a3a4344f96ca257b1862d84d5812762f9333ec1 Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 17:16:00 +0800 Subject: [PATCH 10/18] rephrase , add steps --- .../advanced/features_on_3d_surface.py | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index c77bf05c23c..fccc07265a4 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -8,11 +8,12 @@ :meth:`pygmt.Figure.plot3d`, and :meth:`pygmt.Figure.text` to add these features on a 3-D surface created by :meth:`pygmt.Figure.grdview`. -This tutorial consists of three examples: +This tutorial builds a 3-D map in four steps: -1. Adding coastlines on a 3-D surface -2. Adding symbols on a 3-D surface -3. Adding text annotations on a 3-D surface +1. Creating a 3-D surface +2. Adding coastlines on a 3-D surface +3. Adding symbols on a 3-D surface +4. Adding text annotations on a 3-D surface """ # %% @@ -22,10 +23,10 @@ import pygmt # %% -# 1. Adding coastlines on a 3-D surface -# ------------------------------------- +# 1. Creating a 3-D surface +# ------------------------- # -# In the first example, we plot coastlines on top of a 3-D topographic surface. +# In the first step, we create a 3-D topographic map using :meth:`pygmt.Figure.grdview`. # Load sample earth relief data for the region of Taiwan # ------------------------------------------------------ @@ -46,12 +47,8 @@ pygmt.makecpt(cmap="gmt/globe", series=[-6000, 3000]) # %% -# Create a 3-D surface and add coastlines -# --------------------------------------- -# -# First, we create a 3-D surface using :meth:`pygmt.Figure.grdview`. Then we add -# coastlines using :meth:`pygmt.Figure.coast` with a matching ``perspective`` setting. -# Here we set the z-level to 0 so coastlines are drawn at sea level. +# Create a 3-D surface +# -------------------- fig = pygmt.Figure() @@ -69,6 +66,18 @@ frame=["xaf", "yaf", "WSnE"], ) +# Add a colorbar +fig.colorbar(perspective=True, annot=1000, tick=500, label="Elevation", unit="m") + +fig.show() + +# %% +# 2. Adding coastlines on a 3-D surface +# ------------------------------------- +# +# Next, we add coastlines using :meth:`pygmt.Figure.coast` with a matching ``perspective`` setting. +# Here we set the z-level to 0 so coastlines are drawn at sea level. + # Add coastlines on top of the 3-D surface # Use an explicit perspective to match grdview (azimuth=157.5, elevation=30) # and set the z-level to 0 so the coastlines are drawn at sea level. @@ -78,16 +87,13 @@ shorelines="1/2p,black", ) -# Add a colorbar -fig.colorbar(perspective=True, annot=1000, tick=500, label="Elevation", unit="m") - fig.show() # %% -# 2. Adding symbols on a 3-D surface +# 3. Adding symbols on a 3-D surface # ---------------------------------- # -# In the second example, we add star symbols on top of the same 3-D surface. To plot +# In the third step, we add star symbols on top of the same 3-D map. To plot # symbols on a 3-D surface, use :meth:`pygmt.Figure.plot3d`. The z-coordinate should be # set to a value at or above the maximum elevation to ensure the symbols are visible. @@ -126,10 +132,10 @@ fig.show() # %% -# 3. Adding text annotations on a 3-D surface +# 4. Adding text annotations on a 3-D surface # ------------------------------------------- # -# In the third example, we add text labels to the same 3-D figure. To add text +# In the final step, we add text labels to the same 3-D map. To add text # annotations on a 3-D surface, use :meth:`pygmt.Figure.text` with # ``perspective=True``. Note that the current implementation of ``text`` does not # support a ``z`` parameter for controlling the vertical position of text labels. From c7cfa2e9e13fea163626e32334548bfde833f47d Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 17:26:20 +0800 Subject: [PATCH 11/18] update ruff --- examples/tutorials/advanced/features_on_3d_surface.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 3445f105bf6..ffc076c775c 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -74,8 +74,9 @@ # 2. Adding coastlines on a 3-D surface # ------------------------------------- # -# Next, we add coastlines using :meth:`pygmt.Figure.coast` with a matching ``perspective`` setting. -# Here we set the z-level to 0 so coastlines are drawn at sea level. +# Next, we add coastlines using :meth:`pygmt.Figure.coast` with a matching +# ``perspective`` setting. Here we set the z-level to 0 so coastlines are drawn +# at sea level. # Add coastlines on top of the 3-D surface # Use an explicit perspective to match grdview (azimuth=157.5, elevation=30) From c926807b2c0b6cc2242be1fcb9b2bf2fc6f63841 Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 17:38:31 +0800 Subject: [PATCH 12/18] simplify content --- examples/tutorials/advanced/features_on_3d_surface.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index ffc076c775c..4208251e81c 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -45,10 +45,6 @@ # Set up a colormap for topography and bathymetry pygmt.makecpt(cmap="gmt/globe", series=[-6000, 3000]) -# %% -# Create a 3-D surface -# -------------------- - fig = pygmt.Figure() # Create a 3-D surface From d4723d4e1fc1d189c84907ecfd3711009666dce9 Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 19:08:55 +0800 Subject: [PATCH 13/18] fix typo --- examples/tutorials/advanced/features_on_3d_surface.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 4208251e81c..46bc74f1455 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -26,10 +26,6 @@ # ------------------------- # # In the first step, we create a 3-D topographic map using :meth:`pygmt.Figure.grdview`. - -# Load sample earth relief data for the region of Taiwan -# ------------------------------------------------------ -# # We use a region around Taiwan to demonstrate adding features on a 3-D surface. # Define the study area in degrees East or North From 975ca489f83daae6ac4ec76c0dc68ec6e814c42e Mon Sep 17 00:00:00 2001 From: chuan Date: Sun, 22 Mar 2026 19:18:15 +0800 Subject: [PATCH 14/18] use Times-Bold font --- examples/tutorials/advanced/features_on_3d_surface.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 46bc74f1455..866007622f5 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -140,7 +140,7 @@ y=cities.latitude, text=cities.name, perspective=True, - font="11p,Helvetica-Bold,red", + font="11p,Times-Bold,red", no_clip=True, # Prevent text from being clipped at the frame boundaries ) From a4b8ffb4597e28f6a1e4ca85b61337ef2805dade Mon Sep 17 00:00:00 2001 From: chuan Date: Mon, 23 Mar 2026 22:03:35 +0800 Subject: [PATCH 15/18] Mention 3D plot behavior. --- examples/tutorials/advanced/features_on_3d_surface.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 866007622f5..d5a7d946f55 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -8,7 +8,7 @@ :meth:`pygmt.Figure.plot3d`, and :meth:`pygmt.Figure.text` to add these features on a 3-D surface created by :meth:`pygmt.Figure.grdview`. -This tutorial builds a 3-D map in four steps: +This tutorial builds a 3-D map with additional features in four steps: 1. Creating a 3-D surface 2. Adding coastlines on a 3-D surface @@ -88,6 +88,9 @@ # In the third step, we add star symbols on top of the same 3-D map. To plot # symbols on a 3-D surface, use :meth:`pygmt.Figure.plot3d`. The z-coordinate should be # set to a value at or above the maximum elevation to ensure the symbols are visible. +# Note that 3-D rendering in GMT/PyGMT uses a painter's algorithm (depth sorting) +# rather than true 3-D occlusion. From some viewpoints, symbols that should be +# hidden behind terrain may still appear visible. # Sample point data: five coastal cities around Taiwan cities = pd.DataFrame( From 3ee290cc97b0bdc07b91bdcf847d36bf75c7cff3 Mon Sep 17 00:00:00 2001 From: chuan Date: Tue, 24 Mar 2026 12:06:35 +0800 Subject: [PATCH 16/18] fix cpt --- examples/tutorials/advanced/features_on_3d_surface.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index d5a7d946f55..93d29d0504d 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -38,11 +38,11 @@ # Determine the 3-D region from the minimum and maximum values of the relief grid region_3d = [*region_2d, grd_relief.min().to_numpy(), grd_relief.max().to_numpy()] +fig = pygmt.Figure() + # Set up a colormap for topography and bathymetry pygmt.makecpt(cmap="gmt/globe", series=[-6000, 3000]) -fig = pygmt.Figure() - # Create a 3-D surface fig.grdview( projection="M12c", # Mercator projection with a width of 12 cm From d0e314bd6e0d28053481e2e67dde4994e50bdd41 Mon Sep 17 00:00:00 2001 From: Xingchen He Date: Tue, 24 Mar 2026 12:30:00 +0800 Subject: [PATCH 17/18] Update examples/tutorials/advanced/features_on_3d_surface.py Co-authored-by: Dongdong Tian --- examples/tutorials/advanced/features_on_3d_surface.py | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 93d29d0504d..01bf5893dc8 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -32,7 +32,6 @@ region_2d = [119, 123, 21, 26] # [lon_min, lon_max, lat_min, lat_max] # Download elevation grid for the study region with a resolution of 5 arc-minutes. -# 5m provides clearer terrain than 10m while still being reasonably fast. grd_relief = pygmt.datasets.load_earth_relief(resolution="05m", region=region_2d) # Determine the 3-D region from the minimum and maximum values of the relief grid From c05a0c8f7ac74d545b9d954da77cbb35665e2fed Mon Sep 17 00:00:00 2001 From: chuan Date: Tue, 24 Mar 2026 12:41:08 +0800 Subject: [PATCH 18/18] use new Frame parameter --- examples/tutorials/advanced/features_on_3d_surface.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/features_on_3d_surface.py b/examples/tutorials/advanced/features_on_3d_surface.py index 01bf5893dc8..2eac4bb8606 100644 --- a/examples/tutorials/advanced/features_on_3d_surface.py +++ b/examples/tutorials/advanced/features_on_3d_surface.py @@ -20,6 +20,7 @@ import pandas as pd import pygmt +from pygmt.params import Axis, Frame # %% # 1. Creating a 3-D surface @@ -53,7 +54,7 @@ perspective=[157.5, 30], # Azimuth and elevation for the 3-D plot zsize="1.5c", facade_fill="darkgray", - frame=["xaf", "yaf", "WSnE"], + frame=Frame(axes="WSnE", axis=Axis(annot=True, tick=True)), ) # Add a colorbar