Sphere billboard (Impostor) by m-agour · Pull Request #1037 · fury-gl/fury

m-agour · 2025-09-28T17:31:59Z

Adding first billboard-based actor to Fury (based on #1036). It uses the lighing system and have depth almost as normal gemetry-based sphere. I put it under the sphere actor with a flag imposter (name is up to change).

Here is a super cool video of the super cool impostor:

2025-09-28.13-30-23.mp4

Update (fixed light direction; compare with previoue old video):

2025-09-29.15-44-19.mp4

it looks real to me

example:

import numpy as np
from fury import actor
from fury import window

centers = np.array([[0, 0, 0], [2, 0, 2], [-1, 0, 0]])
colors = np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])
radii = np.array([1.2, 1, 1])

billboard = actor.sphere(
    centers=centers, colors=colors, radii=radii, opacity=1, impostor=True
)
sphere = actor.sphere(
    centers=centers + np.array([[0, -2, 0]]), colors=colors, radii=radii, opacity=1
)

scene = window.Scene()
scene.add(billboard)
scene.add(sphere)

txt_billboard = actor.text(
    "Shader (billboard)", position=[-5, 0, 0], colors=(1, 1, 1), anchor="middle-right"
)
txt_sphere = actor.text(
    "Geometry-based", position=[-5, -4, 0], colors=(1, 1, 1), anchor="middle-right"
)
scene.add(txt_billboard)
scene.add(txt_sphere)

scene.add(actor.box(
    centers=np.array([[0, -2, 0]]), colors=(0.5, 0.5, 0.5), scales=(7, 0.1, 7)
))
scene.add(actor.box(
    centers=np.array([[0, 0, 0]]), colors=(0.5, 0.5, 0.5), scales=(7, 0.1, 7)
))

showm = window.ShowManager(
    scene=scene, size=(600, 600), title="Billboard Sphere Example"
)
showm.start()

Copilot

Pull Request Overview

This PR adds billboard-based sphere impostor functionality to the Fury rendering library, providing a performance alternative to geometry-based spheres using shader techniques and camera-facing quads.

Implements billboard rendering system with WGSL shaders that always face the camera
Adds sphere impostor mode that renders 3D-looking spheres using 2D quads with ray-sphere intersection
Integrates billboard functionality into existing sphere actor with an impostor flag

Reviewed Changes

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

Show a summary per file

File	Description
fury/wgsl/billboard_sphere_render.wgsl	WGSL shader for rendering sphere impostors with lighting and depth
fury/wgsl/billboard_render.wgsl	Basic WGSL shader for camera-facing billboard quads
fury/tests/test_billboard.py	Comprehensive test suite for billboard and sphere impostor functionality
fury/shader.py	Billboard shader classes for rendering pipeline integration
fury/material.py	Material classes for billboard and sphere impostor rendering
fury/actor/curved.py	Modified sphere function to support impostor mode
fury/actor/billboard.py	Core billboard implementation with factory functions
fury/actor/init.pyi	Type stub updates for billboard exports

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

fury/wgsl/billboard_sphere_render.wgsl

Copilot · 2025-09-30T12:52:43Z

fury/actor/curved.py

    scales = radii
    directions = (1, 0, 0)

    vertices, faces = fp.prim_sphere(phi=phi, theta=theta)
-    return actor_from_primitive(
+    obj = actor_from_primitive(


The variable scales is set to radii but should be set to radii_arr for consistency with the processed array data used elsewhere in the function.

fury/actor/curved.py

maharshi-gor

Thank you for the work @m-agour !

Let's fix some simple changes in the sphere method.

fury/actor/curved.py

m-agour · 2025-09-30T16:32:03Z

Thank you for the work @m-agour !

Let's fix some simple changes in the sphere method.

Thank you @maharshi-gor, updated are made!

Garyfallidis · 2025-10-03T13:53:24Z

Great work.
Double check front back coloring. Intersection seems working well.
Also animate and add example.
Figure out maximum number of spheres that can be rendered.

skoudoro · 2025-11-18T15:25:37Z

What is the update on this @m-agour ? can you fix conflict and address Elef comments

guaje · 2025-12-12T12:37:33Z

@m-agour thanks for putting this together! Here are some comments/suggestions:

Could you rebase this branch?
Can you add a test for create_billboard_sphere?
Can you add a test for register_billboard_sphere_render_function?
Can you add a test for the sphere function in curved.py that tests impostor=True and impostor=False?

In addition to this, is there a way to merge or extend billboard_render.wsgl with Jinja templates or similar, so that we avoid the duplication of code in billboard_sphere_render.wsgl?

m-agour · 2026-01-26T16:29:46Z

Hi @maharshi-gor ready for review

maharshi-gor

Thank you for this work @m-agour . Please look at the provided comments on the PR.

maharshi-gor · 2026-02-06T15:17:15Z

fury/actor/billboard.py

 import numpy as np

-from fury.actor import Mesh
+from fury.actor.core import Mesh


Suggested change

from fury.actor.core import Mesh

from fury.actor import Mesh

maharshi-gor · 2026-02-06T15:17:46Z

fury/actor/billboard.py


+__all__ = ["billboard", "billboard_sphere", "Billboard"]


Suggested change

__all__ = ["billboard", "billboard_sphere", "Billboard"]

Let's add them to __init__.pyi, Not required here.

maharshi-gor · 2026-02-06T15:28:23Z

fury/actor/billboard.py

+    stored on ``billboard_sizes`` and reused by shaders for impostor variants.
+    """
+
+    pass


Let's make billbord_count, billboard_centers and billboard_sizes as properties in the Billboard actor so it stays consistent across. If someone tries to use BillBoard actor directly without _create_billboard_actor method.

There a few more on the sphere actor, I would leave it to you how to best represent them. If you want the user to use those properties. They should be available in the object definition.

maharshi-gor · 2026-02-06T15:29:21Z

fury/actor/__init__.pyi

 ]

-from .billboard import billboard
+from .billboard import billboard, billboard_sphere  # noqa: F401


No need for #noqa: F401

maharshi-gor · 2026-02-06T15:29:56Z

fury/actor/billboard.py

+        Tuple containing the configured
+        :class:`~fury.shader.BillboardSphereShader`.
+    """
+    from fury.shader import BillboardSphereShader


Please do not import like this. Move this import on top of the file.

maharshi-gor · 2026-02-06T15:30:10Z

fury/actor/billboard.py

@@ -126,3 +231,23 @@ def register_billboard_render_function(wobject):
    from fury.shader import BillboardShader


Update here as well.

maharshi-gor · 2026-02-06T15:36:29Z

fury/wgsl/billboard_render.wgsl

    // Load color if available - colors are duplicated 6x like positions
    let color = load_s_colors(billboard_index * 6);
    varyings.color = vec4<f32>(color, 1.0);
+    varyings.texcoord_vert = vec2<f32>(tex_coord);


Where do we use it?

…` actor

…ision

m-agour · 2026-02-23T19:28:55Z

Hi @maharshi-gor, thanks for the review, I have them all addressed! also added impostor sphere to tru by default.

m-agour · 2026-02-24T06:17:46Z

@m-agour thanks for putting this together! Here are some comments/suggestions:

Could you rebase this branch?

Can you add a test for create_billboard_sphere?

Can you add a test for register_billboard_sphere_render_function?

Can you add a test for the sphere function in curved.py that tests impostor=True and impostor=False?

In addition to this, is there a way to merge or extend billboard_render.wsgl with Jinja templates or similar, so that we avoid the duplication of code in billboard_sphere_render.wsgl?

Hi @guaje , sorry for the late response. I completely missed your review and that’s on me.
Thanks for the suggestions they’re helpful. I’m working through the tests you requested

maharshi-gor · 2026-02-25T16:25:50Z

Thanks @m-agour for the great work. LGTM Merging!

m-agour added the v2 label Sep 28, 2025

m-agour requested review from maharshi-gor and skoudoro September 28, 2025 19:53

m-agour force-pushed the sphere-billboard branch from 7707f89 to 6eabff0 Compare September 29, 2025 19:29

m-agour requested a review from Copilot September 30, 2025 12:51

Copilot AI reviewed Sep 30, 2025

View reviewed changes

maharshi-gor reviewed Sep 30, 2025

View reviewed changes

fury/actor/curved.py Outdated Show resolved Hide resolved

fury/actor/curved.py Outdated Show resolved Hide resolved

fury/actor/curved.py Show resolved Hide resolved

fury/actor/curved.py Outdated Show resolved Hide resolved

m-agour force-pushed the sphere-billboard branch from fdeb9ae to fffe69b Compare September 30, 2025 16:26

m-agour force-pushed the sphere-billboard branch 2 times, most recently from fbc4532 to 882c804 Compare October 14, 2025 13:49

m-agour force-pushed the sphere-billboard branch 2 times, most recently from e46ee44 to 327387a Compare January 26, 2026 15:34

maharshi-gor requested changes Feb 6, 2026

View reviewed changes

m-agour added 11 commits February 23, 2026 14:23

NF: added billboard sphere actor

91f76d6

RF: merge "geometic-based" and "imposter" sphjeres under `fury.sphere…

1be413f

…` actor

RF: updated billboard actor and material documentation

df85d49

RF: use camera ray for impostor sphere lighting

e430f1b

DOC: fix BillboardMaterial kwargs docstring

0081b7a

FIX: improved billboard sphere implementation

cb5779a

DOCS: Add billboard spheres example and fix lazy loader issue

10e208c

FIX: Use lazy import for billboard to avoid module/function name coll…

39e7633

…ision

BF: fix billboard_sphere function name

f33daba

RF: addressed PR reviews

693a9e4

RF: use impostor sphere by default

2cfc870

m-agour force-pushed the sphere-billboard branch from 327387a to 2096f22 Compare February 23, 2026 19:27

m-agour force-pushed the sphere-billboard branch from 2096f22 to a792212 Compare February 23, 2026 22:46

DOCS: updated examples and tests to adapt to impostor sphere

440cbcb

m-agour force-pushed the sphere-billboard branch from a792212 to 440cbcb Compare February 23, 2026 22:53

RF: removed annotation import as fury support 3.11+

17c7568

maharshi-gor merged commit c6ba464 into fury-gl:v2 Feb 25, 2026
22 checks passed

		@@ -126,3 +231,23 @@ def register_billboard_render_function(wobject):
		from fury.shader import BillboardShader

Conversation

m-agour commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maharshi-gor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

m-agour commented Sep 30, 2025

Uh oh!

Garyfallidis commented Oct 3, 2025

Uh oh!

skoudoro commented Nov 18, 2025

Uh oh!

guaje commented Dec 12, 2025 • edited by m-agour Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

m-agour commented Jan 26, 2026

Uh oh!

maharshi-gor 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!

Choose a reason for hiding this comment

Uh oh!

m-agour commented Feb 23, 2026

Uh oh!

m-agour commented Feb 24, 2026

Uh oh!

maharshi-gor commented Feb 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

m-agour commented Sep 28, 2025 •

edited

Loading

guaje commented Dec 12, 2025 •

edited by m-agour

Loading