Rendering Functionals#

Rendering functionals convert tensor fields and geometric primitives into image buffers. They follow the same stateless functional pattern as the rest of physicsnemo.nn.functional: tensors in, tensors out, with implementation dispatch handled through FunctionSpec.

Isosurface Render#

physicsnemo.nn.functional.isosurface_render(
field: Tensor,
image_height: int,
image_width: int,
eye: Tensor | Sequence[float],
center: Tensor | Sequence[float],
up: Tensor | Sequence[float],
fov_y_degrees: float,
bounds_min: Tensor | Sequence[float],
bounds_max: Tensor | Sequence[float],
threshold: float = 0.0,
step_size: float = 0.01,
max_steps: int = 512,
color_field: Tensor | None = None,
surface_color: Tensor | None = None,
light_direction: Tensor | None = None,
ambient: float = 0.2,
*,
implementation: Literal['warp'] | None = None,
) → tuple[Tensor, Tensor, Tensor]#

Render a threshold isosurface from a scalar volume.

This is a fused image-space renderer: one Warp thread computes one output pixel, generates the camera ray, intersects the volume bounds, marches the scalar field, samples optional RGB/RGBA color data, shades the hit, and writes (rgba, depth, normal) buffers.

Parameters:

  • field – Scalar volume with shape (nx, ny, nz).

  • image_height – Output image height.

  • image_width – Output image width.

  • eye – Camera position with shape (3,).

  • center – Camera look-at point with shape (3,).

  • up – Camera up direction with shape (3,).

  • fov_y_degrees – Vertical field of view in degrees.

  • bounds_min – Minimum world-space volume bound with shape (3,).

  • bounds_max – Maximum world-space volume bound with shape (3,).

  • threshold – Isosurface scalar threshold. Defaults to 0.0.

  • step_size – Ray-marching step size in world units. Defaults to 0.01.

  • max_steps – Maximum number of march steps per pixel. Defaults to 512.

  • color_field – Optional RGB/RGBA volume with shape (nx, ny, nz, 3|4). uint8 colors are normalized to [0, 1].

  • surface_color – Optional uniform RGB/RGBA color used when color_field is omitted.

  • light_direction – Optional surface-to-light direction with shape (3,).

  • ambient – Ambient lighting coefficient in [0, 1].

  • implementation – Explicit implementation name. Currently only "warp" is registered.

Returns:

Tuple of (rgba, depth, normal) image tensors. Missed pixels have zero alpha, infinite depth, and zero normal.

Visualization

This animation ray-marches a moving sphere isosurface from a scalar field and colors the hit surface with an RGB volume.

Isosurface render animation of a moving sphere

Mesh Raycast#

physicsnemo.nn.functional.mesh_raycast(
mesh_vertices: Tensor,
mesh_indices: Tensor,
image_height: int,
image_width: int,
eye: Tensor | Sequence[float],
center: Tensor | Sequence[float],
up: Tensor | Sequence[float],
fov_y_degrees: float,
vertex_colors: Tensor | None = None,
face_colors: Tensor | None = None,
surface_color: Tensor | None = None,
light_direction: Tensor | None = None,
ambient: float = 0.2,
max_distance: float = 100000000.0,
*,
implementation: Literal['warp'] | None = None,
) → tuple[Tensor, Tensor, Tensor]#

Render a triangle mesh with Warp ray queries.

mesh_raycast builds a Warp Mesh acceleration structure from triangle vertices and indices, casts one camera ray per output pixel, and returns image-space (rgba, depth, normal) buffers. Mesh color may be uniform, per vertex, or per face. uint8 colors are accepted and normalized to [0, 1] internally.

Parameters:

  • mesh_vertices – Vertex positions with shape (num_vertices, 3).

  • mesh_indices – Triangle connectivity with shape (num_faces, 3) or a flattened equivalent.

  • image_height – Output image height.

  • image_width – Output image width.

  • eye – Camera position with shape (3,).

  • center – Camera look-at point with shape (3,).

  • up – Camera up direction with shape (3,).

  • fov_y_degrees – Vertical field of view in degrees.

  • vertex_colors – Optional RGB/RGBA colors with one color per vertex.

  • face_colors – Optional RGB/RGBA colors with one color per triangle.

  • surface_color – Optional uniform RGB/RGBA color used when per-element color arrays are omitted.

  • light_direction – Optional surface-to-light direction with shape (3,).

  • ambient – Ambient lighting coefficient in [0, 1].

  • max_distance – Maximum ray distance.

  • implementation – Explicit implementation name. Currently only "warp" is registered.

Returns:

Tuple of (rgba, depth, normal) image tensors. Missed pixels have zero alpha, infinite depth, and zero normal.

Visualization

This animation renders a rotating cube mesh with per-vertex colors.

Mesh raycast animation of a rotating colored cube

Scalar Field To RGBA#

physicsnemo.nn.functional.scalar_field_to_rgba(
field: Tensor,
vmin: float,
vmax: float,
max_opacity: float = 0.8,
opacity_threshold: float = 0.1,
*,
implementation: Literal['warp', 'torch'] | None = None,
) → Tensor#

Map a scalar volume to an RGBA transfer-function volume.

Parameters:

  • field – Scalar volume with shape (nx, ny, nz).

  • vmin – Scalar value mapped to the bottom of the transfer function.

  • vmax – Scalar value mapped to the top of the transfer function.

  • max_opacity – Maximum output alpha in [0, 1].

  • opacity_threshold – Normalized values below this threshold are transparent.

  • implementation – Explicit implementation name. "warp" is preferred; "torch" is available as a portable fallback.

Returns:

uint8 RGBA volume with shape (nx, ny, nz, 4).

Line Integral Convolution#

physicsnemo.nn.functional.line_integral_convolution(
vector_field: Tensor,
seed: Tensor,
step_size: float = 0.5,
num_steps: int = 20,
contrast: float = 1.4,
*,
implementation: Literal['warp'] | None = None,
) → Tensor#

Compute a 3D line integral convolution field.

Parameters:

  • vector_field – Vector field with shape (nx, ny, nz, 3).

  • seed – Scalar seed/noise field with shape (nx, ny, nz).

  • step_size – Integration step size in grid-index units.

  • num_steps – Number of integration steps in each direction.

  • contrast – Contrast multiplier around 0.5 for the output LIC field.

  • implementation – Explicit implementation name. Currently only "warp" is registered.

Returns:

LIC scalar field with shape (nx, ny, nz) and values in [0, 1].

Visualization

This animation shows a zoomed-out center slice through a 3D LIC field computed from a rotating dipole vector field. The LIC texture modulates a jet-colored field-magnitude image after starting from fixed random noise.

Line integral convolution animation of a rotating dipole field

This animation renders a steady 3D dipole LIC field as an RGBA volume with volume_render and overlays a rotating wireframe cube for spatial context.

Three-dimensional line integral convolution volume render with rotating cube

Vector Field To RGBA#

physicsnemo.nn.functional.vector_field_to_rgba(
vector_field: Tensor,
lic_field: Tensor,
vmin: float,
vmax: float,
max_opacity: float = 0.8,
lic_threshold: float = 0.5,
*,
implementation: Literal['warp', 'torch'] | None = None,
) → Tensor#

Map vector magnitude and LIC values to an RGBA volume.

Parameters:

  • vector_field – Vector field with shape (nx, ny, nz, 3).

  • lic_field – LIC scalar field with shape (nx, ny, nz).

  • vmin – Vector magnitude mapped to the bottom of the transfer function.

  • vmax – Vector magnitude mapped to the top of the transfer function.

  • max_opacity – Maximum output alpha in [0, 1].

  • lic_threshold – LIC values below this threshold are transparent.

  • implementation – Explicit implementation name. "warp" is preferred; "torch" is available as a portable fallback.

Returns:

uint8 RGBA volume with shape (nx, ny, nz, 4).

Volume Render#

physicsnemo.nn.functional.volume_render(
rgba_volume: Tensor,
image_height: int,
image_width: int,
eye: Tensor | Sequence[float],
center: Tensor | Sequence[float],
up: Tensor | Sequence[float],
fov_y_degrees: float,
bounds_min: Tensor | Sequence[float],
bounds_max: Tensor | Sequence[float],
step_size: float = 0.01,
max_steps: int = 512,
opacity_threshold: float = 0.95,
depth_threshold: float = 0.1,
*,
implementation: Literal['warp'] | None = None,
) → tuple[Tensor, Tensor]#

Render an RGBA volume with front-to-back ray marching.

Parameters:

  • rgba_volume – RGBA volume with shape (nx, ny, nz, 4). uint8 input is normalized to [0, 1] internally.

  • image_height – Output image height.

  • image_width – Output image width.

  • eye – Camera position with shape (3,).

  • center – Camera look-at point with shape (3,).

  • up – Camera up direction with shape (3,).

  • fov_y_degrees – Vertical field of view in degrees.

  • bounds_min – Minimum world-space volume bound with shape (3,).

  • bounds_max – Maximum world-space volume bound with shape (3,).

  • step_size – Ray-marching step size in world units.

  • max_steps – Maximum number of march steps per pixel.

  • opacity_threshold – Stop marching after this accumulated opacity.

  • depth_threshold – Accumulated opacity needed before depth is recorded.

  • implementation – Explicit implementation name. Currently only "warp" is registered.

Returns:

Tuple of (rgba, depth) image tensors.

Point Cloud Render#

physicsnemo.nn.functional.point_cloud_render(
points: Tensor,
image_height: int,
image_width: int,
eye: Tensor | Sequence[float],
center: Tensor | Sequence[float],
up: Tensor | Sequence[float],
fov_y_degrees: float,
point_colors: Tensor | None = None,
point_color: Tensor | None = None,
point_size: int = 1,
near: float = 0.01,
far: float = 100000000.0,
*,
implementation: Literal['warp'] | None = None,
) → tuple[Tensor, Tensor]#

Rasterize a 3D point cloud into RGBA and depth images.

The Warp implementation uses one pass to atomically select the nearest point per covered pixel and a second pass to resolve the winning color and depth.

Parameters:

  • points – Point positions with shape (num_points, 3).

  • image_height – Output image height.

  • image_width – Output image width.

  • eye – Camera position with shape (3,).

  • center – Camera look-at point with shape (3,).

  • up – Camera up direction with shape (3,).

  • fov_y_degrees – Vertical field of view in degrees.

  • point_colors – Optional RGB/RGBA colors with one color per point.

  • point_color – Optional uniform RGB/RGBA point color.

  • point_size – Square point size in pixels.

  • near – Near clip distance.

  • far – Far clip distance.

  • implementation – Explicit implementation name. Currently only "warp" is registered.

Returns:

Tuple of (rgba, depth) image tensors.

Wireframe Render#

physicsnemo.nn.functional.wireframe_render(
edges: Tensor,
image_height: int,
image_width: int,
eye: Tensor | Sequence[float],
center: Tensor | Sequence[float],
up: Tensor | Sequence[float],
fov_y_degrees: float,
line_color: Tensor | None = None,
line_thickness: int = 1,
near: float = 0.01,
far: float = 100000000.0,
*,
implementation: Literal['warp'] | None = None,
) → tuple[Tensor, Tensor]#

Rasterize 3D line segments into RGBA and depth images.

One Warp thread projects and rasterizes each segment. Depth writes are resolved atomically and all segments use the same line color.

Parameters:

  • edges – Line segments with shape (num_edges, 2, 3) or (num_edges, 6).

  • image_height – Output image height.

  • image_width – Output image width.

  • eye – Camera position with shape (3,).

  • center – Camera look-at point with shape (3,).

  • up – Camera up direction with shape (3,).

  • fov_y_degrees – Vertical field of view in degrees.

  • line_color – Optional uniform RGB/RGBA line color.

  • line_thickness – Line thickness in pixels.

  • near – Near clip distance.

  • far – Far clip distance.

  • implementation – Explicit implementation name. Currently only "warp" is registered.

Returns:

Tuple of (rgba, depth) image tensors.