differt.scene.AbstractPathTracer

class AbstractPathTracer

Bases: AbstractPathSolver

Abstract base class for exact path tracing solvers.

A path tracer generates path candidates (arrays of triangle indices together with interaction-type tags) and then traces them through the scene to produce TracedPaths.

Attributes

epsilon	Tolerance for checking ray / object intersections.
hit_tol	Tolerance for blockage checks.

Methods

generate_path_candidates(scene, order[, ...])	Return a tuple of (path_candidates, interaction_types).
generate_path_candidates_chunks_iter(scene, ...)	Return an iterator of chunked path candidate tuples.
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

epsilon: AbstractVar[float]

Tolerance for checking ray / object intersections.

abstractmethod 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 (used when combining paths of different reflection orders).

Parameters:

• scene (TriangleScene) – The scene.

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

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

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

Return type:

tuple[ num_path_candidates max_order'], num_path_candidates max_order']]

Returns:

A 2-tuple of (path_candidates, interaction_types).

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

Return an iterator of chunked path candidate tuples.

The default implementation calls generate_path_candidates once and then slices the result. Subclasses may override this to generate candidates lazily.

Parameters:

• scene (TriangleScene) – The scene.

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

• *args (Any) – Forwarded to generate_path_candidates.

• chunk_size (int) – Number of candidates per chunk.

• pad_chunks (bool) – If True, the last chunk is zero-padded (with -1) to chunk_size.

• **kwargs (Any) – Forwarded to generate_path_candidates.

Return type:

SizedIterator[tuple[ chunk_size max_order'], chunk_size max_order']]]

Returns:

A SizedIterator over (path_candidates, interaction_types) chunks.

hit_tol: AbstractVar[float]

Tolerance for blockage checks.

abstractmethod trace_path_candidates(scene, path_candidates, interaction_types)

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

Parameters:

• scene (TriangleScene) – The scene.

• path_candidates ( num_path_candidates max_order']) – Triangle indices for each candidate.

• interaction_types ( num_path_candidates max_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.

Parameters:

• scene (TriangleScene) – The scene.

• order (int | Sequence[int]) – 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 | Iterator[TracedPaths]

Returns:

Traced paths, or an iterator thereof.