Add support for mesh and surface #953

almarklein · 2025-11-28T09:41:37Z

Closes #487, closes #917, ref #959

Add MeshGraphgic
Add plot.add_mesh() and plot.add_surface().
Add light to a scene by default.
Add examples.
Support for 2D colormaps.
This relies more on PyGfx colormap mechanics. I am not sure why fastplotlib 'renders' its own colormap into vertex colors for lines and scatter.

Possible upstream (pygfx) improvements:

Support for clim everywhere where a map is supported.
Possibility to set map as a numpy array?

almarklein · 2025-11-28T11:13:48Z

I cannot find the new screenshots. Do I need to whitelist the new examples/mesh dir somewhere?

github-actions · 2025-11-28T11:16:53Z

📚 Docs preview built and uploaded! https://www.fastplotlib.org/ver/mesh

kushalkolar · 2025-11-28T18:51:22Z

Good start!

_graphic_methods_mixin.py is meant to be auto-generated, so we should make a SurfaceGraphic that probably just subclasses MeshGraphic.

Working on figuring out how to make the surface data dynamically settable so we can have a data @property. I think all the properties should be mutable like the other graphics where it make sense.

For general mesh:

positions
indices
mapcoords
cmap
colors

For surface:

data (which under the hood computes positions, indices, mapcoords)
cmap
colors

~~Seems like the normals have to be re-computed if using phong material when positions change. No difference with basic.~~ Edit: Can just set the material.map again. Is there a flag for this we can set?

~~Anyways, I think we can make the basic material mode as the default and also allow phong and slice.~~ Nah phong default seems best for most functions.

Are morph targets useful for this? Or just setting the position directly is the way to go?

I'm not sure if any of the existing "2D" selectors are useful here, in the future we could make a "cube selector", maybe based on the pygfx gizmo example using an expandable cube that can be used to select the triangles inside the cube?

Other than that that #545 might be useful here when it's available, and we could also make a selector that just allows selecting faces on a mesh (I think pygfx has an example for this, but we could maybe make a easy way to Cntrl + Click to build a selection?). Anyways not a priority for now, just thoughts.

kushalkolar · 2025-11-28T22:07:50Z

I'm going to add a few commits to this branch based on #953 (comment)

fastplotlib/graphics/mesh.py

fastplotlib/layouts/_graphic_methods_mixin.py

kushalkolar · 2025-11-29T00:38:18Z

fastplotlib/layouts/_plot_area.py

+        self.scene.add(pygfx.AmbientLight())
+        self.scene.add(self._camera.add(pygfx.DirectionalLight()))


I think these can be settable properties of the PlotArea

mmm ... Having an ambient light and one directional light on the camera is a sweet default that makes sure phong-shaded meshes look good. A user that wants custom lights will probably want to add more lights to the scene, and control on which objects they are attached. That would be tricky to expose as a prop, I think?

FWIW these lights add negligible overhead for objects that don't use lights.

I think it's useful to have easy access to them though, and if a new camera is set on the PlotArea it needs to get the directional light. This is what I mean:

https://github.com/fastplotlib/fastplotlib/pull/953/files#diff-2a0f782c81512ab17081f35fd6cac201fafd429eded696cb76981946bc6baaecR120-R294

Ah I see. Nice fix!

fastplotlib/layouts/_graphic_methods_mixin.py

kushalkolar · 2025-12-01T04:49:22Z

I cannot find the new screenshots. Do I need to whitelist the new examples/mesh dir somewhere?

example dirs for tests are listed here:

fastplotlib/examples/tests/testutils.py

Lines 18 to 34 in 7b4c687

    
           # examples live in themed sub-folders 
        
           example_globs = [ 
        
               "image/*.py", 
        
               "image_volume/*.py", 
        
               "image_widget/*.py", 
        
               "heatmap/*.py", 
        
               "scatter/*.py", 
        
               "line/*.py", 
        
               "line_collection/*.py", 
        
               "vectors/*.py" 
        
               "gridplot/*.py", 
        
               "window_layouts/*.py", 
        
               "events/*.py", 
        
               "selection_tools/*.py", 
        
               "misc/*.py", 
        
               "guis/*.py", 
        
           ]

Did you automate finding them in pygfx?

Similarly for docs that dir needs a readme, making these changes in #954

kushalkolar · 2025-12-02T02:45:55Z

This relies more on PyGfx colormap mechanics. I am not sure why fastplotlib 'renders' its own colormap into vertex colors for lines and scatter.

pygfx.cm.create_colormap() didn't exist when we implemented lines and scatter, is this what you mean?

Edit: I see LineMaterial.map which can be a TextureMap. Is it possible to apply what we call a "cmap transform" as well, for instance in this example it samples from the colormap using the y-values of a sine function: https://www.fastplotlib.org/ver/dev/_gallery/line/line_cmap.html#sphx-glr-gallery-line-line-cmap-py

But this can be arbitrary, we often use it to indicate things like velocity along a 2d trajectory.

I cannot find the new screenshots. Do I need to whitelist the new examples/mesh dir somewhere?

a comma was also missing, added it , slipped by in the vectors PR

* mesh with gfeatures * surface graphic works * update, add PolygonGraphic, works * black * for docs and test screenshots * black * polygon data updating works * update * black * more examples * update add_graphic mixin * code review changes * fix * better polygon example

fastplotlib/graphics/mesh.py

fastplotlib/graphics/features/_mesh.py

almarklein · 2025-12-03T10:26:58Z

pygfx.cm.create_colormap() didn't exist when we implemented lines and scatter, is this what you mean?

Edit: I see LineMaterial.map which can be a TextureMap. Is it possible to apply what we call a "cmap transform" as well, for instance in this example it samples from the colormap using the y-values of a sine function: https://www.fastplotlib.org/ver/dev/_gallery/line/line_cmap.html#sphx-glr-gallery-line-line-cmap-py

Ah, create_colormap() not existing at the time explains it. Though it would be nice if fpl could simply leverage Pygfx's colormap support, by setting geometry.texcoords and material.map.

If I understand correctly, the current line's geometrytexcoords are simply the vertex indices, and map_transform is used to map that to real values. So in fact, the current map_transform is the mapcoords. Which is good news, I guess, because it means moving to pygfx doing the colormapping should be relatively easy (in a different pr).

edit: easy as in not that complex. Still quite a bit of work, I imagine.

fastplotlib/graphics/features/_mesh.py

kushalkolar · 2025-12-04T04:00:21Z

If I understand correctly, the current line's geometrytexcoords are simply the vertex indices, and map_transform is used to map that to real values. So in fact, the current map_transform is the mapcoords. Which is good news, I guess, because it means moving to pygfx doing the colormapping should be relatively easy (in a different pr).

Yes! Thanks I understand it better now :)

…o mesh

kushalkolar · 2025-12-04T05:56:05Z

@almarklein I think this is done 🥳 . Let me know what you think

almarklein · 2025-12-04T08:41:46Z

I was getting ready to update the buffer resizing logic for the poly data, but saw you already fixed that too. Awesome! Ready from my end then! 👍

almarklein added 5 commits November 28, 2025 10:28

Add support for mesh and surface

00b7ccf

restore line example

d944f55

Implement image-surface example

d4897b4

Fix 3D camera for mesh examples

99d00aa

Just remove selector logic for now

3505005

almarklein marked this pull request as ready for review November 28, 2025 11:00

almarklein requested review from clewis7 and kushalkolar as code owners November 28, 2025 11:00

new examples in gallery

c93b13f

kushalkolar reviewed Nov 29, 2025

View reviewed changes

kushalkolar mentioned this pull request Nov 29, 2025

mesh with graphic features #954

Merged

kushalkolar reviewed Nov 30, 2025

View reviewed changes

fastplotlib/layouts/_graphic_methods_mixin.py Outdated Show resolved Hide resolved

kushalkolar mentioned this pull request Dec 1, 2025

PolygonGraphic improvements #957

Open

kushalkolar added 9 commits December 1, 2025 21:52

remove unused import

8bac8b9

update graphics mixin

83ac73d

docs

fbecf03

black

2ccd785

don't need to set limit for docs gen

5dfdb08

add missing comma

2ddb97f

dont run terrain example

a4eecea

new screenshots

c3c528e

kushalkolar reviewed Dec 2, 2025

View reviewed changes

fastplotlib/graphics/mesh.py Show resolved Hide resolved

fastplotlib/graphics/features/_mesh.py Outdated Show resolved Hide resolved

kushalkolar mentioned this pull request Dec 3, 2025

Improvements to mesh graphics #959

Open

4 tasks

remove (i expect) unnecessary check

8344216

almarklein commented Dec 3, 2025

View reviewed changes

fastplotlib/graphics/features/_mesh.py Outdated Show resolved Hide resolved

lights as properties

1c6dbde

kushalkolar mentioned this pull request Dec 4, 2025

Use pygfx material.map directly for cmap and cmap_transform #960

Open

kushalkolar added 6 commits December 3, 2025 23:04

just use VertexPositions

14159ef

Merge branch 'mesh' of https://github.com/fastplotlib/fastplotlib int…

bf29ba2

…o mesh

Merge branch 'main' into mesh

26533b9

update PolyData

c60fe31

I need to use precommit

9d3a007

update api docs

868ee95

almarklein mentioned this pull request Dec 4, 2025

Add uniform.maprange to (almost) all objects that have .map pygfx/pygfx#1246

Merged

kushalkolar approved these changes Dec 4, 2025

View reviewed changes

kushalkolar merged commit db49c62 into main Dec 4, 2025
36 checks passed

		self.scene.add(pygfx.AmbientLight())
		self.scene.add(self._camera.add(pygfx.DirectionalLight()))

Add support for mesh and surface #953

Add support for mesh and surface #953

Uh oh!

Conversation

almarklein commented Nov 28, 2025 • edited by kushalkolar Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

almarklein commented Nov 28, 2025

Uh oh!

github-actions bot commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kushalkolar commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kushalkolar commented Nov 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kushalkolar Nov 29, 2025

Choose a reason for hiding this comment

Uh oh!

almarklein Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

kushalkolar Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

almarklein Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kushalkolar commented Dec 1, 2025

Uh oh!

kushalkolar commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

almarklein commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

kushalkolar commented Dec 4, 2025

Uh oh!

kushalkolar commented Dec 4, 2025

Uh oh!

almarklein commented Dec 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

almarklein commented Nov 28, 2025 •

edited by kushalkolar

Loading

github-actions bot commented Nov 28, 2025 •

edited

Loading

kushalkolar commented Nov 28, 2025 •

edited

Loading

kushalkolar commented Dec 2, 2025 •

edited

Loading

almarklein commented Dec 3, 2025 •

edited

Loading