Intersection

class diffinytrace.intersection.SemiFunctionalModule

Bases: Module

Abstract base class for semi-functional surface modules.

These modules define a static method functional that computes a functional transformation on inputs and parameters, and a method to list their functional parameters for optimization purposes.

static functional(O: Tensor, *params)

This method provides the implicit surface description. It is a static method. Diffinytrace constructs a function s(R, p) on the fly to describe the surface, allowing better control over derivative calculations.

get_functional_param_args()

diffinytrace.intersection.cat_semi_functionals(functional_modules: List[SemiFunctionalModule]) → Callable

Recursively chains a list of `SemiFunctionalModule`s into a single composite function.

Each module’s functional() method is applied in sequence using the respective slice of the parameter list.

Parameters:

functional_modules (list[SemiFunctionalModule]) – List of functional modules.

Returns:

A function f(O, *params) that applies all modules in sequence.

Return type:

Callable

diffinytrace.intersection.get_functional_param_args(semi_functional_module_list: List[SemiFunctionalModule]) → List

Collects all functional parameters from a list of semi-functional modules.

Parameters:

semi_functional_module_list (list[SemiFunctionalModule]) – List of modules.

Returns:

Flattened list of all parameters.

Return type:

list[torch.nn.Parameter]

diffinytrace.intersection.construct_surface_and_normal_func(semi_functional_module_list: List[SemiFunctionalModule]) → Callable

Constructs a function to evaluate both the surface value and its gradient (normal direction) with respect to the ray origin O.

The surface is defined by composing the provided semi-functional modules.

Returns a callable:

\[(O, p_1, ..., p_n) \mapsto ( s(O), \frac{\partial s}{\partial O} )\]

Parameters:

semi_functional_module_list (list[SemiFunctionalModule]) – List of modules.

Returns:

A function s_dsd(O, *params, only_s=False) returning surface value s and optionally gradient ds/dO.

Return type:

Callable

diffinytrace.intersection.construct_surface_and_normal_func_with_params(semi_functional_module_list: List[SemiFunctionalModule]) → Tuple[Callable, List]

Constructs both the surface function and a list of its functional parameters.

Useful for optimization workflows that require parameter tracking.

Parameters:

semi_functional_module_list (list[SemiFunctionalModule]) – List of modules.

Returns:

Callable: A function computing surface and its gradient. list[torch.nn.Parameter]: The list of parameters for the surface.

Return type:

tuple

class diffinytrace.intersection.CustomAutogradRule_t(*args, **kwargs)

Bases: Function

Custom PyTorch autograd rule for ray-surface intersection.

Computes a differentiable intersection length t such that:

\[s(O + t D) = 0\]

where O is the ray origin, D is the direction, and s is the surface function.

This rule enables backpropagation through t with respect to O, D, and surface parameters.

static forward(ctx, O: Tensor, D: Tensor, surface_and_normal_func: Callable, t_detached: Tensor, *param_args) → Tensor

Stores inputs for backward pass and returns precomputed t.

Parameters:

• O (torch.Tensor) – Ray origin of shape (N, 3).

• D (torch.Tensor) – Ray direction of shape (N, 3).

• surface_and_normal_func (Callable) – Surface function returning (s, ds/dR).

• t_detached (torch.Tensor) – Estimated intersection length (detached).

• *param_args – Surface parameters.

Returns:

Intersection length t.

Return type:

torch.Tensor

static backward(ctx, grad_outputs: Tensor) → Tuple

Computes gradients of intersection length t with respect to: - ray origin O - ray direction D - surface parameters

Parameters:

grad_outputs (torch.Tensor) – Gradient of the loss w.r.t. output t.

Returns:

Gradients with respect to inputs (O, D, None, None, *param_args).

Return type:

tuple

diffinytrace.intersection.get_ray_intersection_length(O: Tensor, D: Tensor, surface_and_normal_func: Callable, param_args: List, t_init: Tensor | None = None) → Tensor

Solves for the intersection length t such that:

\[s(O + t D) = 0\]

using a Newton-style iteration method with damping.

This function finds the length t where a ray intersects a parametric surface, given by a composed function with normal information.

Parameters:

• O (torch.Tensor) – Ray origins of shape (N, 3).

• D (torch.Tensor) – Ray directions of shape (N, 3).

• surface_and_normal_func (Callable) – A function returning (s, ds/dR).

• param_args (list) – List of surface parameters.

• t_init (torch.Tensor, optional) – Initial guess for t. If None, starts from zero.

Returns:

Estimated intersection lengths t with autograd support.

Return type:

torch.Tensor

Raises:

Warning is printed (not exception) if convergence fails within max_iter. –