Source code for sionna.rt.radio_materials.radio_material_base

#
# SPDX-FileCopyrightText: Copyright (c) 2021-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
"""Base class for implementing a radio material"""

import mitsuba as mi
import numpy as np
import matplotlib
from typing import Tuple
import weakref

from sionna.rt import scene as scene_module


[docs] class RadioMaterialBase(mi.BSDF): # pylint: disable=line-too-long r""" Base class to implement a radio material This is an abstract class that cannot be instantiated, and serves as interface for defining radio materials. A radio material defines how an object scatters incident radio waves. :param props: Property container storing the parameters required to build the material """ def __init__(self, props: mi.Properties): super().__init__(props) # Scene object that uses this radio material self._scene: weakref.ref[scene_module.Scene] = lambda: None # Read color from properties, if any color = None for pname in ("color", "reflectance", "base_color"): if pname in props: color = tuple(props[pname]) del props[pname] break if color is None: # If not specified, use an arbitrary value palette = matplotlib.colormaps.get_cmap("Pastel1") i = np.random.randint(low=0, high=palette.N) color = palette((i % palette.N + 0.5) / palette.N)[:3] self._color = color @property def scene(self): """Get/set the scene used by the radio material. Note that the scene can only be set once, until the material is removed from that scene. :type: :class:`~sionna.rt.Scene` """ return self._scene() @scene.setter def scene(self, scene: mi.Scene): if not isinstance(scene, scene_module.Scene): raise ValueError("`scene` must be an instance of Scene") if (self._scene() is not None) and (self._scene() is not scene): raise ValueError(f"Radio material ('{self.name}') already used by" " another scene.") self._scene = weakref.ref(scene) def _detach_from_scene(self) -> None: r""" Clears the reference to the scene to which this material belonged This is called when the material is removed from a scene, so that it can subsequently be used by another one. """ self._scene = lambda: None @property def name(self): r""" (read-only) Name of the radio material :type: :py:class:`str` """ # If a prefix 'mat-' is used, it is removed. # This prefix is automatically added by the Mitsuba-Blender extension name = self.id() if name.startswith('mat-'): name = name[4:] return name @property def color(self): r""" Get/set the RGB (red, green, blue) color for the radio material as displayed in the previewer and renderer. Each RGB component must have a value within the range :math:`\in [0,1]`. :type: :py:class:`Tuple[float, float, float]` """ return self._color @color.setter def color(self, new_color: Tuple[float, float, float]): if len(new_color) != 3: raise ValueError( "Color must be a tuple of three RGB components in the range [0, 1]" ) if min(new_color) < 0. or max(new_color) > 1.: raise ValueError("Color components must be in the range [0, 1]") self._color = (float(new_color[0]), float(new_color[1]), float(new_color[2])) @property def is_used(self) -> bool: r""" (read-only) Return `True` if at least one object in the scene uses this material This is evaluated from the objects currently in the scene, and therefore only accounts for objects that are part of it: an object that was removed from the scene no longer uses its material. :type: :py:class:`bool` """ scene = self.scene if scene is None: return False return any(o.radio_material is self for o in scene.objects.values()) # pylint: disable=unused-argument
[docs] def sample( self, ctx: mi.BSDFContext, si: mi.SurfaceInteraction3f, sample1: mi.Float, sample2: mi.Point2f, active: bool | mi.Bool = True ) -> Tuple[mi.BSDFSample3f, mi.Spectrum]: # pylint: disable=line-too-long r""" Samples the radio material This function samples an interaction type (e.g., specular reflection, diffuse reflection, refraction, or diffraction) and direction of propagation for the scattered ray, and returns the corresponding radio material sample and Jones matrix. The returned radio material sample stores the sampled type of interaction, sampled direction of propagation of the scattered ray, and the probability that the selected interaction was sampled. The following assumptions are made on the inputs: - ``ctx.component`` is a binary mask that specifies the types of interaction enabled. Booleans can be obtained from this mask as follows: .. code-block:: python specular_reflection_enabled = (ctx.component & InteractionType.SPECULAR) > 0 diffuse_reflection_enabled = (ctx.component & InteractionType.DIFFUSE) > 0 refraction_enabled = (ctx.component & InteractionType.REFRACTION) > 0 diffraction_enabled = (ctx.component & InteractionType.DIFFRACTION) > 0 - ``si.wi`` is the direction of propagation of the incident wave in the local frame - ``si.sh_frame`` is the surface frame where ``sh_frame.n`` is the normal to the intersected surface in the world coordinate system - ``si.dn_du`` stores the edge vector in the local frame. This is only used for diffraction. - ``si.dn_dv`` stores the normal to the n-face in the local frame. This is only used for diffraction. - ``si.dp_du`` stores the distance from the diffraction point to the source, the distance from the diffraction point to the receiver, and the flags indicating the enabled interaction types. The first two components are only used when diffraction is sampled. - ``si.duv_dx`` and ``si.duv_dy`` stores the incident field - ``si.t`` stores the solid angle of the incident ray tube. Note that all quantities related to diffraction are integrated to the paths only if diffraction is sampled. The outputs are set as follows: - ``bs.wo`` is the direction of propagation of the sampled scattered ray in the world frame - ``bs.sampled_component`` is the sampled interaction type - ``bs.pdf`` is the probability of the sampled interaction type - ``jones_mat`` is the Jones matrix describing the transformation incurred to the incident wave in the implicit world frame :param ctx: A context data structure used to specify which interaction types are enabled :param si: Surface interaction data structure describing the underlying surface position :param sample1: A uniformly distributed sample on :math:`[0,1]` used to sample the type of interaction :param sample2: A uniformly distributed sample on :math:`[0,1]^2` used to sample the direction of the reflected wave in the case of diffuse reflection, or the direction of the diffracted ray on the Keller cone :param active: Mask to specify active rays :return: Radio material sample and Jones matrix as a :math:`4 \times 4` real-valued matrix """ return ...
[docs] def eval( self, ctx: mi.BSDFContext, si: mi.SurfaceInteraction3f, wo: mi.Vector3f, active: bool | mi.Bool = True ) -> mi.Spectrum: # pylint: disable=line-too-long r""" Evaluates the radio material This function evaluates the Jones matrix of the radio material for the scattered direction ``wo`` and for the interaction type stored in ``si.dp_du.z``. - ``si.wi`` is the direction of propagation of the incident wave in the local frame - ``si.sh_frame`` is the surface frame where ``sh_frame.n`` is the normal to the intersected surface in the world coordinate system - ``si.dn_du`` stores the edge vector in the local frame. This is only used for diffraction. - ``si.dn_dv`` stores the normal to the n-face in the local frame. This is only used for diffraction. - ``si.dp_du`` stores the distance from the diffraction point to the source, the distance from the diffraction point to the receiver, and the interaction type. The first two components are only used when diffraction is sampled. - ``si.duv_dx`` and ``si.duv_dy`` stores the incident field - ``si.t`` stores the solid angle of the incident ray tube. :param ctx: A context data structure used to specify which interaction types are enabled :param si: Surface interaction data structure describing the underlying surface position :param wo: Direction of propagation of the scattered wave in the world frame :param active: Mask to specify active rays :return: Jones matrix as a :math:`4 \times 4` real-valued matrix """ return ...
[docs] def pdf( self, ctx: mi.BSDFContext, si: mi.SurfaceInteraction3f, wo: mi.Vector3f, active: bool | mi.Bool = True ) -> mi.Float: # pylint: disable=line-too-long r""" Evaluates the probability of the sampled interaction type and direction of scattered ray This function evaluates the probability density of the radio material for the scattered direction ``wo`` and for the interaction type stored in ``si.dp_du.z``. Note that the built-in :class:`~sionna.rt.RadioMaterial` returns the event probability only and does not use ``wo``. - ``si.wi`` is the direction of propagation of the incident wave in the local frame - ``si.sh_frame`` is the surface frame where ``sh_frame.n`` is the normal to the intersected surface in the world coordinate system - ``si.dn_du`` stores the edge vector in the local frame. This is only used for diffraction. - ``si.dn_dv`` stores the normal to the n-face in the local frame. This is only used for diffraction. - ``si.dp_du`` stores the distance from the diffraction point to the source, the distance from the diffraction point to the receiver, and the interaction type. The first two components are only used when diffraction is sampled. - ``si.duv_dx`` and ``si.duv_dy`` stores the incident field - ``si.t`` stores the solid angle of the incident ray tube. :param ctx: A context data structure used to specify which interaction types are enabled :param si: Surface interaction data structure describing the underlying surface position :param wo: Direction of propagation of the scattered wave in the world frame :param active: Mask to specify active rays :return: Probability density value """ return ...
[docs] def traverse(self, callback: mi.TraversalCallback): # pylint: disable=line-too-long r""" Traverse the attributes and objects of this instance Implementing this function is required for Mitsuba to traverse a scene graph, including materials, and determine the differentiable parameters. :param callback: Object used to traverse the scene graph """ return ...
[docs] def to_string(self) -> str: r""" Returns object description """ return ...