added better comments

Author: thomas-lowe

raycloudtools/raydecimate/raydecimate.cpp

@@ -20,9 +20,9 @@ void usage(int exit_code = 1)
   // clang-format off
   std::cout << "Decimate a ray cloud spatially or temporally" << std::endl;
   std::cout << "usage:" << std::endl;
-  std::cout << "raydecimate raycloud 3 cm   - reduces to one end point every 3 cm" << std::endl;
-  std::cout << "raydecimate raycloud 4 rays - reduces to every fourth ray" << std::endl;
-  std::cout << "raydecimate raycloud 100 cm 1000 rays - A maximum of 1000 rays per metre cubed" << std::endl;
+  std::cout << "raydecimate raycloud 3 cm   - reduces to one end point every 3 cm. A spatially even subsampling" << std::endl;
+  std::cout << "raydecimate raycloud 4 rays - reduces to every fourth ray. A temporally even subsampling (if rays are chronological)" << std::endl;
+  std::cout << "raydecimate raycloud 20 cm 64 rays - A maximum of 64 rays per cubic 20 cm. Retains small-scale details compared to spatial decimation" << std::endl;
   std::cout << "raydecimate raycloud 3 cm/m - reduces to ray ends spaced 3 cm apart for each metre of their length" << std::endl;
   // clang-format off
   exit(exit_code);

raylib/raydecimation.h

@@ -13,9 +13,22 @@
 
 namespace ray
 {
+/// @brief subsample to 1 point per @c vox_width wide voxel in metres
+/// This is a spatially even subsampling, but also emphasises outlier as a side-effect
 bool RAYLIB_EXPORT decimateSpatial(const std::string &file_stub, double vox_width);
+
+/// @brief subsample to every @c num_rays rays
+/// This is an unbiased subsampling, but will be over-sampled in stationary areas as a side-effect
+/// Note that while this is called temporal decimation, it decimates evenly in file order, which isn't 
+/// necessarily temporal order. Though it typically is stored that way on single scans.
 bool RAYLIB_EXPORT decimateTemporal(const std::string &file_stub, int num_rays);
+
+/// @brief subsample to @c num_rays rays (temporally decimated) for each @c vox_width wide voxel
+/// This allows a more even distribution of points while maintaining details better than pure spatial decimation
 bool RAYLIB_EXPORT decimateSpatioTemporal(const std::string &file_stub, double vox_width, int num_rays);
+
+/// @brief decimate to no more than 1 point per voxel of width @c radius_per_length x ray length. 
+/// This is used when error is proportional to ray length, prioritising closer measurements and leaving distant areas sparse
 bool RAYLIB_EXPORT decimateAngular(const std::string &file_stub, double radius_per_length);
 }  // namespace ray