From 9261db43c658494d455f32945803ead39b521ffc Mon Sep 17 00:00:00 2001 From: andchybi <160877028+andchybi@users.noreply.github.com> Date: Wed, 28 Feb 2024 12:25:55 +0100 Subject: [PATCH] added code documentation --- src/BoundingBox.hpp | 4 ++++ src/HydroDataReader.hpp | 4 ++++ src/RasterInfo.hpp | 15 +++++++++++++-- src/XYPair.hpp | 6 ++++++ src/analyze_dir.cpp | 6 ++++++ src/clustering.hpp | 31 +++++++++++++++++++++++++++++-- src/csv.hpp | 4 ++++ src/main.cpp | 4 ++++ src/mapper.cpp | 11 +++++++++-- src/polarization.hpp | 7 +++++++ src/rasters.hpp | 30 +++++++++++++++++++++++++++--- src/utils.hpp | 5 ++++- 12 files changed, 117 insertions(+), 10 deletions(-) diff --git a/src/BoundingBox.hpp b/src/BoundingBox.hpp index 4ce89bd..f8ae93a 100644 --- a/src/BoundingBox.hpp +++ b/src/BoundingBox.hpp @@ -1,5 +1,9 @@ #pragma once +/* +* Class representing analyzed bound box +*/ + class BoundingBox { public: diff --git a/src/HydroDataReader.hpp b/src/HydroDataReader.hpp index c0016af..0c3a61f 100644 --- a/src/HydroDataReader.hpp +++ b/src/HydroDataReader.hpp @@ -6,6 +6,10 @@ #include "csv.hpp" #include "types.hpp" +/* +Class for paring discharge data. +*/ + class HydroDataReader { public: diff --git a/src/RasterInfo.hpp b/src/RasterInfo.hpp index 1f12ffd..4e78bb3 100644 --- a/src/RasterInfo.hpp +++ b/src/RasterInfo.hpp @@ -7,6 +7,12 @@ namespace fs = std::filesystem; +/* +* +* Utility class for extracting infromation about satellite imagery +* +*/ + class RasterInfo { public: @@ -22,13 +28,18 @@ class RasterInfo Polarization pol; Date date; }; - +/* +* +* This class contains methods to retrevie acquistiion date and polarization for input satellite imagery filebuf* +* +*/ class RasterInfoExtractor { public: virtual RasterInfo extractFromPath(std::string filepath) = 0; }; +//Extractor for file preprocessed using Hyp3 class AsfExtractor : public RasterInfoExtractor { public: @@ -52,7 +63,7 @@ class AsfExtractor : public RasterInfoExtractor return RasterInfo(filepath, resultPol, resultDate); } }; - +//Extractor for locally processed imagery files (date + polarization) class StdExtractor : public RasterInfoExtractor { public: diff --git a/src/XYPair.hpp b/src/XYPair.hpp index 349c7bc..421a469 100644 --- a/src/XYPair.hpp +++ b/src/XYPair.hpp @@ -1,5 +1,11 @@ #pragma once +/* +* +* Utility script for representing coordinates in the algorothm +* +*/ + class XYPair { public: diff --git a/src/analyze_dir.cpp b/src/analyze_dir.cpp index 7f7fd47..e70b192 100644 --- a/src/analyze_dir.cpp +++ b/src/analyze_dir.cpp @@ -17,6 +17,11 @@ #include #include +/* +* Utility function that contains main() . This script can is used additionaly to analyze and prepare input data for the floodsar +* algorithm. +*/ + namespace fs = std::filesystem; void @@ -75,6 +80,7 @@ main(int argc, char** argv) std::ifstream proj4file(proj4Path); + //get polarization and date info from imagery filenames RasterInfo extractedInfo = extractor->extractFromPath(filepath.string()); std::getline(proj4file, extractedInfo.proj4); diff --git a/src/clustering.hpp b/src/clustering.hpp index df3f1ec..e77513f 100644 --- a/src/clustering.hpp +++ b/src/clustering.hpp @@ -3,9 +3,23 @@ #include #include +/* +* The 2D algorithm that performs clustering on two SAR polarizations at the same time. + +@param vectorVH is a cross polarization +@param vectorVV is a co-polarization +@param numClasses is a number of flooded classes +@param maxiter is a maximum number of iteration to find clusters +@param frac is a fraction of pixels that algorithms analyzes in order to find cluster centroids. + +*/ const std::string kmeansInputFilename = "KMEANS_INPUT"; const int kmeansMinimumPoints = 100; - +/* +* +* Function performs k-means clustering for floodSar +* +*/ void performClustering(std::vector& vectorVH, std::vector& vectorVV, @@ -159,7 +173,14 @@ performClustering(std::vector& vectorVH, ofsPoints << clusterAssignments[i] << "\n"; } } - +/* +Function that returns a vector with classes list +* +* @params clusersFilePath is a prefix for filenemame that stores flood mapping results +* @params classesNum is a number of flood classes +* @params is a strategy how to pick flood classes. Only applicable to 2D algorithm. Possible values: vh, vv, sum. +* +*/ std::vector createFloodClassesList(std::string clustersFilePath, unsigned int classesNum, @@ -202,6 +223,12 @@ createFloodClassesList(std::string clustersFilePath, void +/* +Function to calculate flooder Areas +@params floodedAreas is a vector that is filled in during function invocation. +@params numberofClasses iz total number of classes analyzed by k-means +@params floodClassesNum is a number of flood classes to calculate area +*/ calculateFloodedAreasFromKMeansOutput( std::vector& floodedAreas, // vector to fill unsigned int numberOfClasses, diff --git a/src/csv.hpp b/src/csv.hpp index 833a7ad..ac15914 100644 --- a/src/csv.hpp +++ b/src/csv.hpp @@ -3,6 +3,10 @@ #include #include +/* +* Class for reading a CSV file with discharge data. See exammple -> discharge.csv file +*/ + class CSVRow { public: diff --git a/src/main.cpp b/src/main.cpp index 2e0fe85..5f9508e 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -19,6 +19,10 @@ #include "utils.hpp" #include "clustering.hpp" +/* +* Main function file +*/ + namespace fs = std::filesystem; diff --git a/src/mapper.cpp b/src/mapper.cpp index 46a3194..aa38cac 100644 --- a/src/mapper.cpp +++ b/src/mapper.cpp @@ -19,6 +19,11 @@ namespace fs = std::filesystem; +/* +* +* This is a postprocessing script for transforming floodSar results to rasters. +* +*/ int main(int argc, char** argv) { @@ -34,6 +39,7 @@ main(int argc, char** argv) "a,auto", "automatically use best k-means results"); +//default values for 1D algorithm int numAllClassess = 2; int numFloodClasses = 1; int aa; @@ -67,12 +73,12 @@ main(int argc, char** argv) // base algoritm mapping. floodClasses.push_back(1); std::string pol = userInput["base"].as(); - // bedzie VV albo VH + // either VV or VH pointsFile = "./.floodsar-cache/1d_output/" + pol; mapDirectory = "./mapped/base_algo_pol_" + pol + "/"; } else { - // improved algo mapping. + // 2D algroithm if (userInput.count("auto")) { std::ifstream bestClassStream(".floodsar-cache/kmeans_outputs/best.txt"); @@ -167,6 +173,7 @@ main(int argc, char** argv) std::cout << "Its time to stop. \n"; break; } + //mapPath contains reults raster for particular date mapPath = mapDirectory + dates[dateIndex] + ".tif"; std::filesystem::copy_file(rasterToClassify, mapPath); diff --git a/src/polarization.hpp b/src/polarization.hpp index 47848f8..a5318bc 100644 --- a/src/polarization.hpp +++ b/src/polarization.hpp @@ -2,6 +2,13 @@ #include +/* +* +* Utility scripts for converting strings to polarization and vice versa. +* +*/ + + enum class Polarization { VH, diff --git a/src/rasters.hpp b/src/rasters.hpp index 76938a1..205355d 100644 --- a/src/rasters.hpp +++ b/src/rasters.hpp @@ -7,6 +7,13 @@ #include #include + +/* +* Gets the bounding box of Sentintel Imagery raster +* @param raster is retreived from GDAL +* +*/ + BoundingBox getRasterBoundingBox(GDALDataset* raster) { @@ -41,6 +48,13 @@ getRasterBoundingBox(GDALDataset* raster) return boundingBox; } +/* +* The functions crops satellite imagery in smaller region of interes +* @param zoneBbox defines area of interest +* @param info is a georeference info GDAL +* @param epsgCode is projection code applied in satelltie imagery* +*/ + void cropToZone(BoundingBox zoneBBox, RasterInfo info, std::string epsgCode) { @@ -68,6 +82,13 @@ cropToZone(BoundingBox zoneBBox, RasterInfo info, std::string epsgCode) std::system(command.c_str()); } +/* The function reduces geographcially raster to the area of interest in order to save memory. +* +* @param rasterPaths is a vector of raster information (RasterInfo) of analyzed satellite imageries +* @param aoiDataset is a pointer to imagery data +* @param epsgCode is a cartographic projection code used in imagery (assumed equal to every imagery) +* +*/ void cropRastersToAreaOfInterest(std::vector& rasterPaths, GDALDataset* aoiDataset, @@ -97,6 +118,7 @@ cropRastersToAreaOfInterest(std::vector& rasterPaths, } } +//get imagery projection info void getProjectionInfo(std::string rasterPath, std::string proj4filePath) { @@ -120,8 +142,7 @@ printProjCrs(RasterInfo info) std::system(command.c_str()); } -// returns absolute paths to all images that will take part in calculating the -// result +// returns absolute paths to all images that will take part in calculating the result... std::vector readRasterDirectory(std::string dirname, std::string fileExtension, @@ -183,6 +204,7 @@ mosaicRasters(const std::string targetPath, std::system(command.c_str()); } +//if two rasters with the same are present then mosaicing is performed... void performMosaicking(std::vector& rasterInfos, std::vector& outputVector) @@ -226,6 +248,7 @@ performMosaicking(std::vector& rasterInfos, } } +//prefrom reprojection using GDAL (gdalwarp) std::string performReprojection(RasterInfo& info, std::string epsgCode) { @@ -248,7 +271,7 @@ performReprojection(RasterInfo& info, std::string epsgCode) return filename; } - +//in case of different projection of a raster file.. void reprojectIfNeeded(std::vector& rasters, std::string epsgCode) { @@ -301,6 +324,7 @@ getPixelValuesFromRaster(GDALDataset* raster, CPLFree(buffer); } +// Method to calculae flooder area basing on threshold in 1D algorithm unsigned int calcFloodedArea(GDALDataset* raster, double threshold) { diff --git a/src/utils.hpp b/src/utils.hpp index b08ac25..b88e107 100644 --- a/src/utils.hpp +++ b/src/utils.hpp @@ -12,7 +12,7 @@ struct ClassifiedCentroid double vv; unsigned int cl; }; - +//simple utilites to compare value of centroids by polariztion (vh,vv or sum). struct compareByVH { inline bool operator()(const ClassifiedCentroid& c1, @@ -105,6 +105,7 @@ calcCorrelationCoeff(std::vector& floodedAreaVals, return corr; } +//Converts hydrological date format to standard date format yyyymmdd Date hydrologicalToNormalDate(std::string_view year, std::string_view month, @@ -156,6 +157,7 @@ hydrologicalToNormalDate(std::string_view year, return out; } +//utility function that prints obsElevationMaps to console void printMap(const std::map& m) { @@ -165,6 +167,7 @@ printMap(const std::map& m) std::cout << '\n'; } +//creates neccasary local files void createCacheDirectoryIfNotExists() {