Add Physics Based Rendering (PBR) shading method to grdimage and grdview by joa-quim · Pull Request #9230 · GenericMappingTools/gmt

joa-quim · 2026-09-25T23:09:03Z

PBR is a shading method used by the VTK library in GPU rendering. In i'GMT I managed to had it replicated (almost) in C and this PR ports it into GMT. The shading quality of this method seems rather more appealing than what we have so far. It is implemented in grdimage and grdview as option -F and a shortcut -I+f can be used to that resorts to default values (maybe these def values can be tuned). Code was accelerated with OMP and runs rather rapidly in spite having to do quite some more work than the pure gradient methods we have in GMT so far.

As an example, this

gmt grdimage @earth_gebco_15s -R-156.2/-154.7/18.8/20.35 -Cgeo -F315/35+o+s+t+v3+l1.4+f0.5 -JM15c -Ba -png hawaii

produces this image (notice the presence of shadows)

github-actions · 2026-09-25T23:13:33Z

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	test/baseline/grdimage/pbr.ps
added	test/baseline/grdview/pbr.ps
modified	test/baseline/grdimage/
modified	test/baseline/grdview/

Image diff(s)

Details

Added images

test/baseline/grdimage/pbr.png

test/baseline/grdview/pbr.png

Modified images

Path	Old	New

Report last updated at commit af7f78b

Esteban82

I got the same map.

seisman · 2026-09-26T02:42:20Z

+**-F**\ *azim*/*elev*\ [**+f**\ *fill*][**+i**\ *ior*][**+l**\ *light*][**+m**\ *metallic*][**+o**\ [*radius*]][**+r**\ *roughness*][**+s**][**+t**][**+v**\ *ve*]
+    Shade the grid with physically based lighting instead of illuminating it with |-I| (the two
+    cannot be combined). The shaded image is made on the grid's own nodes and then projected and
+    plotted as any image, so |-A|, |-E| and |-J| work as usual. Use **-I+f** as a short form that


The new shading looks good, but why support -I+f? Can we just use -F with no arguments to mean using the default settings?

The idea was to give the -I, that I believe is very embedded in users memory, a quick shortcut to also use this new illumination. But you are right that at least, -F should do that too. To be honest, I don't even like the idea to introduce a new letter to do illuminations but at the time the idea to overload the -I with all new -F flags seemed bad idea. But now I'm not so sure anymore. What do you guys think of dropping -F and letting -I take the extra burden like in (the P is from the PBR method name)

-I+P[azim/elev+...]

What do you guys think of dropping -F and letting -I take the extra burden like in (the P is from the PBR method name)

The two shadings have totally different modifiers. Combining them into one flag will make the documentation difficult to read.

So -F and -I are mutually exclusive, or is -F a modifier for -I? (I see now that the docs says ‘cannot be combined’). Adding a new option (-F) for illumination might be confusing, but so is creating a -I monster with dizzying amount of modifiers. What confuses the least..?

Ps: very nice to see a new illumination method!

Andreas, you summarized it well. What confuses less?

No strong opinion here, but I lean towards -F. It might also help to add a cross-reference in the -I docs pointing to the -F shading method, so users searching under either option find the other.

Adding a new option (-F) for illumination might be confusing, but so is creating a -I monster with dizzying amount of modifiers. What confuses the least..?

I think adding the new feature into -I is more confusing. With so many modifiers, it would be very confusing that which modifiers controls the normal shading, and which modifiers belong to the new shading.

Ideally, I prefer adding it to -I ('all illumination is given by -I'), but in practice, as you're saying, it's probably best to create the -F option.

If we were going to reuse the -I we it have to show up in the docs in a way similar to this

-I[file|intens|+aazimuth][+d][+mambient][+nargs]
or, for PBR shading

-I+P[azim /elev][+f fill ][+i ior ][+l light ][+m metallic ][+o[ radius ]][+r roughness ][+s][+t][+v ve ]

Maybe this would not be very confusing. And to be honest I would even drop from the docs the [+mambient][+nargs] from first form. It is far from clear whet they do and I doubt any one is using it.

Let the full -F be also set via -I+P[...]

joa-quim · 2026-09-29T12:37:11Z

I have updated the PR so we can try better the -I, -F functionality. Now both -I+P[...] and -F[...] works and the the -I man page explains that it can do both (the old) and the new syntax. Add to this that I also extended the PBR shading to grd2kml and in it the -F letter is already taken so we cannot make it do -P

For some reason I can no longer build any documentation.

C:\v\build>ninja docs_html
ninja: error: unknown target 'docs_html'

joa-quim · 2026-09-30T09:52:53Z

I'm leaning to strip the -F option and leave the PBR shading on -I like I explained above. Please say if still think that it makes -I too confusing. As I said unfortunately I cannot rebuild the docs anymore so can't see how the -I shows up in the man page.

joa-quim · 2026-09-30T23:29:49Z

Ok, no voices against this -I form, I'll merge it.

joa-quim added 4 commits September 24, 2026 13:27

Add grdimage pbr test

c669fed

Add PBR shading fter the shading methos used by the VTL library

e762230

add them

3879259

Simplify PBR example shading in man pages examples.

623d037

joa-quim requested a review from a team September 25, 2026 23:10

joa-quim changed the title ~~Add Physics Based Shading (PBR) shading method to grdimage and grdview~~ Add Physics Based Rendering(PBR) shading method to grdimage and grdview Sep 25, 2026

joa-quim changed the title ~~Add Physics Based Rendering(PBR) shading method to grdimage and grdview~~ Add Physics Based Rendering (PBR) shading method to grdimage and grdview Sep 25, 2026

Esteban82 added new feature PR that implements a new feature or capability in GMT add-changelog Add PR to the changelog labels Sep 26, 2026

Esteban82 approved these changes Sep 26, 2026

View reviewed changes

seisman reviewed Sep 26, 2026

View reviewed changes

Expand the PBR shading to grd2kml.c

80ff2ba

Let the full -F be also set via -I+P[...]

Remove the option -F and overload -I with it

af7f78b

joa-quim merged commit bd4f479 into master Sep 30, 2026
17 of 20 checks passed

joa-quim deleted the PBR-shading branch September 30, 2026 23:30

Conversation

joa-quim commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of changed images

Image diff(s)

Added images

Modified images

Uh oh!

Esteban82 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anbj Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joa-quim commented Sep 29, 2026

Uh oh!

joa-quim commented Sep 30, 2026

Uh oh!

joa-quim commented Sep 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

joa-quim commented Sep 25, 2026 •

edited

Loading

github-actions Bot commented Sep 25, 2026 •

edited

Loading

anbj Sep 28, 2026 •

edited

Loading