differt.geometry.SBRPathTracer

class SBRPathTracer(num_rays=1000000, epsilon=None, hit_tol=None, min_len=None, smoothing_factor=None, confidence_threshold=0.5, batch_size=512, chunk_size=None, max_num_candidates=100000)

Bases: HybridPathTracer

Shooting-and-bouncing ray (SBR) path tracer.

Instead of enumerating a (possibly visibility-pruned) complete graph, like ExhaustivePathTracer and HybridPathTracer do, this tracer discovers candidate interaction sequences by launching a fixed, bounded population of rays from each transmitter and following their specular bounces, closely following the shooting-and-bouncing-rays (SBR) candidate generation procedure used by Sionna RT [14]; see its technical report for a detailed description of the algorithm this class is based on.

Every ray trajectory yields (at most) one candidate sequence of primitive indices, so the memory needed to generate candidates only depends on num_rays and max_num_candidates, and no longer grows combinatorially with order or the number of primitives in the scene. Because many rays typically converge onto the same discrete sequence of primitives, especially at low orders, the discovered candidates are deduplicated (and bounded by max_num_candidates) before being passed to the same exact image-method solver used by ExhaustivePathTracer and HybridPathTracer.

When order is a sequence (or a range/slice), rays are launched only once, up to the maximum requested order: candidates for every requested order (including order 0 for line-of-sight if requested) are collected, padded up to the maximum requested order with -1 placeholders, and combined into a single array bounded by max_num_candidates.

Important

Because candidates are discovered from a finite ray population, this tracer is not guaranteed to be exhaustive: it may miss valid paths that subtend a small solid angle as seen from the transmitters, especially at high orders or in scenes with many small primitives. Increasing num_rays improves coverage, at the cost of memory and runtime.

Important

Like HybridPathTracer, this tracer is best used for a small number of transmitters (rays are only launched from transmitters, not receivers).

Attributes

batch_size	Intersection check batch size.
chunk_size	If specified, iterates through chunks of path candidates, yielding an iterator over path chunks.
confidence_threshold	Confidence threshold for valid paths.
epsilon	Tolerance for checking ray / object intersections.
hit_tol	Tolerance for blockage checks.
max_num_candidates	The maximum number of (deduplicated) path candidates that are kept.
min_len	Minimal (squared) length that each path segment must have for a path to be valid.
num_rays	The number of rays launched.
smoothing_factor	Parameters for slope of the smoothing function.

Methods

generate_path_candidates(scene, order[, ...])	Return a tuple of (path_candidates, interaction_types).
generate_path_candidates_chunks_iter(scene, ...)	Fall back to the default slice-based chunking.
trace_path_candidates(scene, ...)	Core logic to trace the exact paths from the proposed candidates.
trace_paths(scene, order[, chunk_size, ...])	Trace paths for the given scene and order(s).

Detailed documentation

batch_size: int | None = 512

Intersection check batch size.

chunk_size: int | None = None

If specified, iterates through chunks of path candidates, yielding an iterator over path chunks.

confidence_threshold: Float[ArrayLike, ""] = 0.5

Confidence threshold for valid paths.

epsilon: Float[ArrayLike, ""] | None = None

Tolerance for checking ray / object intersections.

generate_path_candidates(scene, order, specular_reflection=True, diffuse_scattering=False)

Return a tuple of (path_candidates, interaction_types).

path_candidates contains triangle indices. interaction_types classifies the bounce (e.g., 0 for specular). A value of -1 in either array indicates an “inactive” interaction or padded bounce.

order may also be a sequence of orders, e.g., [1, 2, 3], a range (e.g., range(0, 6)), or a slice with a defined stop (e.g., slice(0, 6), equivalent to range(0, 6)), to combine candidates of multiple orders into a single array, with lower-order candidates padded with -1 up to the maximum requested order, see check_path_candidates for the exact placeholder convention. For most solvers, candidates are generated independently for each order and concatenated, so the size of the returned arrays is known ahead of time: it is the sum of the number of candidates generated for each individual order. SBRPathTracer is a notable exception: it shares a single, fixed-size buffer across all requested orders instead, see its documentation for details.

Parameters:

• scene (Scene) – The scene.

• order (int | Sequence[int] | slice) – The path order (number of bounces), or a sequence of orders (also accepted as a range or slice) to combine.

• specular_reflection (bool) – Whether to include specular reflections.

• diffuse_scattering (bool) – Whether to include diffuse scattering (not yet implemented).

Return type:

tuple[Int[Array, "num_candidates order"], Int[Array, "num_candidates order"]]

Returns:

A 2-tuple of (path_candidates, interaction_types).

generate_path_candidates_chunks_iter(scene, order, *args, chunk_size=None, pad_chunks=False, **kwargs)

Fall back to the default slice-based chunking.

Unlike HybridPathTracer, this tracer does not build a visibility graph, so there is nothing to chunk natively: candidates are generated all at once (bounded by max_num_candidates) and then sliced into chunks.

Return type:

SizedIterator[tuple[Int[Array, "... chunk_size order"], Int[Array, "... chunk_size order"]]]

Returns:

An iterator over path candidates chunks.

hit_tol: Float[ArrayLike, ""] | None = None

Tolerance for blockage checks.

max_num_candidates: int = 100000

The maximum number of (deduplicated) path candidates that are kept.

If more unique candidates are discovered than this value, the extra candidates are silently dropped.

min_len: Float[ArrayLike, ""] | None = None

Minimal (squared) length that each path segment must have for a path to be valid.

num_rays: int = 1000000

The number of rays launched.

smoothing_factor: Float[ArrayLike, ""] | None = None

Parameters for slope of the smoothing function.

trace_path_candidates(scene, path_candidates, interaction_types)

Core logic to trace the exact paths from the proposed candidates.

Parameters:

• scene (Scene) – The scene.

• path_candidates (Int[Array, "num_candidates order"]) – Triangle indices for each candidate.

• interaction_types (Int[Array, "num_candidates order"]) – Interaction type for each bounce.

Return type:

TracedPaths

Returns:

The traced paths.

trace_paths(scene, order, chunk_size=None, pad_chunks=False)

Trace paths for the given scene and order(s).

If chunk_size is provided, returns an iterator of TracedPaths (one per chunk); otherwise returns a single TracedPaths.

If order is a sequence of orders, e.g., [1, 2, 3], then generate_path_candidates directly generates path candidates for every requested order, combining them into a single array, with lower-order candidates padded (with -1) up to the maximum requested order; the (single) combined array is then traced in one call to trace_path_candidates. This is not compatible with chunk_size.

Parameters:

• scene (Scene) – The scene.

• order (int | Sequence[int] | slice) – The path order(s).

• chunk_size (int | None) – If not None, iterate through chunks of this size.

• pad_chunks (bool) – If True and chunk_size is set, pad the last chunk.

Return type:

TracedPaths | SizedIterator[TracedPaths]

Returns:

Traced paths, or a sized iterator thereof.

Raises:

NotImplementedError – If order is a sequence of orders and chunk_size is not None.