finished documentation of bsq.h

David Mayerich
1 parent 5853ce9b
Showing 1 changed file with 43 additions and 29 deletions Show diff stats
envi/bsq.h
@@ -37,7 +37,7 @@ public:
 	//using binary<T>::getSlice;
 	using binary<T>::R;
-	///This function opens a data file for reading using the class interface.
+	/// Open a data file for reading using the class interface.
 	/// @param filename is the name of the binary file on disk
 	/// @param X is the number of samples along dimension 1
@@ -56,7 +56,7 @@ public:
 	}
-	///This function retrieves a single band (based on index) and stores it in pre-allocated memory.
+	/// Retrieve a single band (based on index) and stores it in pre-allocated memory.
 	/// @param p is a pointer to an allocated region of memory at least X * Y * sizeof(T) in size.
 	/// @param page <= B is the integer number of the band to be copied.
@@ -74,7 +74,7 @@ public:
 		return true;
 	}
-	///This function retrieves a single band (by numerical label) and stores it in pre-allocated memory.
+	/// Retrieve a single band (by numerical label) and stores it in pre-allocated memory.
 	/// @param p is a pointer to an allocated region of memory at least X * Y * sizeof(T) in size.
 	/// @param wavelength is a floating point value (usually a wavelength in spectral data) used as a label for the band to be copied.
@@ -131,7 +131,7 @@ public:
 		return true;
 	}
-	///This function retrieves a single spectrum (B-axis line) at a given (x, y) location and stores it in pre-allocated memory.
+	/// Retrieve a single spectrum (B-axis line) at a given (x, y) location and stores it in pre-allocated memory.
 	/// @param p is a pointer to pre-allocated memory at least B * sizeof(T) in size.
 	/// @param x is the x-coordinate (dimension 1) of the spectrum.
@@ -155,7 +155,7 @@ public:
 		return true;	
 	}
-	///This function retrieves a single pixel and stores it in pre-allocated memory.
+	/// Retrieve a single pixel and stores it in pre-allocated memory.
 	/// @param p is a pointer to pre-allocated memory at least sizeof(T) in size.
 	/// @param n is an integer index to the pixel using linear array indexing.
@@ -177,7 +177,7 @@ public:
 		return true;	
 	}
-	///This function performs baseline correction given a list of baseline points and stores the result in a new BSQ file.
+	/// Perform baseline correction given a list of baseline points and stores the result in a new BSQ file.
 	/// @param outname is the name of the output file used to store the resulting baseline-corrected data.
 	/// @param wls is the list of baseline points based on band labels.	
@@ -282,7 +282,7 @@ public:
 		return true;
 	}
-	///This function normalizes all spectra based on the value of a single band, storing the result in a new BSQ file.
+	/// Normalize all spectra based on the value of a single band, storing the result in a new BSQ file.
 	/// @param outname is the name of the output file used to store the resulting baseline-corrected data.
 	///	@param w is the label specifying the band that the hyperspectral image will be normalized to.
@@ -325,7 +325,7 @@ public:
 		return true;
 	}
-	///This function converts the current BSQ file to a BIP file with the specified file name.
+	/// Convert the current BSQ file to a BIP file with the specified file name.
 	/// @param outname is the name of the output BIP file to be saved to disk.
 	bool bip(std::string outname)
@@ -348,7 +348,7 @@ public:
 		return true;
 	}
-	///This function converts the current BSQ file to a BIL file with the specified file name.
+	/// Convert the current BSQ file to a BIL file with the specified file name.
 	/// @param outname is the name of the output BIL file to be saved to disk.
 	bool bil(std::string outname)
@@ -381,7 +381,7 @@ public:
 		return true;
 	}
-	/// This function returns a baseline corrected band given two adjacent baseline points and their bands. The result is stored in a pre-allocated array.
+	/// Return a baseline corrected band given two adjacent baseline points and their bands. The result is stored in a pre-allocated array.
 	/// @param lb is the label value for the left baseline point
 	/// @param rb is the label value for the right baseline point
@@ -402,7 +402,7 @@ public:
 		return true;
 	}
-	///This function returns a baseline corrected band given two adjacent baseline points. The result is stored in a pre-allocated array.
+	/// Return a baseline corrected band given two adjacent baseline points. The result is stored in a pre-allocated array.
 	/// @param lb is the label value for the left baseline point
 	/// @param rb is the label value for the right baseline point
@@ -428,7 +428,7 @@ public:
 	}
-	///This function calculates the area under the spectrum between two specified points and stores the result in a pre-allocated array.
+	/// Calculate the area under the spectrum between two specified points and stores the result in a pre-allocated array.
 	/// @param lb is the label value for the left baseline point
 	/// @param rb is the label value for the right baseline point
@@ -512,7 +512,7 @@ public:
 		return true;
 	}
-	/// This function computes the ratio of two baseline-corrected peaks. The result is stored in a pre-allocated array.
+	/// Compute the ratio of two baseline-corrected peaks. The result is stored in a pre-allocated array.
 	/// @param lb1 is the label value for the left baseline point for the first peak (numerator)
 	/// @param rb1 is the label value for the right baseline point for the first peak (numerator)
@@ -542,7 +542,7 @@ public:
 		return true;	
 	}
-	/// This function computes the ratio between a peak area and peak height.
+	/// Compute the ratio between a peak area and peak height.
 	/// @param lb1 is the label value for the left baseline point for the first peak (numerator)
 	/// @param rb1 is the label value for the right baseline point for the first peak (numerator)
@@ -575,7 +575,7 @@ public:
 		return true;	
 	}		
-	/// This function computes the ratio between two peak areas.
+	/// Compute the ratio between two peak areas.
 	/// @param lb1 is the label value for the left baseline point for the first peak (numerator)
 	/// @param rb1 is the label value for the right baseline point for the first peak (numerator)
@@ -608,7 +608,7 @@ public:
 		return true;	
 	}		
-	/// This function computes the definite integral of a baseline corrected peak.
+	/// Compute the definite integral of a baseline corrected peak.
 	/// @param lb is the label value for the left baseline point
 	/// @param rb is the label value for the right baseline point
@@ -689,7 +689,7 @@ public:
 		return true;
 	}
-	/// This function computes the centroid of a baseline corrected peak.
+	/// Compute the centroid of a baseline corrected peak.
 	/// @param lb is the label value for the left baseline point
 	/// @param rb is the label value for the right baseline point
@@ -716,7 +716,7 @@ public:
 		return true;	
 	}
-	/// This function creates a mask based on a given band and threshold value.
+	/// Create a mask based on a given band and threshold value.
 	/// All pixels in the
 	/// specified band greater than the threshold are true and all pixels less than the threshold are false.
@@ -740,7 +740,7 @@ public:
 	}
-	/// This function applies a mask file to the BSQ image, setting all values outside the mask to zero.
+	/// Apply a mask file to the BSQ image, setting all values outside the mask to zero.
 	/// @param outfile is the name of the masked output file
 	/// @param p is a pointer to memory of size X * Y, where p(i) = 0 for pixels that will be set to zero.
@@ -772,7 +772,7 @@ public:
 		return true;
 	}
-	/// This function calculates the mean band value (average along B) at each pixel location.
+	/// Calculate the mean band value (average along B) at each pixel location.
 	/// @param p is a pointer to memory of size X * Y * sizeof(T) that will store the band averages.
 	bool band_avg(T* p){
@@ -794,22 +794,26 @@ public:
 		return true;
 	}
-	//calculate the average number of every band
+	/// Calculate the mean value for all masked (or valid) pixels in a band and returns the average spectrum
+
+	/// @param p is a pointer to pre-allocated memory of size [B * sizeof(T)] that stores the mean spectrum
+	/// @param mask is a pointer to memory of size [X * Y] that stores the mask value at each pixel location
 	bool avg_band(T*p, unsigned char* mask){
 		unsigned long long XY = R[0] * R[1];
-		unsigned count = 0;		//number of vaild pixel in a band
+		unsigned count = 0;						//count will store the number of masked pixels
 		T* temp = (T*)malloc(sizeof(T) * XY);
-		//calculate valid pixel number
+		//calculate this loop counts the number of true pixels in the mask
 		for (unsigned j = 0; j < XY; j++){
 			if (mask[j] != 0){
 				count++;
 			}
 		}
-		//calculate average of a band
+		//this loops goes through each band in B (R[2])
+		//	masked (or valid) pixels from that band are averaged and the average is stored in p
 		for (unsigned i = 0; i < R[2]; i++){
 			p[i] = 0;
-			band_index(temp, i);
-			for (unsigned j = 0; j < XY; j++){
+			band_index(temp, i);				//get the band image and store it in temp
+			for (unsigned j = 0; j < XY; j++){	//loop through temp, averaging valid pixels
 				if (mask[j] != 0){
 					p[i] += temp[j] / (T)count;
 				}				
@@ -819,7 +823,11 @@ public:
 		return true;
 	}
-	//calculate correlated matrix
+	/// Calculate the covariance matrix for all masked pixels in the image.
+
+	/// @param co is a pointer to pre-allocated memory of size [B * B] that stores the resulting covariance matrix
+	/// @param avg is a pointer to memory of size B that stores the average spectrum
+	/// @param mask is a pointer to memory of size [X * Y] that stores the mask value at each pixel location
 	bool co_matrix(T* co, T* avg, unsigned char *mask){
 		//memory allocation
 		unsigned long long xy = R[0] * R[1];
@@ -857,7 +865,13 @@ public:
 	}
-	//crop specified area the of the original file
+	/// Crop a region of the image and save it to a new file.
+
+	/// @param outfile is the file name for the new cropped image
+	/// @param x0 is the lower-left x pixel coordinate to be included in the cropped image
+	/// @param y0 is the lower-left y pixel coordinate to be included in the cropped image
+	/// @param x1 is the upper-right x pixel coordinate to be included in the cropped image
+	/// @param y1 is the upper-right y pixel coordinate to be included in the cropped image
 	bool crop(std::string outfile, unsigned x0, unsigned y0, unsigned x1, unsigned y1){
 		//calculate the new number of samples and lines
@@ -886,7 +900,7 @@ public:
 	}
-	//close the file
+	/// Close the file.
 	bool close(){
 		file.close();
 		return true;