Add doc.

Author: abellgithub

alg/viewshed/util.cpp

@@ -20,6 +20,8 @@ namespace viewshed
 
 /// Normalize a masking angle. Change from clockwise with 0 north (up) to counterclockwise
 /// with 0 to the east (right) and change to radians.
+///
+// @param maskAngle  Masking angle in degrees.
 double normalizeAngle(double maskAngle)
 {
     maskAngle = 90 - maskAngle;
@@ -30,7 +32,12 @@ double normalizeAngle(double maskAngle)
 
 /// Compute the X intersect position on the line Y = y with a ray extending
 /// from (nX, nY) along `angle`.
-///ABELL doc args
+///
+/// @param angle  Angle in radians, standard arrangement.
+/// @param nX  X coordinate of ray endpoint.
+/// @param nY  Y coordinte of ray endpoint.
+/// @param y  Horizontal line where Y = y.
+/// @return  X intersect or NaN
 double horizontalIntersect(double angle, int nX, int nY, int y)
 {
     double x = std::numeric_limits<double>::quiet_NaN();
@@ -54,6 +61,14 @@ double horizontalIntersect(double angle, int nX, int nY, int y)
     return x;
 }
 
+/// Compute the X intersect position on the line Y = y with a ray extending
+/// from (nX, nY) along `angle`.
+///
+/// @param angle  Angle in radians, standard arrangement.
+/// @param nX  X coordinate of ray endpoint.
+/// @param nY  Y coordinte of ray endpoint.
+/// @param y  Horizontal line where Y = y.
+/// @return  Rounded X intersection of the sentinel INVALID_ISECT
 int hIntersect(double angle, int nX, int nY, int y)
 {
     double x = horizontalIntersect(angle, nX, nY, y);
@@ -62,6 +77,14 @@ int hIntersect(double angle, int nX, int nY, int y)
     return static_cast<int>(std::round(x));
 }
 
+/// Compute the X intersect on one of the horizontal edges of a window
+/// with a ray extending from (nX, nY) along `angle`, clamped the the extent of a window.
+///
+/// @param angle  Angle in radians, standard arrangement.
+/// @param nX  X coordinate of ray endpoint.
+/// @param nY  Y coordinte of ray endpoint.
+/// @param win  Window to intersect.
+/// @return  X intersect, clamped to the window extent.
 int hIntersect(double angle, int nX, int nY, const Window &win)
 {
     if (ARE_REAL_EQUAL(angle, M_PI))
@@ -74,9 +97,14 @@ int hIntersect(double angle, int nX, int nY, const Window &win)
     return std::clamp(static_cast<int>(std::round(x)), win.xStart, win.xStop);
 }
 
-/// Compute the Y intersect position on the line X = x with a ray extending
+/// Compute the X intersect position on the line Y = y with a ray extending
 /// from (nX, nY) along `angle`.
-///ABELL doc args
+///
+/// @param angle  Angle in radians, standard arrangement.
+/// @param nX  X coordinate of ray endpoint.
+/// @param nY  Y coordinte of ray endpoint.
+/// @param y  Vertical  line where X = x.
+/// @return  Y intersect or NaN
 double verticalIntersect(double angle, int nX, int nY, int x)
 {
     double y = std::numeric_limits<double>::quiet_NaN();
@@ -100,6 +128,14 @@ double verticalIntersect(double angle, int nX, int nY, int x)
     return y;
 }
 
+/// Compute the X intersect position on the line Y = y with a ray extending
+/// from (nX, nY) along `angle`.
+///
+/// @param angle  Angle in radians, standard arrangement.
+/// @param nX  X coordinate of ray endpoint.
+/// @param nY  Y coordinte of ray endpoint.
+/// @param y  Horizontal line where X = x.
+/// @return  Rounded Y intersection of the sentinel INVALID_ISECT
 int vIntersect(double angle, int nX, int nY, int x)
 {
     double y = verticalIntersect(angle, nX, nY, x);
@@ -108,6 +144,15 @@ int vIntersect(double angle, int nX, int nY, int x)
     return static_cast<int>(std::round(y));
 }
 
+/// Compute the Y intersect on one of the vertical edges of a window
+/// with a ray extending from (nX, nY) along `angle`, clamped the the extent
+/// of the window.
+///
+/// @param angle  Angle in radians, standard arrangement.
+/// @param nX  X coordinate of ray endpoint.
+/// @param nY  Y coordinte of ray endpoint.
+/// @param win  Window to intersect.
+/// @return  y intersect, clamped to the window extent.
 int vIntersect(double angle, int nX, int nY, const Window &win)
 {
     if (ARE_REAL_EQUAL(angle, M_PI / 2))
@@ -120,8 +165,12 @@ int vIntersect(double angle, int nX, int nY, const Window &win)
     return std::clamp(static_cast<int>(std::round(y)), win.yStart, win.yStop);
 }
 
-// Determine if ray is in the slice between two rays starting at `start` and
-// going clockwise to `end` (inclusive). [start, end]
+/// Determine if ray is in the slice between two rays starting at `start` and
+/// going clockwise to `end` (inclusive). [start, end]
+/// @param  start  Start angle.
+/// @param  end  End angle.
+/// @param  test  Test angle.
+/// @return  Whether `test` lies in the slice [start, end]
 bool rayBetween(double start, double end, double test)
 {
     // Our angles go counterclockwise, so swap start and end

alg/viewshed/viewshed.cpp

@@ -217,16 +217,26 @@ bool getTransforms(GDALRasterBand &band, double *pFwdTransform,
     return true;
 }
 
+/// Shrink the extent of a window to just cover the slice defined by rays from
+/// (nX, nY) and [startAngle, endAngle]
+///
+/// @param oOutExtent  Window to modify
+/// @param nX  X coordinate of ray endpoint.
+/// @param nY  Y coordinate of ray endpoint.
+/// @param startAngle  Start angle of slice (standard mathmatics notion, in radians)
+/// @param endAngle  End angle of slice (standard mathmatics notion, in radians)
 void shrinkWindowForAngles(Window &oOutExtent, int nX, int nY,
                            double startAngle, double endAngle)
 {
+    /// NOTE: This probably doesn't work when the observer is outside the raster and
+    ///   needs to be enhanced for that case.
+
     if (startAngle == endAngle)
         return;
 
     Window win = oOutExtent;
 
     // Set the X boundaries for the angles
-    //ABELL - Verify for out-of-raster.
     int startAngleX = hIntersect(startAngle, nX, nY, win);
     int stopAngleX = hIntersect(endAngle, nX, nY, win);
 
@@ -248,7 +258,6 @@ void shrinkWindowForAngles(Window &oOutExtent, int nX, int nY,
     }
 
     // Set the Y boundaries for the angles
-    //ABELL - Verify for out-of-raster.
     int startAngleY = vIntersect(startAngle, nX, nY, win);
     int stopAngleY = vIntersect(endAngle, nX, nY, win);
 

alg/viewshed/viewshed_executor.cpp

@@ -29,14 +29,20 @@ namespace viewshed
 namespace
 {
 
-bool valid(int x)
+/// Determines whether a value is a valid intersection coordinate.
+/// @param  i  Value to test.
+/// @return  True if the value doesn't represent an invalid intersection.
+bool valid(int i)
 {
-    return x != INVALID_ISECT;
+    return i != INVALID_ISECT;
 }
 
-bool invalid(int x)
+/// Determines whether a value is an invalid intersection coordinate.
+/// @param  i  Value to test.
+/// @return  True if the value represents an invalid intersection.
+bool invalid(int i)
 {
-    return !valid(x);
+    return !valid(i);
 }
 
 /// Calculate the height at nDistance units along a line through the origin given the height
@@ -454,6 +460,11 @@ void ViewshedExecutor::processFirstLineLeft(const LineLimits &ll,
     maskLineLeft(vResult, ll, m_nY);
 }
 
+/// Mask cells based on angle intersection to the left of the observer.
+///
+/// @param vResult  Result raaster line.
+/// @param nLine  Line number.
+/// @return  True when all cells have been masked.
 bool ViewshedExecutor::maskAngleLeft(std::vector<double> &vResult, int nLine)
 {
     auto clamp = [this](int x)
@@ -510,6 +521,11 @@ bool ViewshedExecutor::maskAngleLeft(std::vector<double> &vResult, int nLine)
     return false;
 }
 
+/// Mask cells based on angle intersection to the right of the observer.
+///
+/// @param vResult  Result raaster line.
+/// @param nLine  Line number.
+/// @return  True when all cells have been masked.
 bool ViewshedExecutor::maskAngleRight(std::vector<double> &vResult, int nLine)
 {
     int lineLength = static_cast<int>(vResult.size());
@@ -571,6 +587,11 @@ bool ViewshedExecutor::maskAngleRight(std::vector<double> &vResult, int nLine)
     return false;
 }
 
+/// Perform angle and min/max masking to the left of the observer.
+///
+/// @param vResult  Raster line to mask.
+/// @param ll  Min/max line limits.
+/// @param nLine  Line number.
 void ViewshedExecutor::maskLineLeft(std::vector<double> &vResult,
                                     const LineLimits &ll, int nLine)
 {
@@ -586,6 +607,11 @@ void ViewshedExecutor::maskLineLeft(std::vector<double> &vResult,
                   oOpts.outOfRangeVal);
 }
 
+/// Perform angle and min/max masking to the right of the observer.
+///
+/// @param vResult  Raster line to mask.
+/// @param ll  Min/max line limits.
+/// @param nLine  Line number.
 void ViewshedExecutor::maskLineRight(std::vector<double> &vResult,
                                      const LineLimits &ll, int nLine)
 {
@@ -783,7 +809,9 @@ void ViewshedExecutor::processLineRight(int nYOffset, LineLimits &ll,
     maskLineRight(vResult, ll, nLine);
 }
 
-// Apply angular mask to the initial X position.  Assumes m_nX is in the raster.
+/// Apply angular mask to the initial X position.  Assumes m_nX is in the raster.
+/// @param vResult  Raster line on which to apply mask.
+/// @param nLine  Line number.
 void ViewshedExecutor::maskInitial(std::vector<double> &vResult, int nLine)
 {
     if (!oOpts.angleMasking())
@@ -952,6 +980,12 @@ bool ViewshedExecutor::run()
     return true;
 }
 
+/// Mask cells lower than the low pitch angle of intersection by setting the value
+/// to the intersection value.
+///
+/// @param dfZ  Initial/modified cell height.
+/// @param nXOffset  Cell X offset from observer.
+/// @param nYOffset  Cell Y offset from observer.
 void ViewshedExecutor::maskLowPitch(double &dfZ, int nXOffset, int nYOffset)
 {
     if (std::isnan(m_lowTanPitch))
@@ -963,6 +997,13 @@ void ViewshedExecutor::maskLowPitch(double &dfZ, int nXOffset, int nYOffset)
         dfZ = dfZmask;
 }
 
+/// Mask cells higher than the high pitch angle of intersection by setting the value
+/// to out-of-range.
+///
+/// @param dfResult  Result value.
+/// @param dfZ  Cell height.
+/// @param nXOffset  Cell X offset from observer.
+/// @param nYOffset  Cell Y offset from observer.
 void ViewshedExecutor::maskHighPitch(double &dfResult, double dfZ, int nXOffset,
                                      int nYOffset)
 {