differt.geometry module

Geometries for building scenes and tracing ray paths efficiently.

Scene and Meshes

The most important classes for defining the environment.

Scene([transmitters, receivers, mesh])	A simple scene made of one or more triangle meshes, some transmitters and some receivers.
Mesh(vertices, triangles[, face_colors, ...])	A simple geometry made of triangles.

Reusing scenes from Sionna

Provide a compatibility layer with Sionna’s scenes [9].

Sionna uses the simple XML-based format from Mitsuba 3.

download_sionna_scenes([branch_or_tag, ...])	Download the scenes from Sionna, and store them in the given folder.
get_sionna_scene(scene_name, *[, folder])	Return the path to the given Sionna scene.
list_sionna_scenes(*[, folder])	List available Sionna scenes, by name.

Geometry Utilities

Utilities to transform 3D coordinates and miscellaneous helpers.

assemble_path(from_vertex, intermediate_vertices)	Assemble path vertices by concatenating start-, intermediate, and end-vertices.
cartesian_to_spherical(xyz)	Transform Cartesian coordinates to spherical coordinates.
spherical_to_cartesian(rpa)	Transform spherical coordinates to Cartesian coordinates.
rotation_matrix_along_axis(angle, axis)	Return a rotation matrix to rotate coordinates along a given axis.
rotation_matrix_along_x_axis(angle)	Return a rotation matrix to rotate coordinates along x axis.
rotation_matrix_along_y_axis(angle)	Return a rotation matrix to rotate coordinates along y axis.
rotation_matrix_along_z_axis(angle)	Return a rotation matrix to rotate coordinates along z axis.
fibonacci_lattice(n[, dtype, frustum])	Return a lattice of vertices on the unit sphere.
merge_cell_ids(cell_ids_a, cell_ids_b)	Merge two arrays of cell indices as returned by TracedPaths.multipath_cells.
min_distance_between_cells(cell_vertices, ...)	Compute the minimal (Euclidean) distance between vertices in different cells.
normalize(vectors[, keepdims])	Normalize vectors and also return their length.
perpendicular_vector(u)	Generate a vector perpendicular to the input vector.
orthogonal_basis(u)	Generate v and w, two other unit vectors that form with input u an orthogonal basis.
path_length(path)	Compute the path length of the path.
triangle_contains_vertex_assuming_inside_same_plane(...)	Return whether the triangle contains the corresponding vertex, assuming the vertex lies in the same plane as the triangle.
viewing_frustum(viewing_vertex, ...[, ...])	Compute the viewing frustum as seen by one viewer.

Ray Tracing

Methods and classes for simulating electromagnetic wave propagation, path tracing, and ray launching.

TracedPaths(vertices, objects, mask, ...[, ...])	A convenient wrapper class around path vertices and object indices.
LaunchedPaths(vertices, objects, masks, ...)	Paths method generated with ray launching methods.

Path solvers

AbstractPathSolver()	Base class for all path solvers and launchers.
AbstractPathTracer()	Abstract base class for exact path tracing solvers.
AbstractPathLauncher()	Abstract base class for ray-launching path solvers.
ExhaustivePathTracer([epsilon, hit_tol, ...])	Exhaustive (image-method) path tracer.
HybridPathTracer([num_rays, epsilon, ...])	Hybrid path tracer, combining ray launching for visibility and exhaustive tracing.
SBRPathLauncher([num_rays, epsilon, ...])	Shooting-and-bouncing ray (SBR) path launcher.

Image method

Image-based path tracing.

image_method(from_vertex, to_vertex, ...)	Return the ray path between a pair of vertices, that reflects on a given list of mirrors in between.
image_of_vertex_with_respect_to_mirror(...)	Return the image of the vertex with respect to the mirror.
intersection_of_ray_with_plane(ray_origin, ...)	Return the intersection point between the ray and the (infinite) plane.

Fermat path tracing

Path tracing utilities that utilize Fermat’s principle.

Fermat’s principle states that the path taken by a ray between two given points is the path that can be traveled in the least time [21]. In a homogeneous medium, this means that the path of least time is also the path of least distance.

As a result, this module offers minimization methods for finding ray paths.

fermat_path_on_linear_objects(from_vertex, ...)	Return the ray path between a pair of vertices, that reflects or diffracts on a given list of objects in between.
fermat_path_on_planar_mirrors(from_vertex, ...)	Return the ray path between a pair of vertices, that reflects on a given list of mirrors in between.

Path candidates iterators

Useful utilities to generate path candidates, see Generating path candidates.

To generate a subset of all paths between two vertices, e.g., a transmitter TX and a receiver RX, path tracing methods generate each ray path from a corresponding path candidate.

A path candidate is simply a list of primitive indices to indicate with what primitive the path interacts, and in what order. The latter indicates that any permutation of a given path candidate will result in another path.

I.e., the path candidate [4, 7] indicates that the path first interacts with primitive 4, then primitive 7, while the path candidate [7, 4] indicates a path interacting first with 7 then with 4.

An empty path candidate indicates a direct path from TX or RX, also known as line-of-sight path.

In general, interaction can be anything of the following: reflection, diffraction, refraction, etc. The utilities present in this module do not take care of the interaction type.

For fine tuning, use differt_core.geometry’s graphs and iterators.

You can also read more about path candidates in [1].

generate_all_path_candidates(num_primitives, ...)	Generate an array of all path candidates for fixed path order and a number of primitives.
generate_all_path_candidates_chunks_iter(...)	Iterator variant of generate_all_path_candidates, grouped in chunks of size of max.
generate_all_path_candidates_iter(...)	Iterator variant of generate_all_path_candidates.

All returned iterators are of the following type.

class SizedIterator(iter, size)

A custom generic class that is both Iterator and Sized.

The main purpose of this class is to be able to use tqdm utilities on iterators and have some meaningful information about how iterations are left.

Parameters:

• iter – The iterator.

• size (int | Callable[[], int]) – The size, i.e., length, of the iterator, or a callable that returns its current length.

Examples

The following example shows how to create a sized iterator.

>>> from differt.rt import SizedIterator
>>> l = [1, 2, 3, 4, 5]
>>> it = SizedIterator(iter=iter(l), size=5)
>>> len(it)
5
>>> it = SizedIterator(iter=iter(l), size=l.__len__)
>>> len(it)
5

Sanity checks

Utilities to check that ray paths are physically valid.

consecutive_vertices_are_on_same_side_of_mirror(...)	Check if consecutive vertices, but skipping one every other vertex, are on the same side of a given mirror.
first_triangle_hit_by_ray(ray_origins, ...)	Return the first triangle hit by each ray.
ray_intersect_any_triangle(ray_origins, ...)	Return whether rays intersect any of the triangles using the Möller-Trumbore algorithm.
ray_intersect_triangle(ray_origins, ...[, ...])	Return whether rays intersect corresponding triangles using the Möller-Trumbore algorithm.
triangles_visible_from_vertex(vertex, ...[, ...])	Return whether triangles are visible from vertex positions.

Deprecated classes

Paths(*args, **kwargs)	Deprecated alias for TracedPaths.
SBRPaths(*args, **kwargs)	Deprecated alias for LaunchedPaths.
TriangleMesh(*args, **kwargs)	Deprecated alias for Mesh.
TriangleScene(*args, **kwargs)	Deprecated alias for Scene.