Skip to content

Conversation

@yvonnefroehlich
Copy link
Member

@yvonnefroehlich yvonnefroehlich commented Dec 20, 2025

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

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

@yvonnefroehlich yvonnefroehlich added the documentation Improvements or additions to documentation label Dec 20, 2025
@yvonnefroehlich yvonnefroehlich self-assigned this Dec 20, 2025
@yvonnefroehlich yvonnefroehlich marked this pull request as draft December 22, 2025 07:33
@yvonnefroehlich yvonnefroehlich changed the title POC: WIP: Add gallery example for 3-D bar plot WIP: Add gallery example for 3-D bar plot Jan 15, 2026
@yvonnefroehlich yvonnefroehlich changed the title WIP: Add gallery example for 3-D bar plot Add gallery example for 3-D bar plot Jan 15, 2026
@yvonnefroehlich yvonnefroehlich added this to the 0.19.0 milestone Jan 15, 2026
@yvonnefroehlich yvonnefroehlich marked this pull request as ready for review January 15, 2026 15:55
@yvonnefroehlich yvonnefroehlich added the needs review This PR has higher priority and needs review. label Jan 15, 2026
# Convert the grid into a table and add a column "color" for the quantity used for the
# color-coding of the bars, here the elevation ("z")
grd2tab = pygmt.grd2xyz(grid=grid, region=region)
grd2tab["color"] = grd2tab["z"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the "color" column used anywhere?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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()

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +5 to +8
A 3-D bar plot of a grid can be created in two steps: (i) convert the grid into a table
via :func:`pygmt.grd2xyz` and (ii) plot this table as bars in 3-D using
:meth:`pygmt.Figure.plot3d`. The bars can be outlined, and the fill can be one color or
based on a quantity using a colormap.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

import pygmt
from pygmt.params import Position

# Define a study area with huge elevation changes
Copy link

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comment mentions 'huge elevation changes' but this is subjective and not specific. Consider being more descriptive about the region (e.g., 'Define a study area covering Japan's Honshu island').

Suggested change
# Define a study area with huge elevation changes
# Define a study area over northern Japan (around northern Honshu and southern Hokkaido) with large elevation changes

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation needs review This PR has higher priority and needs review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants