Unresolved Lambertian Sphere¶
-
template<IsSpectral TSpectral>
class UnresolvedLambertianSphere : public huira::UnresolvedObject<TSpectral>¶ Represents an unresolved sphere with Lambertian reflectance.
UnresolvedLambertianSphere models a spherical body with uniform Lambertian scattering. The apparent brightness depends on the phase angle between each light source, the sphere, and the observer, calculated using Lambert’s phase function. The reflected light is computed based on the sphere’s radius, albedo, and the incident irradiance, summed over the illuminating light sources.
By default the sphere is illuminated by every light in the scene view. The light-linked constructors restrict illumination to a single specified light instance (light linking).
- Template Parameters:
TSpectral – The spectral type (e.g., RGB, Visible8)
Public Functions
-
UnresolvedLambertianSphere(const UnresolvedLambertianSphere&) = delete¶
-
UnresolvedLambertianSphere &operator=(const UnresolvedLambertianSphere&) = delete¶
-
UnresolvedLambertianSphere(UnresolvedLambertianSphere&&) = delete¶
-
UnresolvedLambertianSphere &operator=(UnresolvedLambertianSphere&&) = delete¶
-
UnresolvedLambertianSphere(units::Meter radius, TSpectral albedo = TSpectral{1.f})¶
Constructs a sphere illuminated by all lights in the scene view.
Constructs an UnresolvedLambertianSphere illuminated by all scene lights.
- Parameters:
radius – Physical radius of the sphere in meters.
albedo – Spectral albedo of the sphere (default: 1.0 for all wavelengths).
- Throws:
std::runtime_error – if the radius or albedo is invalid.
-
UnresolvedLambertianSphere(units::Meter radius, float albedo)¶
Constructs a sphere illuminated by all lights in the scene view.
Constructs an UnresolvedLambertianSphere illuminated by all scene lights.
- Parameters:
radius – Physical radius of the sphere in meters.
albedo – Constant albedo of the sphere.
- Throws:
std::runtime_error – if the radius or albedo is invalid.
-
UnresolvedLambertianSphere(units::Meter radius, InstanceHandle<TSpectral> light_instance, TSpectral albedo = TSpectral{1.f})¶
Constructs a sphere illuminated only by the given light instance (light linking).
Constructs a light-linked UnresolvedLambertianSphere.
Initializes a Lambertian sphere with a given radius, illuminating light source, and spectral albedo. The constructor validates that the provided light instance actually contains a Light object. The sphere is illuminated only by that light.
-
UnresolvedLambertianSphere(units::Meter radius, InstanceHandle<TSpectral> light_instance, float albedo)¶
Constructs a sphere illuminated only by the given light instance (light linking).
Constructs a light-linked UnresolvedLambertianSphere.
Initializes a Lambertian sphere with a given radius, illuminating light source, and constant albedo. The constructor validates that the provided light instance actually contains a Light object. The sphere is illuminated only by that light.
-
virtual std::vector<TSpectral> resolve_irradiance(const std::vector<Transform<float>> &self_transforms, const std::vector<Time> ×, const SceneView<TSpectral> &scene_view, RandomSampler<float> &sampler) const override¶
Resolves the spectral irradiance via stochastic illumination sampling.
Computes the apparent brightness of the sphere as seen by an observer at the origin, at each temporal sample of the exposure. The estimator is, for each illumination source (emitting light or designated indirect source):
F = (2/3) * albedo * (R / d_obs)^2 * E[ (L_i * T_i / pdf_i) * Phi(alpha_i) ]
where each sample i draws a direction toward the source, L_i is the incident radiance from that direction (the light’s radiance, or the traced-and-shaded radiance of an indirect source’s surface), T_i is the visibility / transmittance along the sample ray, pdf_i is the solid-angle sampling density, and alpha_i is that sample’s own phase angle against the observer direction. Phi is the Lambert sphere phase function (Phi(0) = 1); the 2/3 prefactor is the Lambertian sphere’s geometric albedo factor, which integrates to exact energy conservation (total scattered power = albedo * pi * R^2 * E).
This single formulation captures: multiple light sources, penumbra (finite lights partially occluded across their disk), extended non-uniform indirect sources such as earthshine/moonshine (phase variation across the source’s solid angle included), and occlusion of the indirect sources themselves.
If this sphere was constructed with a light-linking filter, only that light contributes to the direct term; all designated indirect sources always contribute.
- Parameters:
self_transforms – Camera-relative transforms of this object, one per temporal sample.
times – Absolute times of the temporal samples.
scene_view – The fully constructed scene view (TLAS built).
sampler – Random sampler for the stochastic estimate.
- Throws:
std::runtime_error – if a light-linked sphere’s light source is not found in the scene.
- Returns:
The irradiance at each temporal sample.
-
void set_light_samples(std::size_t samples)¶
Sets the number of stochastic samples per light source.
Each light is sampled this many times per temporal sample; each sample casts one shadow/transmittance ray, so occlusion (including penumbra across a finite light’s disk) is captured. Defaults to 64.
- Parameters:
samples – Sample count (must be at least 1).
- Throws:
std::runtime_error – if samples is zero.
-
void set_indirect_source_samples(std::size_t samples)¶
Sets the number of stochastic samples per indirect source.
Each designated indirect source (reflector) is sampled this many times per temporal sample; each sample traces one ray to the source and shades the hit against the scene’s lights. Defaults to 64.
- Parameters:
samples – Sample count (must be at least 1).
- Throws:
std::runtime_error – if samples is zero.
-
inline virtual std::string type() const override¶
Get the object’s type string.
- Returns:
std::string Type
-
void set_irradiance(const units::SpectralWattsPerMeterSquared<TSpectral> &spectral_irradiance)¶
Sets the spectral irradiance of the unresolved object.
Updates the object’s irradiance. All spectral components must be non-negative, as negative irradiance is physically meaningless.
- Parameters:
spectral_irradiance – The new spectral irradiance value in \(W \cdot m^{-2}\).
- Throws:
std::runtime_error – if any irradiance component is negative.
-
void set_irradiance(const units::WattsPerMeterSquared &irradiance)¶
Sets the total irradiance of the unresolved object.
Updates the object’s irradiance by converting a total irradiance value (in watts per square meter) to the spectral representation. The total irradiance must be non-negative, as negative values are physically meaningless.
- Parameters:
irradiance – The new total irradiance value in \(W \cdot m^{-2}\).
- Throws:
std::runtime_error – if the total irradiance is negative, NaN, or infinite.
-
inline TSpectral get_irradiance() const¶
The irradiance it was given, by its constructor or set_irradiance().
-
inline bool is_scene_owned() const¶
Check if the object is owned by the scene.
- Returns:
bool True if owned
-
inline void set_scene_owned(bool owned)¶
Set scene ownership flag.
- Parameters:
owned – True if owned
-
inline std::string name() const¶
Get the object’s name.
- Returns:
std::string Name
-
inline virtual std::uint64_t id() const¶
Get the object’s unique ID.
- Returns:
std::uint64_t ID
-
inline virtual std::string get_info() const¶
Get a descriptive info string for the object.
- Returns:
std::string Info string