Scene¶

template<IsSpectral TSpectral> class Scene¶

Scene graph and asset manager for a rendered world.

The Scene class manages all assets (meshes, 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 – Spectral type used for asset spectral properties

Public Functions

Scene(const Scene&) = delete¶

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

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

MeshHandle<TSpectral> add_mesh(Mesh<TSpectral> &&mesh, std::string name = "")¶

Adds a mesh to the scene.

Parameters:

mesh – Mesh to add (moved)
name – Optional name for the mesh

Returns:

MeshHandle<TSpectral> Handle to the added mesh

void set_name(const MeshHandle<TSpectral> &mesh_handle, const std::string &name)¶

Sets the name for a mesh asset.

Parameters:

mesh_handle – Handle to the mesh
name – New name

MeshHandle<TSpectral> get_mesh(const std::string &name)¶

Retrieves a mesh by name.

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

void delete_mesh(const MeshHandle<TSpectral> &mesh_handle)¶

Deletes a mesh from the scene.

Parameters:: mesh_handle – Handle to the mesh

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

Creates a new point light with spectral power.

Parameters:

spectral_power – Spectral power of the light
name – Optional name

Returns:

LightHandle<TSpectral> Handle to the new light

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

Creates a new point light with total power.

Parameters:

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.

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)¶

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, 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)¶

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)¶

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)¶

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

void add_star(const Star<TSpectral> &star)¶

Adds a star to the scene.

Parameters:: star – Star to add

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 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¶