Add gallery example for 3-D bar plot

[yvonnefroehlich]

Description of proposed changes

This PR tests to create a 3-D bar plot in PyGMT and addes a gallery example.

Preview: https://pygmt-dev--4315.org.readthedocs.build/en/4315/gallery/3d_plots/3d_bar.html

Guidelines

• General Guidelines for Pull Request
• Guidelines for Contributing Documentation
• Guidelines for Contributing Code

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[seisman]

Is the "color" column used anywhere?

[yvonnefroehlich]

Yes, the "color" column is used for the color-coding.
Alternatively, we could use the incols parameter and use the second column ("z") twice:

# %%
import pygmt
from pygmt.params import Position

# Define a study area with huge elevation changes
region = [141, 147, 36, 43]

# Download a grid for the Earth relief with a resolution of 10 arc-minutes
grid = pygmt.datasets.load_earth_relief(resolution="10m", region=region)

# Convert the grid into a pandas DataFrame
grd_df = pygmt.grd2xyz(grid=grid)
zmin = grd_df["z"].min() - 50
zmax = grd_df["z"].max() + 50

# Create a 3-D bar plot with color-coding
fig = pygmt.Figure()

fig.basemap(
    region=[*region, zmin, zmax],
    projection="M10c",
    zsize="8c",
    frame=["WSneZ", "xaf", "yag", "za1000f500+lElevation / m"],
    perspective=(195, 30),
)

pygmt.makecpt(cmap="SCM/oleron", series=(zmin, zmax))
fig.plot3d(
    data=grd_df,
    # Use "o" to plot bars and give the desired size
    # The base of the bars is set via "+b"
    style=f"o0.34c+b{zmin}",
    cmap=True,
    pen="0.01p,gray30",
    perspective=True,
    # Use the elevation for the color-coding of the bars
    # Zero-based indexing for columns
    incols=[0, 1, 2, 2],  # lon, lat, z for elevation, z for color-coding
)
fig.colorbar(
    frame=["xa1000f500+lElevation", "y+lm"],
    position=Position("TR", cstype="inside", offset=1.4),
    orientation="vertical",
    length=7,
    move_text="label",
    label_as_column=True,
)

fig.show()

[seisman]

I see the point. Need to explain that plot3d requires four columns. The four column is used for color coding. In this example, the fourth column is identical to the z column, but other values are allowed

[seisman]

We can create a 3-D bar plot for any collection of XYZ points, whether they lie on a regular grid or are irregularly scattered. Therefore, it’s clearer to start with a general description of the 3-D bar plot itself and then mention that, as a special case, we can convert a grid into XYZ and visualize it with the same routine.

[yvonnefroehlich]

Agree the introduction texts needs some more work. Thanks for your ideas here 🙂. Will work on this in the next days.

[yvonnefroehlich]

I have made some updates to the introduction text and comments.

[Copilot]

Pull request overview

This PR adds a new gallery example demonstrating how to create a 3-D bar plot in PyGMT using Earth relief data. The example shows how to convert grid data to a table format and visualize it as color-coded bars in 3D space.

Changes:

• Adds a new 3-D bar plot example to the gallery
• Demonstrates grid-to-table conversion using pygmt.grd2xyz
• Shows color-coded visualization of elevation data using bars in 3D

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.