Scene¶

template<IsSpectral TSpectral> class Scene¶

Scene graph and asset manager for a rendered world.

The Scene class manages all assets (geometries, materials, lights, unresolved objects, camera models, models, stars) and the scene graph (root node, child nodes, instances, etc.). It provides methods for adding, removing, and querying assets, as well as for loading star catalogs and models. The scene graph is rooted at a FrameNode and supports hierarchical relationships between nodes and assets. Scene is non-copyable.

Template Parameters:: TSpectral – The spectral type (e.g., RGB, Visible8)

Public Functions

Scene(const Scene&) = delete¶

Scene &operator=(const Scene&) = delete¶

Scene()¶: Constructs a Scene and initializes the root node.

~Scene()¶

MeshHandle<TSpectral> add_mesh(const IndexBuffer &index_buffer, const VertexBuffer<TSpectral> &vertex_buffer, std::string name = "")¶

Adds a mesh to the scene.

Parameters:

index_buffer – The index buffer for the mesh.
vertex_buffer – The vertex buffer for the mesh.
name – Optional name for the mesh.

MeshHandle<TSpectral> add_mesh(const IndexBuffer &index_buffer, const VertexBuffer<TSpectral> &vertex_buffer, const TangentBuffer &tangent_buffer, std::string name = "")¶

Adds a mesh to the scene.

Parameters:

index_buffer – The index buffer for the mesh.
vertex_buffer – The vertex buffer for the mesh.
tangent_buffer – The tangent buffer for the mesh.
name – Optional name for the mesh.

EllipsoidHandle<TSpectral> add_ellipsoid(const units::Meter &x, const units::Meter &y, const units::Meter &z, std::string name = "")¶

Adds an ellipsoid to the scene.

Parameters:

x – Semi-axis length along the x-axis.
y – Semi-axis length along the y-axis.
z – Semi-axis length along the z-axis.
name – Optional name for the mesh.

GeometryHandle<TSpectral> add_geometry(std::shared_ptr<Geometry<TSpectral>> geom, std::string name = "")¶

Adds a geometry to the scene.

Parameters:

geometry – std::shared_ptr to the Geometry object
name – Optional name for the geometry

Returns:

GeometryHandle<TSpectral> Handle to the added geometry

void set_name(const GeometryHandle<TSpectral> &geom_handle, const std::string &name)¶

Sets the name for a geometry asset.

Parameters:

geom_handle – Handle to the geometry
name – New name

GeometryHandle<TSpectral> get_geometry(const std::string &name) const¶

Retrieves a geometry by name.

Parameters:: name – Name of the geometry
Returns:: GeometryHandle<TSpectral> Handle to the mesh

void delete_geometry(const GeometryHandle<TSpectral> &geom_handle)¶

Deletes a geometry from the scene.

Parameters:: geom_handle – Handle to the geometry

PrimitiveHandle<TSpectral> add_primitive(const GeometryHandle<TSpectral> &geom, std::string name = "")¶

Adds a primitive to the scene with default material.

Parameters:

geometry_handle – GeometryHandle for the primitive’s geometry
name – Optional name for the primitive

Returns:

PrimitiveHandle<TSpectral> Handle to the added primitive

PrimitiveHandle<TSpectral> add_primitive(const GeometryHandle<TSpectral> &geom, const MaterialHandle<TSpectral> &mat, std::string name = "")¶

Adds a primitive to the scene.

Parameters:

geometry_handle – GeometryHandle for the primitive’s geometry
material_handle – MaterialHandle for the primitive’s material
name – Optional name for the primitive

Returns:

PrimitiveHandle<TSpectral> Handle to the added primitive

PrimitiveHandle<TSpectral> add_primitive(const GeometryHandle<TSpectral> &geom, const MediumHandle<TSpectral> &medium, std::string name = "")¶

Adds a primitive to the scene.

Parameters:

geometry_handle – GeometryHandle for the primitive’s geometry
medium_handle – MediumHandle for the primitive’s medium
name – Optional name for the primitive

Returns:

PrimitiveHandle<TSpectral> Handle to the added primitive

PrimitiveHandle<TSpectral> add_primitive(const GeometryHandle<TSpectral> &geom, const MaterialHandle<TSpectral> &mat, const MediumHandle<TSpectral> &medium, std::string name = "")¶

Adds a primitive to the scene.

Parameters:

geometry_handle – GeometryHandle for the primitive’s geometry
material_handle – MaterialHandle for the primitive’s material
medium_handle – MediumHandle for the primitive’s medium
name – Optional name for the primitive

Returns:

PrimitiveHandle<TSpectral> Handle to the added primitive

void set_name(const PrimitiveHandle<TSpectral> &primitive_handle, const std::string &name)¶

Sets the name for a primitive asset.

Parameters:

primitive_handle – Handle to the primitive
name – New name

PrimitiveHandle<TSpectral> get_primitive(const std::string &name) const¶

Retrieves a primitive by name.

Parameters:: name – Name of the primitive
Returns:: PrimitiveHandle<TSpectral> Handle to the primitive

void delete_primitive(const PrimitiveHandle<TSpectral> &primitive_handle)¶

Deletes a primitive from the scene.

Parameters:: primitive_handle – Handle to the primitive

LightHandle<TSpectral> new_sphere_light(const units::Meter &radius, const units::SpectralWattsPerMeterSquaredSteradian<TSpectral> &spectral_radiance, std::string name = "")¶

Creates a new sphere light with spectral radiance.

Parameters:

radius – Radius of the sphere light
spectral_radiance – Spectral radiance of the light
name – Optional name

Returns:

LightHandle<TSpectral> Handle to the new light

LightHandle<TSpectral> new_sphere_light(const units::Meter &radius, const units::SpectralWatts<TSpectral> &spectral_power, std::string name = "")¶

Creates a new point light with spectral power.

Parameters:

radius – Radius of the sphere light
spectral_power – Spectral power of the light
name – Optional name

Returns:

LightHandle<TSpectral> Handle to the new light

LightHandle<TSpectral> new_sphere_light(const units::Meter &radius, const units::Watt &total_power, std::string name = "")¶

Creates a new point light with total power.

Parameters:

radius – Radius of the sphere light
total_power – Total power of the light
name – Optional name

Returns:

LightHandle<TSpectral> Handle to the new light

LightHandle<TSpectral> new_sun_light()¶

Creates a new sun light with solar spectral radiance, and radius of the sun.

Returns:: LightHandle<TSpectral> Handle to the new sun light

LightHandle<TSpectral> add_light(std::shared_ptr<Light<TSpectral>> light, std::string name = "")¶

Adds a light to the scene.

Parameters:

light – Shared pointer to the light
name – Optional name

Returns:

LightHandle<TSpectral> Handle to the added light

void set_name(const LightHandle<TSpectral> &light_handle, const std::string &name)¶

Sets the name for a light asset.

Parameters:

light_handle – Handle to the light
name – New name

LightHandle<TSpectral> get_light(const std::string &name) const¶

Retrieves a light by name.

Parameters:: name – Name of the light
Returns:: LightHandle<TSpectral> Handle to the light

void delete_light(const LightHandle<TSpectral> &light_handle)¶

Deletes a light from the scene.

Parameters:: light_handle – Handle to the light

UnresolvedObjectHandle<TSpectral> new_unresolved_object(const units::SpectralWattsPerMeterSquared<TSpectral> &spectral_irradiance, std::string name = "")¶

Creates a new unresolved object with spectral irradiance.

Parameters:

spectral_irradiance – Spectral irradiance
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new object

UnresolvedObjectHandle<TSpectral> new_unresolved_object(const units::WattsPerMeterSquared &irradiance, std::string name = "")¶

Creates a new unresolved object with total irradiance.

Parameters:

irradiance – Total irradiance
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new object

UnresolvedObjectHandle<TSpectral> new_unresolved_object_from_magnitude(double visual_magnitude, std::string name = "")¶

Creates a new unresolved object from visual magnitude.

Parameters:

visual_magnitude – Visual magnitude
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new object

UnresolvedObjectHandle<TSpectral> new_unresolved_object_from_magnitude(double visual_magnitude, TSpectral albedo, std::string name = "")¶

Creates a new unresolved object from visual magnitude and albedo.

Parameters:

visual_magnitude – Visual magnitude
albedo – Albedo value
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new object

UnresolvedObjectHandle<TSpectral> new_unresolved_emitter(const units::SpectralWatts<TSpectral> &spectral_power, std::string name = "")¶

Creates a new unresolved emitter with spectral power.

Parameters:

spectral_power – Spectral power
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new emitter

UnresolvedObjectHandle<TSpectral> new_unresolved_emitter(const units::Watt &power, std::string name = "")¶

Creates a new unresolved emitter with total power.

Parameters:

power – Total power
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new emitter

UnresolvedObjectHandle<TSpectral> new_unresolved_sphere(units::Meter radius, TSpectral albedo, std::string name = "")¶

Creates a new unresolved sphere illuminated by all lights in the scene.

Parameters:

radius – Sphere radius
albedo – Albedo value (spectral)
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new sphere

UnresolvedObjectHandle<TSpectral> new_unresolved_sphere(units::Meter radius, float albedo, std::string name = "")¶

Creates a new unresolved sphere illuminated by all lights in the scene.

Parameters:

radius – Sphere radius
albedo – Albedo value (constant)
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new sphere

UnresolvedObjectHandle<TSpectral> new_unresolved_sphere(units::Meter radius, InstanceHandle<TSpectral> sun, std::string name = "")¶

Creates a new unresolved sphere with radius and sun instance.

Parameters:

radius – Sphere radius
sun – Sun instance handle
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new sphere

UnresolvedObjectHandle<TSpectral> new_unresolved_sphere(units::Meter radius, InstanceHandle<TSpectral> sun, TSpectral albedo, std::string name = "")¶

Creates a new unresolved sphere with radius, sun instance, and albedo.

Parameters:

radius – Sphere radius
sun – Sun instance handle
albedo – Albedo value (spectral)
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new sphere

UnresolvedObjectHandle<TSpectral> new_unresolved_sphere(units::Meter radius, InstanceHandle<TSpectral> sun, float albedo, std::string name = "")¶

Creates a new unresolved sphere with radius, sun instance, and albedo.

Parameters:

radius – Sphere radius
sun – Sun instance handle
albedo – Albedo value (constant)
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new sphere

UnresolvedObjectHandle<TSpectral> new_unresolved_asteroid(double H, double G, InstanceHandle<TSpectral> sun, std::string name = "")¶

Creates a new unresolved asteroid with H, G, and sun instance.

Parameters:

H – Absolute magnitude
G – Slope parameter
sun – Sun instance handle
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new asteroid

UnresolvedObjectHandle<TSpectral> new_unresolved_asteroid(double H, double G, InstanceHandle<TSpectral> sun, TSpectral albedo, std::string name = "")¶

Creates a new unresolved asteroid with H, G, sun instance, and albedo.

Parameters:

H – Absolute magnitude
G – Slope parameter
sun – Sun instance handle
albedo – Albedo value (spectral)
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new asteroid

UnresolvedObjectHandle<TSpectral> new_unresolved_asteroid(double H, double G, InstanceHandle<TSpectral> sun, float albedo, std::string name = "")¶

Creates a new unresolved asteroid with H, G, sun instance, and albedo.

Parameters:

H – Absolute magnitude
G – Slope parameter
sun – Sun instance handle
albedo – Albedo value (constant)
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the new asteroid

UnresolvedObjectHandle<TSpectral> add_unresolved_object(std::shared_ptr<UnresolvedObject<TSpectral>> unresolved_object, std::string name = "")¶

Adds an unresolved object to the scene.

Parameters:

unresolved_object – Shared pointer to the unresolved object
name – Optional name

Returns:

UnresolvedObjectHandle<TSpectral> Handle to the added object

void set_name(const UnresolvedObjectHandle<TSpectral> &unresolved_object_handle, const std::string &name)¶

Sets the name for an unresolved object asset.

Parameters:

unresolved – Handle to the unresolved object
name – New name

UnresolvedObjectHandle<TSpectral> get_unresolved_object(const std::string &name) const¶

Retrieves an unresolved object by name.

Parameters:: name – Name of the unresolved object
Returns:: UnresolvedObjectHandle<TSpectral> Handle to the unresolved object

void delete_unresolved_object(const UnresolvedObjectHandle<TSpectral> &unresolved_object_handle)¶

Deletes an unresolved object from the scene.

Parameters:: unresolved_object_handle – Handle to the unresolved object

CameraModelHandle<TSpectral> new_camera_model(std::string name = "")¶

Creates a new camera model.

Parameters:: name – Optional name
Returns:: CameraModelHandle<TSpectral> Handle to the new camera model

void set_name(const CameraModelHandle<TSpectral> &camera_model_handle, const std::string &name)¶

Sets the name for a camera model asset.

Parameters:

camera_model_handle – Handle to the camera model
name – New name

CameraModelHandle<TSpectral> get_camera_model(const std::string &name) const¶

Retrieves a camera model by name.

Parameters:: name – Name of the camera model
Returns:: CameraModelHandle<TSpectral> Handle to the camera model

void delete_camera_model(const CameraModelHandle<TSpectral> &camera_model_handle)¶

Deletes a camera model from the scene.

Parameters:: camera_model_handle – Handle to the camera model

ModelHandle<TSpectral> load_model(const fs::path &file, std::string name = "", unsigned int post_process_flags = ModelLoader<TSpectral>::DEFAULT_POST_PROCESS_FLAGS)¶

Loads a model from file and adds it to the scene.

Parameters:

file – Path to the model file
name – Optional name
post_process_flags – Flags for post-processing

Returns:

ModelHandle<TSpectral> Handle to the loaded model

void set_name(const ModelHandle<TSpectral> &model_handle, const std::string &name)¶

Sets the name for a model asset.

Parameters:

model_handle – Handle to the model
name – New name

ModelHandle<TSpectral> get_model(const std::string &name) const¶

Retrieves a model by name.

Parameters:: name – Name of the model
Returns:: ModelHandle<TSpectral> Handle to the model

void delete_model(const ModelHandle<TSpectral> &model_handle)¶

Deletes a model from the scene.

Parameters:: model_handle – Handle to the model

BSDFHandle<TSpectral> new_bsdf_cook_torrance(std::string name = "")¶

BSDFHandle<TSpectral> new_bsdf_hapke(float h, float B0, float b, float c, std::string name = "")¶

BSDFHandle<TSpectral> new_bsdf_lambertian(std::string name = "")¶

BSDFHandle<TSpectral> new_bsdf_lommel_seeliger(std::string name = "")¶

BSDFHandle<TSpectral> new_bsdf_mcewen(std::string name = "")¶

BSDFHandle<TSpectral> new_bsdf_null(std::string name = "")¶

BSDFHandle<TSpectral> new_bsdf_oren_nayar(std::string name = "")¶

BSDFHandle<TSpectral> add_bsdf(std::shared_ptr<BSDF<TSpectral>> bsdf, std::string name = "")¶

MaterialHandle<TSpectral> new_material(const BSDFHandle<TSpectral> &bsdf, std::string name = "")¶

MaterialHandle<TSpectral> add_material(std::shared_ptr<Material<TSpectral>> material, std::string name = "")¶

DensityFieldHandle<TSpectral> new_constant_density_field(TSpectral absorption, TSpectral scattering, std::string name = "")¶

DensityFieldHandle<TSpectral> add_density_field(std::shared_ptr<DensityField<TSpectral>> density_field, std::string name = "")¶

PhaseFunctionHandle<TSpectral> new_isotropic_phase_function(std::string name = "")¶

PhaseFunctionHandle<TSpectral> add_phase_function(std::shared_ptr<PhaseFunction<TSpectral>> phase_function, std::string name = "")¶

MediumHandle<TSpectral> new_medium(DensityFieldHandle<TSpectral> density_field_handle, PhaseFunctionHandle<TSpectral> phase_function_handle, std::string name = "")¶

MediumHandle<TSpectral> add_medium(std::shared_ptr<Medium<TSpectral>> medium, std::string name = "")¶

void set_background_radiance(Image<TSpectral> background)¶

Set the radiance of the sky behind everything in the scene.

An image is an equirectangular map, looked up by the direction a ray leaves the scene in. A single value (or a 1 x 1 image) is a uniform sky.

With PSF convolution enabled (CameraModel::enable_psf_convolution()), a uniform sky is convolved as if it continued beyond the frame’s edges, which leaves it as it is: a PSF that sums to one gives a uniform sky back. Only the light that geometry adds to the sky, or blocks from it, is spread by the PSF, and with nothing but sky in view the convolution is skipped. A background image is convolved with the rest of the frame as it is, and so darkens toward the frame’s edges, where the sky beyond them is missing.

Parameters:: background – The radiance, as an equirectangular map.
Throws:: std::runtime_error – if it has no pixels, or a pixel is negative or not finite.

void set_background_radiance(TSpectral background)¶

Set a uniform sky. See set_background_radiance(Image<TSpectral>).

Throws:: std::runtime_error – if it is negative or not finite.

void set_background_radiance(float background)¶

Set a uniform sky, from its total radiance spread over the spectrum (see SpectralBins::from_total()). See set_background_radiance(Image<TSpectral>).

Throws:: std::runtime_error – if it is negative or not finite.

TextureHandle<TSpectral> add_texture(Image<TSpectral> &&image, std::string name = "")¶

TextureHandle<float> add_texture(Image<float> &&image, std::string name = "")¶

TextureHandle<Vec3<float>> add_texture(Image<Vec3<float>> &&image, std::string name = "")¶

TextureHandle<Vec3<float>> add_normal_texture(Image<Vec3<float>> &&image, std::string name = "")¶

Add a tangent-space normal map, each pixel’s normal encoded as (n + 1) / 2.

Throws:: std::runtime_error – if the image has no pixels, or a pixel is not finite or encodes no direction (0.5, 0.5, 0.5), which would make its normal NaN.

TextureHandle<Vec3<float>> add_normal_texture(Image<RGB> &&image, std::string name = "")¶

void set_stars(const std::vector<Star<TSpectral>> &stars)¶

Sets the stars in the scene.

Parameters:: stars – Vector of stars

void load_stars(const fs::path &star_catalog_path, const Time &time, float min_magnitude = 100.f)¶

Loads stars from a catalog file.

Parameters:

star_catalog_path – Path to the star catalog
time – Time for proper motion
min_magnitude – Minimum magnitude to load

void load_dynamic_stars(const fs::path &star_catalog_path, const Time &time, float min_magnitude = 100.f)¶

Loads dynamic stars from a catalog file. These can have their proper motion updated by calling update_star_epoch().

Parameters:

star_catalog_path – Path to the star catalog
time – Time for proper motion
min_magnitude – Minimum magnitude to load

void update_star_epoch(const Time &time)¶

void prune_unreferenced_assets()¶: Removes assets not referenced in the scene graph.

void print_meshes() const¶: Prints information about all meshes in the scene.

void print_lights() const¶: Prints information about all lights in the scene.

void print_unresolved_objects() const¶: Prints information about all unresolved objects in the scene.

void print_camera_models() const¶: Prints information about all camera models in the scene.

void print_models() const¶: Prints information about all models in the scene.

void print_graph() const¶: Prints the scene graph hierarchy.

void print_contents() const¶: Prints a summary of the scene contents and graph.

Public Members

RootFrameHandle<TSpectral> root¶