differt.scene.TriangleScene

differt.scene.TriangleScene#

class TriangleScene(transmitters=<factory>, receivers=<factory>, mesh=<factory>)[source]#

Bases: Module

A simple scene made of one or more triangle meshes, some transmitters and some receivers.

Attributes

`num_receivers`	The number of receivers.
`num_transmitters`	The number of transmitters.
`transmitters`	The array of transmitter vertices.
`receivers`	The array of receiver vertices.
`mesh`	The triangle mesh.

Methods

`compute_paths`([order, method, chunk_size, ...])	Compute paths between all pairs of transmitters and receivers in the scene, that undergo a fixed number of interaction with objects.
`from_core`(core_scene)	Return a triangle scene from a scene created by the `differt_core` module.
`from_mitsuba`(mi_scene)	Load a triangle scene from a Mitsuba scene object.
`from_sionna`(sionna_scene)	Load a triangle scene from a Sionna scene object.
`load_xml`(file)	Load a triangle scene from a XML file.
`plot`([tx_kwargs, rx_kwargs, mesh_kwargs])	Plot this scene on a 3D scene.
`rotate`(rotation_matrix)	Return a new scene by applying a rotation matrix to all the objects in the scene.
`scale`(scale_factor)	Return a new scene by applying a scale factor to all the objects in the scene.
`set_assume_quads`([flag])	Return a new instance of this scene with `TriangleMesh.assume_quads` set to `flag`.
`translate`(translation)	Return a new scene by applying a translation to all the objects in the scene.
`with_receivers_grid`([m, n, height])	Return a new instance of this scene with a 2D grid of receivers placed at a fixed height.
`with_transmitters_grid`([m, n, height])	Return a new instance of this scene with a 2D grid of transmitters placed at a fixed height.

Detailed documentation

compute_paths(order=None, *, method='exhaustive', chunk_size=None, num_rays=int(1e6), path_candidates=None, epsilon=None, hit_tol=None, min_len=None, max_dist=1e-3, smoothing_factor=None, confidence_threshold=0.5, batch_size=512, disconnect_inactive_triangles=False)[source]#

Compute paths between all pairs of transmitters and receivers in the scene, that undergo a fixed number of interaction with objects.

Note

Currently, only LOS and fixed order reflection paths are computed, using the image_method. More types of interactions and path tracing methods will be added in the future, so stay tuned!

Parameters:

order (int | None) –
The number of interaction, i.e., the number of bounces.

This or path_candidates must be specified.
method (Literal['exhaustive', 'sbr', 'hybrid']) –
The method used to generate path candidates and trace paths.

See Advanced Path Tracing for a detailed tutorial.
- If 'exhaustive', all possible paths are generated, performing an exhaustive search. This is the slowest method, but it is also the most accurate.
- If 'sbr', a fixed number of rays are launched from each transmitter and are allowed to perform a fixed number of bounces. Only rays paths passing in the vicinity of a receiver are considered valid, see max_dist parameter. This is the fastest method, but may miss some valid paths if the number of rays is too low.
  
  Important
  
  This method is currently unstable and not yet optimized, and it is likely to changed in future releases. Use with caution.
- If 'hybrid', a hybrid method is used, which estimates the objects visible from all transmitters, to reduce the number of path candidates, by launching a fixed number of rays, and then performs an exhaustive search on those path candidates. This is a faster alternative to 'exhaustive', but still grows exponentially with the number of bounces or the size of the scene. In the future, we plan on allowing the user to explicitly pass visibility matrices to further reduce the number of path candidates.
  
  Warning
  
  This method is best used for a single transmitter and a single receiver, as the estimated visibility is merged across all transmitters and receivers, respectively.
chunk_size (int | None) –
If specified, it will iterate through chunks of path candidates, and yield the result as an iterator over paths chunks.

Unused if path_candidates is provided or if method == 'sbr'.
num_rays (int) –
The number of rays launched with method == 'sbr' or method == 'hybrid'.

Unused if method == 'exhaustive'.
path_candidates (Int[ArrayLike, 'num_path_candidates order'] | None) –
An optional array of path candidates, see Generating path candidates.

This is helpful to only generate paths on a subset of the scene. E.g., this is used in Sampling Path Candidates with Machine Learning to test a specific set of path candidates generated from a Machine Learning model.

If self.mesh.assume_quads is True, then path candidates are rounded down toward the nearest even value (but object indices still refer to triangle indices, not quadrilateral indices).

Not compatible with method == 'sbr' and method == 'hybrid'.
epsilon (Float[ArrayLike, ''] | None) – Tolerance for checking ray / objects intersection, see rays_intersect_triangles.
hit_tol (Float[ArrayLike, ''] | None) –
Tolerance for checking blockage (i.e., obstruction), see rays_intersect_any_triangle.

Unused if method == 'sbr'.
min_len (Float[ArrayLike, ''] | None) –
Minimal (squared [1]) length that each path segment must have for a path to be valid.

If not specified, the default is ten times the epsilon value of the currently used floating point dtype.

Unused if method == 'sbr'.
max_dist (Float[ArrayLike, '']) –
Maximal (squared [1]) distance between a receiver and a ray for the receiver to be considered in the vicinity of the ray path.

Unused if method == 'exhaustive' or if method == 'hybrid'.
smoothing_factor (Float[ArrayLike, ''] | None) –
If set, intermediate hard conditions are replaced with smoothed ones, as described in [2], and this argument parameters the slope of the smoothing function. The, valid paths are lazily identified using confidence > confidence_threshold where confidence is a real value between 0 and 1 that indicates the confidence that a path is valid.

For more details, refer to Smoothing Discontinuities for Fully Differentiable Ray Tracing.

Warning

Currently, only the 'exhaustive' method is supported.
confidence_threshold (Float[ArrayLike, '']) – A threshold value for deciding which paths are valid.
batch_size (int | None) –
If specified, the number of triangles or rays to process in one batch when checking for intersections.

If None, everything is processed in one batch, which can lead to memory issues on large scenes.

See rays_intersect_any_triangle, triangles_visible_from_vertices, and first_triangles_hit_by_rays for more details.
disconnect_inactive_triangles (bool) –
If True, inactive triangles (where the mesh mask is False) are disconnected from the graph before generating path candidates. This can significantly reduce computational time for scenes with many inactive triangles, but the path candidates array size will vary based on the mask, which can trigger recompilations in JIT-compiled code.

For the 'hybrid' method, inactive triangles are always disconnected regardless of this parameter value, as the method already depends on the mask.

Return type:

Returns:

The paths, as class wrapping path vertices, object indices, and a masked identify valid paths.

The returned paths have the following batch dimensions:

[*transmitters_batch *receivers_batch num_path_candidates],
[*transmitters_batch *receivers_batch chunk_size],
or [*transmitters_batch *receivers_batch num_rays],

depending on the method used.

Raises:

ValueError – If neither order nor path_candidates has been provided, or if both have been provided simultaneously. If method == 'sbr' or method == 'hybrid'`, and ``order is not provided.

classmethod from_core(core_scene)[source]#

Return a triangle scene from a scene created by the differt_core module.

Parameters:: core_scene (TriangleScene) – The scene from the core module.
Return type:: Self
Returns:: The corresponding scene.

classmethod from_mitsuba(mi_scene)[source]#

Load a triangle scene from a Mitsuba scene object.

This method does not extract any transmitters or receivers from the Mitsuba scene, as Mitsuba does not provide any explicit information about them, and they are usually part of the Sionna scene object, see from_sionna.

Parameters:

mi_scene (mitsuba.Scene) –

The Mitsuba scene object.

You can obtain the Mitsuba scene object from a Sionna scene via its .mi_scene attribute.

Return type:

Self

Returns:

The corresponding scene containing only triangle meshes.

differt.scene.TriangleScene

Contents

differt.scene.TriangleScene#