📝 Add some comments

tools/eclipse-shadow-generator/LimbDarkening.cuh

@@ -12,17 +12,17 @@
 
 namespace common {
 
-/// This struct implements a simple wavelength-independent limb darkening model.
+// This implements a simple wavelength-independent limb darkening model.
 class LimbDarkening {
 
  public:
- /// This computes the average brightness over the entire solar disc by sampling so that the get()
- /// method can return normalized values.
+ // This computes the average brightness over the entire solar disc by sampling so that the get()
+ // method can return normalized values.
  void __host__ __device__ init();
 
- /// Returns the Sun's brightness at the given radial distance to the center of the solar disc
- /// between [0...1]. The returned values are normalized so that the average brightness over entire
- /// disc is one.
+ // Returns the Sun's brightness at the given radial distance to the center of the solar disc
+ // between [0...1]. The returned values are normalized so that the average brightness over entire
+ // disc is one.
  double __host__ __device__ get(double r) const;
 
  private:

tools/eclipse-shadow-generator/advanced_modes.cu

@@ -82,16 +82,8 @@ __global__ void computeShadowMap(common::Output output, common::Mapping mapping,
  uint32_t samplesY = 64;
  glm::vec3 indirectIlluminance(0.0);
 
- double phiOcc, phiSun, delta;
- uint32_t iterations = math::mapPixelToAngles(
- glm::ivec2(x, y), output.mSize, mapping, geometry, phiOcc, phiSun, delta);
-
- if (i == 100) {
- printf("phiSun: %f\n", phiSun);
- printf("phiOcc: %f\n", phiOcc);
- printf("delta: %f\n", delta);
- printf("iterations: %d\n", iterations);
- }
+ double phiOcc, phiSun, delta;
+ math::mapPixelToAngles(glm::ivec2(x, y), output.mSize, mapping, geometry, phiOcc, phiSun, delta);
 
  double occDist = geometry.mRadiusOcc / glm::sin(phiOcc);
  double sunDist = geometry.mRadiusSun / glm::sin(phiSun);

tools/eclipse-shadow-generator/advanced_modes.cuh

@@ -11,15 +11,22 @@
 #include <string>
 #include <vector>
 
+// The "advanced" modes compute eclipse shadows for spherical bodies which have an atmosphere. The
+// "bruneton" mode uses the Bruneton precomputed atmospheric scattering model to compute the shadow
+// map. The required input data is precomputed using the "bruneton-preprocessor" tool of the
+// csp-atmospheres plugin. The "planetView" and "atmoView" modes render the atmosphere of a planet
+// from the perspective of a given location in the shadow map for debugging and visualization
+// purposes.
+
 namespace advanced {
 
 // Computes the shadow map evaluating the Bruneton precomputed atmospheric scattering model for each
 // position in the shadow map.
 int brunetonMode(std::vector<std::string> const& arguments);
 
 // Draws the atmosphere of a planet into a texture as seen through a pinhole camera. The atmospheric
-// scattering data, the position of the observer relative to the planet and the sun's direction are
-// given via command line arguments.
+// scattering data and the position of the observer in shadow map coordinates are given via the
+// command line arguments.
 int planetViewMode(std::vector<std::string> const& arguments);
 
 // Same as planetMode, but an angular parametrization is used so that the atmosphere fills the

tools/eclipse-shadow-generator/atmosphere_rendering.cuh

@@ -14,6 +14,8 @@
 
 namespace advanced {
 
+// These input textures are required for the Bruneton precomputed atmospheric scattering model.
+// They have to be precomputed using the "bruneton-preprocessor" tool of the csp-atmospheres plugin.
 struct Textures {
  cudaTextureObject_t mPhase;
  cudaTextureObject_t mThetaDeviation;
@@ -29,8 +31,10 @@ struct Textures {
  double mMuSMin;
 };
 
-__host__ Textures loadTextures(std::string const& path);
+// Loads all required textures from the given output directory from the Bruneton preprocessor tool.
+Textures loadTextures(std::string const& path);
 
+// Computes the luminance of the atmosphere for the given geometry.
 __device__ glm::vec3 getLuminance(glm::dvec3 camera, glm::dvec3 viewRay, glm::dvec3 sunDirection,
  common::Geometry const& geometry, common::LimbDarkening const& limbDarkening,
  Textures const& textures, double phiSun);

tools/eclipse-shadow-generator/common.hpp

@@ -10,34 +10,45 @@
 
 #include "../../../src/cs-utils/CommandLine.hpp"
 
-////////////////////////////////////////////////////////////////////////////////////////////////////
-// Common functionality which is used by multiple modes. //
-////////////////////////////////////////////////////////////////////////////////////////////////////
-
 #include <cstdint>
 
 namespace common {
 
+// This is used to describe the different shadow-map parameterization variants described in figure
+// 10 of "Real-Time Rendering of Eclipses without Incorporation of Atmospheric Effects". The values
+// can be set via command line arguments.
 struct Mapping {
  bool mIncludeUmbra = false;
  double mExponent = 1.0;
 };
 
+// This is used to describe the output file and resolution. The values can be set via command line
+// arguments. The buffer is allocated and filled by the shadow-map generator.
 struct Output {
  std::string mFile = "shadow.hdr";
  uint32_t mSize = 512;
  float* mBuffer;
 };
 
+// When computing an eclipse shadow involving atmospheric effects, the geometry of the Sun,
+// occluding body, and its atmosphere are needed. The values can be set via command line arguments.
 struct Geometry {
  double mRadiusOcc = 6370900.0;
  double mRadiusAtmo = 6451000.0;
  double mRadiusSun = 696340000.0;
  double mSunOccDist = 149597870700.0;
 };
 
+// This adds the command line arguments for the shadow-map parameterization to the given
+// CommandLine object.
 void addMappingFlags(cs::utils::CommandLine& commandLine, Mapping& settings);
+
+// This adds the command line arguments for the output file and resolution to the given
+// CommandLine object.
 void addOutputFlags(cs::utils::CommandLine& commandLine, Output& settings);
+
+// This adds the command line arguments for the geometry of the Sun, occluding body, and its
+// atmosphere to the given CommandLine object.
 void addGeometryFlags(cs::utils::CommandLine& commandLine, Geometry& settings);
 
 } // namespace common

tools/eclipse-shadow-generator/simple_modes.cu

@@ -14,8 +14,6 @@
 
 #include <stb_image_write.h>
 
-#include <cstdint>
-
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
 namespace {
@@ -47,9 +45,8 @@ __global__ void computeLimbDarkeningShadow(
  double radiusOcc, distance;
  math::mapPixelToRadii(glm::ivec2(x, y), output.mSize, mapping, radiusOcc, distance);
 
- double sunArea = math::getCircleArea(1.0);
-
- float intensity = static_cast<float>(
+ double sunArea = math::getCircleArea(1.0);
+ float intensity = static_cast<float>(
  1 - math::sampleCircleIntersection(1.0, radiusOcc, distance, limbDarkening) / sunArea);
 
  writeAsRGBValue(intensity, output.mBuffer, i);
@@ -70,8 +67,7 @@ __global__ void computeCircleIntersectionShadow(common::Mapping mapping, common:
  math::mapPixelToRadii(glm::ivec2(x, y), output.mSize, mapping, radiusOcc, distance);
 
  double sunArea = math::getCircleArea(1.0);
-
- float intensity =
+ float intensity =
  static_cast<float>(1.0 - math::getCircleIntersection(1.0, radiusOcc, distance) / sunArea);
 
  writeAsRGBValue(intensity, output.mBuffer, i);

tools/eclipse-shadow-generator/simple_modes.cuh

@@ -5,16 +5,23 @@
 // SPDX-FileCopyrightText: German Aerospace Center (DLR) <cosmoscout@dlr.de>
 // SPDX-License-Identifier: MIT
 
-#ifndef SIMPLE_HPP
-#define SIMPLE_HPP
+#ifndef SIMPLE_MODES_HPP
+#define SIMPLE_MODES_HPP
 
 #include <string>
 #include <vector>
 
+// The "simple" modes compute eclipse shadows for spherical bodies which do not have an atmosphere.
+// The most accurate mode is "limbDarkeningMode", which uses a limb darkening function to model the
+// surface brightness of the Sun. The other modes are less accurate, and are mostly provided for
+// comparison purposes. More details can be found in the paper "Real-Time Rendering of Eclipses
+// without Incorporation of Atmospheric Effects"
+// (https://onlinelibrary.wiley.com/doi/full/10.1111/cgf.14676).
+
 namespace simple {
 
-// Computes the shadow map by sampling the intersection area between circles representing the Sun
-// and the occluder. This makes use of the global limb darkening function.
+// Computes the shadow map by sampling a limb-darkening model in the intersection area between
+// circles representing the Sun and the occluder.
 int limbDarkeningMode(std::vector<std::string> const& arguments);
 
 // Computes the shadow map by analytically computing the intersection area between circles
@@ -33,4 +40,4 @@ int smoothstepMode(std::vector<std::string> const& arguments);
 
 } // namespace simple
 
-#endif // SIMPLE_HPP
+#endif // SIMPLE_MODES_HPP

tools/eclipse-shadow-generator/tiff_utils.cpp

@@ -10,7 +10,7 @@
 #include <iostream>
 #include <tiffio.h>
 
-namespace tiff_utils {
+namespace {
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
@@ -29,6 +29,35 @@ std::vector<float> addAlphaChannel(std::vector<float> const& rgbData) {
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
+} // namespace
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+namespace tiff_utils {
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+uint32_t getNumLayers(std::string const& path) {
+ auto* data = TIFFOpen(path.c_str(), "r");
+
+ if (!data) {
+ std::cerr << "Failed to open TIFF file'" << path << "' " << std::endl;
+ return 0;
+ }
+
+ uint32_t numLayers = 0;
+
+ do {
+ numLayers++;
+ } while (TIFFReadDirectory(data));
+
+ TIFFClose(data);
+
+ return numLayers;
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
 RGBATexture read2DTexture(std::string const& path, uint32_t layer) {
  RGBATexture texture;
 

tools/eclipse-shadow-generator/tiff_utils.hpp

@@ -10,7 +10,6 @@
 
 #include <cstdint>
 #include <string>
-#include <tuple>
 #include <vector>
 
 namespace tiff_utils {
@@ -20,6 +19,13 @@ struct RGBATexture {
  std::vector<float> data;
 };
 
+// This helper function returns the number of layers in the given tiff file.
+uint32_t getNumLayers(std::string const& path);
+
+// This helper function reads a 2D RGB tiff image from the given path and returns the data as a
+// vector of floats. The data is stored in the order R, G, B, A, R, G, B, A, ... The alpha channel
+// is always 1.0 but is still included in the returned vector for easier upload to the CUDA device.
+// The optional layer parameter can be used to read a specific layer from a multi-layer tiff file.
 RGBATexture read2DTexture(std::string const& path, uint32_t layer = 0);
 
 } // namespace tiff_utils