From d2c66d47828ea53fea0b3a55d1b76c6e952a3abe Mon Sep 17 00:00:00 2001 From: Alexander Bock Date: Wed, 15 Jan 2025 11:53:01 +0100 Subject: [PATCH] Add documentation of spacecraftinstrument module types (closes #1847) --- .../dashboard/dashboarditeminstruments.cpp | 6 ++++++ modules/spacecraftinstruments/rendering/renderablefov.cpp | 6 +++++- .../rendering/renderablemodelprojection.cpp | 6 ++++++ .../rendering/renderableplaneprojection.cpp | 6 ++++++ .../rendering/renderableplanetprojection.cpp | 6 ++++++ .../rendering/renderableshadowcylinder.cpp | 6 ++++++ 6 files changed, 35 insertions(+), 1 deletion(-) diff --git a/modules/spacecraftinstruments/dashboard/dashboarditeminstruments.cpp b/modules/spacecraftinstruments/dashboard/dashboarditeminstruments.cpp index 151e7c8baa..da1bebe296 100644 --- a/modules/spacecraftinstruments/dashboard/dashboarditeminstruments.cpp +++ b/modules/spacecraftinstruments/dashboard/dashboarditeminstruments.cpp @@ -74,6 +74,12 @@ namespace { return glm::vec2(std::max(lhs.x, rhs.x), lhs.y + rhs.y); } + // This dashboard item shows information about the status of individual instruments + // onboard a spacecraft with regards to upcoming image capture. An image sequence has + // to be registered in order to be able to show the necessary information. The + // dashboard item shows a visual representation on how much time has passed since the + // previous image capture and how much time remains until the instrument captures the + // next image. struct [[codegen::Dictionary(DashboardItemInstruments)]] Parameters { // [[codegen::verbatim(ActiveColorInfo.description)]] std::optional activeColor [[codegen::color()]]; diff --git a/modules/spacecraftinstruments/rendering/renderablefov.cpp b/modules/spacecraftinstruments/rendering/renderablefov.cpp index 5a8da0188c..40e980d6bb 100644 --- a/modules/spacecraftinstruments/rendering/renderablefov.cpp +++ b/modules/spacecraftinstruments/rendering/renderablefov.cpp @@ -142,7 +142,11 @@ namespace { } } - // Needs support for std::map first for the frameConversions + // This Renderable type shows a visual representation of a spacecraft instrument's + // field-of-view. Information about the field-of-view are extracted from SPICE kernels + // that must be loaded with the correct information. By default a field-of-view is + // only visible while an instrument is active, but the field-of-view can be made + // visible at all times through the `AlwaysDrawFov` setting. struct [[codegen::Dictionary(RenderableFov)]] Parameters { // The SPICE name of the source body for which the field of view should be // rendered. diff --git a/modules/spacecraftinstruments/rendering/renderablemodelprojection.cpp b/modules/spacecraftinstruments/rendering/renderablemodelprojection.cpp index 7f724cc3dc..8c16dca39a 100644 --- a/modules/spacecraftinstruments/rendering/renderablemodelprojection.cpp +++ b/modules/spacecraftinstruments/rendering/renderablemodelprojection.cpp @@ -47,6 +47,12 @@ namespace { openspace::properties::Property::Visibility::NoviceUser }; + // Similarly to the [RenderablePlaneProjection](renderableplaneprojection) and + // [RenderablePlanetProjection](renderableplanetprojection), this Renderable type + // servers as a potential target for image projections from a spacecraft's instrument. + // This renderable will determine whenever an image in a currently loaded image + // sequence is projected whether that instrument's field of view intersects this model + // and will correctly project the captured image onto the model. struct [[codegen::Dictionary(RenderableModelProjection)]] Parameters { // The file or files that should be loaded, that specifies the model to load. The // file can contain filesystem tokens or can be specified relative to the diff --git a/modules/spacecraftinstruments/rendering/renderableplaneprojection.cpp b/modules/spacecraftinstruments/rendering/renderableplaneprojection.cpp index 47cf8125cc..847d78dc88 100644 --- a/modules/spacecraftinstruments/rendering/renderableplaneprojection.cpp +++ b/modules/spacecraftinstruments/rendering/renderableplaneprojection.cpp @@ -44,6 +44,12 @@ namespace { constexpr std::string_view _loggerCat = "RenderablePlaneProjection"; + // This specialized Renderable type is used as a target for projections from a + // spacecraft instrument. Similarly to the + // [RenderablePlanetProject](renderableplanetprojection) it uses the spacecraft's + // position and orientation and information about an instruments field-of-view and + // set of images to project a captured image. In the case of this renderable the + // target geometry is a two-dimensional plane that the image is projected on. struct [[codegen::Dictionary(RenderablePlaneProjection)]] Parameters { // The SPICE name of the spacecraft from which the projection is performed. std::string spacecraft; diff --git a/modules/spacecraftinstruments/rendering/renderableplanetprojection.cpp b/modules/spacecraftinstruments/rendering/renderableplanetprojection.cpp index d4e185c243..c55297182b 100644 --- a/modules/spacecraftinstruments/rendering/renderableplanetprojection.cpp +++ b/modules/spacecraftinstruments/rendering/renderableplanetprojection.cpp @@ -137,6 +137,12 @@ namespace { openspace::properties::Property::Visibility::AdvancedUser }; + // This Renderable serves as a potential target for images projected from a + // spacecraft's instrument. Images have to be loaded into an image sequence first and + // when it is then time to project an image into the world from the point of view of + // the instrument, the field-of-view will be checked against the extent of this + // planetary body. If the field-of-view intersects, the image gets correctly projected + // onto the surface. struct [[codegen::Dictionary(RenderablePlanetProjection)]] Parameters { // Contains information about projecting onto this planet. ghoul::Dictionary projection diff --git a/modules/spacecraftinstruments/rendering/renderableshadowcylinder.cpp b/modules/spacecraftinstruments/rendering/renderableshadowcylinder.cpp index fc8737ce5a..bc9764f25e 100644 --- a/modules/spacecraftinstruments/rendering/renderableshadowcylinder.cpp +++ b/modules/spacecraftinstruments/rendering/renderableshadowcylinder.cpp @@ -105,6 +105,12 @@ namespace { openspace::properties::Property::Visibility::AdvancedUser }; + // This Renderable displays the shadow cylinder behind a planetary body. Given the + // SPICE name of a planetary body and an observer, it will show a cylinder extending + // behind the body away from the observer to highlight the areas of space from which + // the observer is occluded by the body. A concrete example is using the Sun as the + // observer, in which case the shadow cylinder indicates the areas in which there is + // darkness. struct [[codegen::Dictionary(RenderableShadowCylinder)]] Parameters { // [[codegen::verbatim(NumberPointsInfo.description)]] std::optional numberOfPoints;