Skip to content

Refactor handling of alpha #873

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Refactor handling of alpha #873

wants to merge 1 commit into from

Conversation

almarklein
Copy link
Collaborator

Context

Previously, Pygfx automatically distinguished between opaque and transparent fragments on a per-fragment level. With the new blending in Pygfx (current main), this distinction will have to be made per object. This means that somewhere a decision will have to be made whether an object is opaque or transparent.

This decision will not be made by Pygfx, except (perhaps) for a few common cases. In Fastplotlib we could make this decision by examining the provided data (i.e. does it have alpha values < 1?). But we could also decide to let the user decided. In that case we'd document that the user should set something like graphic.alpha_mode='blend' when they want their object to be transparent.

To be honest, I don't know yet what the best approach is. I have a tendency to want to make it easy for end-users. But forcing users to make the decision will make them more aware of blending, and of the other options for blending (like stochastic or weighted transparency).

In this PR I've made some changes, but more to get a feeling of how Fastplotlib currently uses color and to understand how the end-user API will be affected by our choice in this matter.

Places where users can introduce transparency

(Let me know if I missed one!)

  • the graphic's alpha argument.
  • alpha in colormaps.
  • alpha in a uniform color
  • alpha in per-point colors.
  • alpha in image pixels.

Ideas

Some ideas, some compatible, some mutually exclusive:

  • The alpha value passed to the graphic could be used to set world_object.material.opacity.
  • Also allow RGB colors, and maybe even promote that a bit over RGBA.
  • Automatically make a graphic transparent when alpha < 1. Easy to do either in fpl or pygfx. Covers quite some use-cases.
    • Somewhat intuitive: people who wonder why their transparent image is opaque may set alpha and see that it works then. Then they can set it to 0.999 to fix it.
  • For other cases (e.g. images or per-point colors), require setting alpha_mode.
    • A bit harder on users, but easy enough to document?
  • Or check the alpha values in images and colorlists, and automatically set the alpha_mode when values < 1 are present.
    • Makes it easier for users, but adds complexity and possible source of bugs.
  • Default to "dither", which always works. Then users can set alpha_mode="blend" for smoother results of transparent objects.

cc @Korijn because this is is a topic that touches both fpl and pygfx

kushalkolar
kushalkolar reviewed Jul 8, 2025
View reviewed changes
examples/gridplot/multigraphic_gridplot.py
2, 2, 8, 3,
1, 9, 1, 5
]
cmap_transform = [0, 1, 1, 2, 0, 0, 1, 1, 2, 2, 8, 3, 1, 9, 1, 5]
Copy link
Member

Choose a reason for hiding this comment

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

We don't black the examples because it's useful to manually set things like this list sometimes so the user has a better visual understanding.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

My IDE autoformats the whole file with Ruff. Maybe I can rewrite this as a list of lists to keep it square.

Copy link
Member

Choose a reason for hiding this comment

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

It's a 1d list that defines per color lines 🤔, anyways not too important for now, can fix later

@kushalkolar
Copy link
Member

kushalkolar commented Jul 8, 2025 •
edited
Loading

Thanks! Will check this in detail later today, but I wanted to mention this: #754

We want to make alpha a separate graphic feature and thus an entirely independent Graphic property (in general we're trying to make the constructor as symmetric as possible with the settable properties, just like pygfx) . This would probably be a good time to do that?

@almarklein
Copy link
Collaborator Author

We want to make alpha a separate graphic feature and thus an entirely independent Graphic property

Good to know this was already on the agenda! Yeah I think it makes sense both from an API perspective, but also technically; changing a color is fine, but changing an alpha value might affect how you want to blend things.

@almarklein almarklein mentioned this pull request Jul 10, 2025
Merged
6 tasks
@Korijn
Copy link

Korijn commented Jul 11, 2025 •
edited
Loading

Then they can set it to 0.999 to fix it.

This seems a bit awkward. I foresee users would complain about having to do this.

  • Or check the alpha values in images and colorlists, and automatically set the alpha_mode when values < 1 are present.

From your list of options, this seems most straight forward.

  • Default to "dither", which always works. Then users can set alpha_mode="blend" for smoother results of transparent objects.

After thinking about this for a while, I guess what I would expect from a 2D plotting library as a user:

  • All graphics have alpha_mode="blend"
  • Graphics are drawn in the order that I add them to the figure, transparent or not, so the depth buffer is kind of ignored I guess

I'm not sure if fastplotlib also does 3D plotting, but in that case I would expect it to behave as pygfx does naturally.

By the way, I appreciate you calling for my thoughts, so I'm sharing them here, but I really have not been keeping up with fastplotlib's development for a while, so take it with a grain of salt.

@kushalkolar
Copy link
Member

  • Or check the alpha values in images and colorlists, and automatically set the alpha_mode when values < 1 are present.

From your list of options, this seems most straight forward.

I'm leaning towards this as well.

After thinking about this for a while, I guess what I would expect from a 2D plotting library as a user:

  • Graphics are drawn in the order that I add them to the figure, transparent or not, so the depth buffer is kind of ignored I guess

When using an orthographic projection graphics are stacked in z.

I'm not sure if fastplotlib also does 3D plotting, but in that case I would expect it to behave as pygfx does naturally.

Everything is 3D just like pygfx, perspective camera for everything. We just don't have a high level API for meshes yet, I've rarely used meshes myself so I hope someone else would be able to contributre a high level API for that. Or maybe meshes are so specific that the pygfx level of abstraction is the best for it, I don't know yet.

@almarklein
Copy link
Collaborator Author

When using an orthographic projection graphics are stacked in z.

Do you mean that the objects are offset in their ob.local.z?

Is it possible to clearly identify whether the current graphic is in a 2D or 3D scene? If that is the case we could indeed default to blend.

Or maybe meshes are so specific

Haha!. Some Pygfx users consider meshes the "normal object" and think all the non-meshes are special 😉

@Korijn
Copy link

Korijn commented Jul 15, 2025

When using an orthographic projection graphics are stacked in z.

And what determines the stacking order? Insertion order?

@kushalkolar
Copy link
Member

kushalkolar commented Jul 15, 2025 •
edited
Loading

When using an orthographic projection graphics are stacked in z.

Do you mean that the objects are offset in their ob.local.z?

Yup!

When using an orthographic projection graphics are stacked in z.

And what determines the stacking order? Insertion order?

Yup. Though the z can be set when added, or later at any time.

Is it possible to clearly identify whether the current graphic is in a 2D or 3D scene? If that is the case we could indeed default to blend.

If camera.fov == 0

You can switch between them and it's something I do all the time when looking at low dimensional projections with lines and scatters.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kushalkolar kushalkolar kushalkolar left review comments

@clewis7 clewis7 Awaiting requested review from clewis7 clewis7 will be requested when the pull request is marked ready for review clewis7 is a code owner

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@almarklein @kushalkolar @Korijn