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 representation type.
Public Functions
-
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 void resolve_irradiance(const std::vector<Transform<float>> &self_transforms, const std::vector<Time> ×, const SceneView<TSpectral> &scene_view, RandomSampler<float> &sampler) 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.
-
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 value as a single constant entry. 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, stored as a single constant entry. 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.
-
virtual TSpectral get_irradiance(Time time) const¶
Returns the spectral irradiance at a given time.
If the object holds a single (constant) irradiance entry, it is returned directly. Otherwise, the per-temporal-sample entries are linearly interpolated over the time range cached by set_resolved_irradiance_(). Times outside the range are clamped to the endpoints.
- Parameters:
time – The time at which to query irradiance.
- Returns:
The spectral irradiance value at the requested time.
-
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
Protected Functions
-
void set_resolved_irradiance_(std::vector<TSpectral> irradiances, const std::vector<Time> ×)¶
Stores resolved per-temporal-sample irradiances and their time range.
Validates the irradiance values and caches the time range endpoints used by get_irradiance() for interpolation.
irradiancesmust either contain a single (constant) entry, or exactly one entry per entry intimes.- Parameters:
irradiances – Resolved spectral irradiances, one per temporal sample (or a single constant entry).
times – Absolute times of the temporal samples.
- Throws:
std::runtime_error – if sizes are inconsistent or any value is invalid.