kaolin.render.lighting

API

class kaolin.render.lighting.SgLightingParameters(amplitude=3.0, direction=(1, 0.0, 0.0), sharpness=5.0)

Bases: object

Encapsulates Spherical Gaussians lighting parameters.

amplitude
cpu()
cuda()
direction
static from_environment_map(image)
static from_sun(direction, strength=3.0, angle=0.7853981633974483, color=None)

Returns a SgLightingParameters corresponding to suns.

Parameters

direction – The directions of the suns, of shape \((\text{num_suns}, 3)\).

Return: (SgLightingParameters): the spherical Gaussians matching the suns.

sharpness
to(device)
kaolin.render.lighting.approximate_sg_integral(amplitude, sharpness)

Computes an approximate integral of a spherical gaussian over the entire sphere.

The error vs the non-approximate version decreases as sharpness increases.

Parameters

  • amplitude (torch.Tensor) – The amplitude of the spherical gaussian.

  • sharpness (torch.Tensor) – The sharpness of the spherical gaussian.

Returns

The integral of same shape than amplitude.

Return type

(torch.tensor)

kaolin.render.lighting.cosine_lobe_sg(direction)

Returns an approximation of the clamped cosine lobe represented as a spherical gaussian.

This is to be used with normal of surfaces to apply Lambert’s cosine law.

Parameters

direction (torch.tensor) – The direction of the desired lobe, of last dimension 3

Returns

  • The amplitude of the spherical gaussian, of same shape as direction

  • The input direction

  • The sharpness of the spherical gaussian, of shape direction.shape[:-1]

Return type

(torch.tensor, torch.Tensor, torch.Tensor)

kaolin.render.lighting.fresnel(ldh, spec_albedo)
kaolin.render.lighting.project_onto_sh9(directions)

Project directions, represented as cartesian coordinates, onto the spherical harmonic coefficients of degree 3.

Parameters

directions (torch.Tensor or list of int) – The directions as cartesian coordinates, of any shape but of last dimension 3.

Returns

The spherical harmonics coefficients,

of shape direction.shape[:-1] and last dimension 9.

Return type

(torch.Tensor)

kaolin.render.lighting.sg_diffuse_fitted(amplitude, direction, sharpness, normal, albedo)

Computes the outgoing radiance from multiple spherical gaussians representing incoming radiance, using a Lambertian diffuse BRDF.

Note

The irradiance is computed using a fitted approximation polynomial, this approximation were provided by Stephen Hill. See sg_irradiance_fitted().

Parameters

  • amplitude (torch.Tensor) – The amplitudes of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • direction (torch.Tensor) – The directions of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • sharpness (torch.Tensor) – The sharpness of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg},)\).

  • normal (torch.Tensor) – The normal of the surface points where the radiance is to be estimated, of shape \((\text{num_points}, 3)\).

  • albedo (torch.Tensor) – The albedo (RGB color) of the surface points where the radiance is to be estimated, of shape \((\text{num_points}, 3)\).

Returns

The diffuse radiance, of shape \((\text{num_points}, 3)\).

Return type

(torch.Tensor)

kaolin.render.lighting.sg_diffuse_inner_product(amplitude, direction, sharpness, normal, albedo)

Computes the outgoing radiance from multiple spherical gaussians representing incoming radiance, using a Lambertian diffuse BRDF.

This is the diffuse reflectance used in DIB-R++: Learning to Predict Lighting and Material with a Hybrid Differentiable Renderer NeurIPS 2021.

Parameters

  • amplitude (torch.Tensor) – The amplitudes of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • direction (torch.Tensor) – The directions of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • sharpness (torch.Tensor) – The sharpness of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg},)\).

  • normal (torch.Tensor) – The normal of the surface points where the radiance is to be estimated, of shape \((\text{num_points}, 3)\).

  • albedo (torch.Tensor) – The albedo of the surface points where the radiance is to be estimated, of shape \((\text{num_points}, 3)\).

Returns

The diffuse radiance, of shape \((\text{num_points}, 3)\).

Return type

(torch.Tensor)

kaolin.render.lighting.sg_direction_from_azimuth_elevation(azimuth, elevation)

Converts azimuth and elevation angles to a direction vector, assuming y-up orientation.

Parameters
Returns

(torch.Tensor)

kaolin.render.lighting.sg_distribution_term(direction, roughness)

Returns spherical gaussians approximation of the Trowbridge-Reitz (GGX) distribution used in the Cook-Torrance specular BRDF.

Use a single lobe to approximate the distribution.

Parameters

  • direction (torch.Tensor) – The normal directions, of shape \((\text{num_points}, 3)\)

  • roughness (torch.Tensor) – The roughness of the surface, of shape \((\text{num_points})\)

Returns

  • The amplitude of the spherical gaussians, of shape \((\text{num_points}, 3)\).

  • The input direction.

  • The sharpness of the spherical gaussians, of shape \((\text{num_points})\).

Return type

(torch.Tensor, torch.Tensor, torch.Tensor)

kaolin.render.lighting.sg_from_sun(direction, strength, angle, color)

Returns Spherical Gaussian parameters corresponding to suns.

Parameters

  • strength (torch.Tensor) – The strength of the suns, of shape \((\text{num_suns},)\), [1..inf] expected, usually in low integer range.

  • color (torch.Tensor) – The color of the suns, of shape \((\text{num_suns}, 3)\), float [0..1] expected.

  • direction (torch.Tensor) – The directions of the suns, of shape \((\text{num_suns}, 3)\).

  • angle (torch.Tensor) – The suns angular diameter, in radians, of shape \((\text{num_suns},)\).

Returns

  • The amplitude of the spherical gaussians, of shape \((\text{num_suns}, 3)\).

  • The direction of the spherical gaussians, of shape \((\text{num_suns}, 3)\).

  • The sharpness of the spherical gaussians, of shape \((\text{num_suns},)\).

Return type

(torch.Tensor, torch.Tensor, torch.Tensor)

kaolin.render.lighting.sg_irradiance_fitted(amplitude, direction, sharpness, normal)

Computes an approximate incident irradiance from multiple spherical gaussians representing the incoming radiance.

The result is broadcasted per point per spherical gaussian.

Note

The irradiance is computed using a fitted approximation polynomial, this approximation were provided by Stephen Hill.

Parameters

  • amplitude (torch.Tensor) – The amplitudes of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • direction (torch.Tensor) – The directions of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • sharpness (torch.Tensor) – The sharpness of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg},)\).

  • normal (torch.Tensor) – The normal of the surface points where the irradiance is to be estimated, of shape \((\text{num_points}, 3)\).

Returns

The irradiance for each spherical gaussian for each surface point, of shape \((\text{num_points}, \text{num_sg}, 3)\).

Return type

(torch.Tensor)

kaolin.render.lighting.sg_irradiance_inner_product(amplitude, direction, sharpness, normal)

Computes the approximate incident irradiance from multiple spherical gaussians representing incoming radiance.

The clamped cosine lobe is approximated as a spherical gaussian, and convolved with the incoming radiance lobe using a spherical gaussian inner product.

Parameters

  • amplitude (torch.Tensor) – The amplitudes of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • direction (torch.Tensor) – The directions of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • sharpness (torch.Tensor) – The sharpness of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg},)\).

  • normal (torch.Tensor) – The normal of the surface points where the radiance is to be estimated, of shape \((\text{num_points}, 3)\).

Returns

The irradiance, of shape \((\text{num_points}, 3)\).

Return type

(torch.Tensor)

kaolin.render.lighting.sg_warp_distribution(amplitude, direction, sharpness, view)

Generate spherical gaussians that best represent the normal distribution function but with its axis oriented in the direction of the current BRDF slice.

Uses the warping operator from Wang et al.

Parameters

  • amplitude (torch.Tensor) – The amplitudes of the spherical gaussians to be warped, of shape \((\text{num_sg}, 3)\).

  • direction (torch.Tensor) – The directions of the spherical gaussians to be warped, of shape \((\text{num_sg}, 3)\).

  • sharpness (torch.Tensor) – The sharpness of the spherical gaussians to be warped, of shape \((\text{num_sg},)\).

  • view (torch.Tensor) – The view direction, of shape \((\text{num_sg}, 3)\).

Returns

  • The input amplitude

  • The warped direction, of shape \((\text{num_sg}, 3)\)

  • The warped sharpness, of shape \((\text{num_sg})\)

Return type

(torch.Tensor, torch.Tensor, torch.Tensor)

kaolin.render.lighting.sg_warp_specular_term(amplitude, direction, sharpness, normal, roughness, view, spec_albedo)

Computes the specular reflectance from a spherical gaussians lobes representing incoming radiance, using the Cook-Torrance microfacet specular shading model.

Parameters

  • amplitude (torch.Tensor) – The amplitudes of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • direction (torch.Tensor) – The directions of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg}, 3)\).

  • sharpness (torch.Tensor) – The sharpness of the spherical gaussians representing the incoming radiance, of shape \((\text{num_sg},)\).

  • normal (torch.Tensor) – The normal of the surface points where the specular reflectance is to be estimated, of shape \((\text{num_points}, 3)\).

  • roughness (torch.Tensor) – The roughness of the surface points where the specular reflectance is to be estimated, of shape \((\text{num_points})\).

  • view (torch.Tensor) – The direction toward the camera from the surface points where the specular reflectance is to be estimated, of shape \((\text{num_points}, 3)\).

  • spec_albedo (torch.Tensor) – The specular albedo (RGB color) of the surface points where the specular reflectance is to be estimated, of shape \((\text{num_points}, 3)\).

Returns

The specular reflectance, of shape \((\text{num_points}, 3)\).

Return type

(torch.Tensor)

kaolin.render.lighting.sh9_diffuse(directions, normals, albedo)

Compute the outgoing radiance from a single spherical harmonic lobe of degree 3 representing incoming radiance, using a Lambertian diffuse BRDF.

Parameters

  • directions (torch.Tensor) – Light directions, of 1D size \((3,)\).

  • normals (torch.Tensor) – Normal of the points where the radiance is to be estimated, of shape \((\text{num_points}, 3)\).

  • albedo (torch.Tensor) – albedo (RGB color) of the points where the radiance is to be estimated, of shape \((\text{num_points}, 3)\).

Returns

The diffuse radiance, of same shape than albedo.

Return type

(torch.Tensor)

kaolin.render.lighting.sh9_irradiance(lights, normals)

Compute approximate incident irradiance from a single spherical harmonic lobe of degree 3 representing incoming radiance.

The clamped cosine lobe is approximated as spherical harmonics.

Parameters

  • lights (torch.Tensor) – Light parameters of each spherical harmonic (see: project_onto_sh9()), of 1D size \((9,)\).

  • normals (torch.Tensor) – Normal of the points where the irradiance is to be estimated, of shape \((\text{num_points}, 3)\).

Returns

The irradiance values, of 1D shape \((\text{num_points},)\).

Return type

(torch.Tensor)