Doxygen comments for bil, bsq, bip. Removed JPEG library from image.h

David Mayerich
1 parent e0c22b85
Showing 4 changed files with 293 additions and 49 deletions Show diff stats
envi/bil.h
envi/bip.h
envi/bsq.h
image/image.h
@@ -8,6 +8,15 @@
  
 namespace stim{
  
+/**
+	The BIL class represents a 3-dimensional binary file stored using band interleaved by line (BIL) image encoding. The binary file is stored
+	such that X-Z "frames" are stored sequentially to form an image stack along the y-axis. When accessing the data sequentially on disk,
+	the dimensions read, from fastest to slowest, are X, Z, Y.
+
+	This class is optimized for data streaming, and therefore supports extremely large (terabyte-scale) files. Data is loaded from disk
+	on request. Functions used to access data are written to support efficient reading.
+*/
+
 template <typename T>
  
 class bil: public binary<T> {
@@ -22,7 +31,14 @@ public:
 	using binary<T>::file;
 	using binary<T>::R;
  
-	//open a file, given the file and its header's names
+	/// 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
+	/// @param Y is the number of samples (lines) along dimension 2
+	/// @param B is the number of samples (bands) along dimension 3
+	/// @param header_offset is the number of bytes (if any) in the binary header
+	/// @param wavelengths is an optional STL vector of size B specifying a numerical label for each band
 	bool open(std::string filename, unsigned int X, unsigned int Y, unsigned int B, unsigned int header_offset, std::vector<double> wavelengths){
  
 		w = wavelengths;
@@ -31,7 +47,10 @@ public:
  
 	}
  
-	//save one band of the file into the memory, and return the pointer
+	/// 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.
 	bool band_index( T * p, unsigned int page){
  
 		unsigned int L = R[0] * sizeof(T);		//caculate the number of bytes in a sample line
@@ -52,6 +71,10 @@ public:
 		return true;
 	}
  
+	/// 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.
 	bool band( T * p, double wavelength){
  
 		//if there are no wavelengths in the BSQ file
@@ -151,7 +174,11 @@ public:
 		return true;		
 	}
  
-	//save one pixel of the BIP file into the memory, and return the pointer
+	/// 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.
+	/// @param y is the y-coordinate (dimension 2) of the spectrum.
 	bool spectrum(T * p, unsigned x, unsigned y){
  
 		if ( x >= R[0] || y >= R[1]){							//make sure the sample and line number is right
@@ -173,7 +200,10 @@ public:
 		return true;	
 	}
  
-	//save one pixel into 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.
 	bool pixel(T * p, unsigned n){
  
 		//calculate the corresponding x, y
@@ -199,7 +229,10 @@ public:
  
 	}
  
-	//(BIL) baseline correction
+	/// 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.
 	bool baseline(std::string outname, std::vector<double> wls){
  
 		unsigned N = wls.size();			//get the number of baseline points
@@ -308,7 +341,11 @@ public:
  
 	}
  
-	// normalize the BIL 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.
+	///	@param t is a threshold specified such that a spectrum with a value at w less than t is set to zero. Setting this threshold allows the user to limit division by extremely small numbers.
 	bool normalize(std::string outname, double w, double t = 0.0)
 	{
 		unsigned int B = R[2];		//calculate the number of bands
@@ -352,7 +389,9 @@ public:
 		return true;
 	}
  
-	//convert BIL file to BSQ file and save it
+	/// Convert the current BIL file to a BSQ file with the specified file name.
+
+	/// @param outname is the name of the output BSQ file to be saved to disk.
 	bool bsq(std::string outname)
 	{
 		unsigned int S = R[0] * R[1] * sizeof(T);		//calculate the number of bytes in a band
@@ -374,7 +413,9 @@ public:
 		return true;
 	}
  
-	//convert bil file to bip file and save it
+	/// Convert the current BIL 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)
 	{
 		unsigned int S = R[0] * R[2] * sizeof(T);		//calculate the number of bytes in a ZX slice
@@ -408,7 +449,14 @@ public:
 	}
  
  
-	//providing the left and the right bound data, return baseline-corrected band height
+	/// 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
+	/// @param lp is a pointer to an array holding the band image for the left baseline point
+	/// @param rp is a pointer to an array holding the band image for the right baseline point
+	/// @param wavelength is the label value for the requested baseline-corrected band
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size.
 	bool baseline_band(double lb, double rb, T* lp, T* rp, double wavelength, T* result){
  
 		unsigned XY = R[0] * R[1];
@@ -421,6 +469,13 @@ public:
 		}
 		return true;
 	}
+
+	/// 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
+	/// @param bandwavelength is the label value for the desired baseline-corrected band
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size.
 	bool height(double lb, double rb, double bandwavelength, T* result){
  
 		T* lp;
@@ -441,7 +496,14 @@ public:
 	}
  
  
-	//calculate the area between two bound point(including baseline correction)
+
+	/// 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
+	/// @param lab is the label value for the left bound (start of the integration)
+	/// @param rab is the label value for the right bound (end of the integration)
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool area(double lb, double rb, double lab, double rab, T* result){
  
 		T* lp;	//left band pointer
@@ -519,7 +581,15 @@ public:
 		return true;
 	}
  
-	//peak height ratio
+	/// 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)
+	/// @param pos1 is the label value for the first peak (numerator) position
+	/// @param lb2 is the label value for the left baseline point for the second peak (denominator)
+	/// @param rb2 is the label value for the right baseline point for the second peak (denominator)
+	/// @param pos2 is the label value for the second peak (denominator) position
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool ph_to_ph(double lb1, double rb1, double pos1, double lb2, double rb2, double pos2, T * result){
  
 		T* p1 = (T*)malloc(R[0] * R[1] * sizeof(T));	
@@ -541,7 +611,15 @@ public:
 		return true;	
 	}
  
-	//peak are to peak height ratio
+	/// 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)
+	/// @param pos1 is the label value for the first peak (numerator) position
+	/// @param lb2 is the label value for the left baseline point for the second peak (denominator)
+	/// @param rb2 is the label value for the right baseline point for the second peak (denominator)
+	/// @param pos2 is the label value for the second peak (denominator) position
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool pa_to_ph(double lb1, double rb1, double lab1, double rab1,
 					double lb2, double rb2, double pos, T* result){
  
@@ -564,7 +642,17 @@ public:
 		return true;	
 	}		
  
-	//peak area to peak area ratio
+	/// 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)
+	/// @param lab1 is the label value for the left bound (start of the integration) of the first peak (numerator)
+	/// @param rab1 is the label value for the right bound (end of the integration) of the first peak (numerator)
+	/// @param lb2 is the label value for the left baseline point for the second peak (denominator)
+	/// @param rb2 is the label value for the right baseline point for the second peak (denominator)
+	/// @param lab2 is the label value for the left bound (start of the integration) of the second peak (denominator)
+	/// @param rab2 is the label value for the right bound (end of the integration) of the second peak (denominator)	
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool pa_to_pa(double lb1, double rb1, double lab1, double rab1,
 					double lb2, double rb2, double lab2, double rab2, T* result){
  
@@ -587,7 +675,13 @@ public:
 		return true;	
 	}		
  
-	//x * f(x)
+	/// 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
+	/// @param lab is the label for the start of the definite integral
+	/// @param rab is the label for the end of the definite integral
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool x_area(double lb, double rb, double lab, double rab, T* result){
 		T* lp;	//left band pointer
 		T* rp;	//right band pointer
@@ -662,7 +756,13 @@ public:
 		return true;
 	}
  
-	//centroid point
+	/// 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
+	/// @param lab is the label for the start of the peak
+	/// @param rab is the label for the end of the peak
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool cpoint(double lb, double rb, double lab, double rab, T* result){
 		T* p1 = (T*)malloc(R[0] * R[1] * sizeof(T));	
 		T* p2 = (T*)malloc(R[0] * R[1] * sizeof(T));	
@@ -683,7 +783,13 @@ public:
 		return true;	
 	}
  
-	//create mask file
+	/// 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.
+	/// @param mask_band is the band used to specify the mask
+	/// @param threshold is the threshold used to determine if the mask value is true or false
+	/// @param p is a pointer to a pre-allocated array at least X * Y in size
 	bool build_mask(double mask_band, double threshold, unsigned char* p){
  
 		T* temp = (T*)malloc(R[0] * R[1] * sizeof(T));		//allocate memory for the certain band
@@ -700,7 +806,10 @@ public:
 		return true;
 	}
  
-	//apply mask
+	/// 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.
 	bool apply_mask(std::string outfile, unsigned char* p){
  
 		std::ofstream target(outfile.c_str(), std::ios::binary);
@@ -730,7 +839,9 @@ public:
 		return true;
 	}
  
-	//calculate the average band value
+	/// 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){
 		unsigned long long XZ = R[0] * R[2];
 		T* temp = (T*)malloc(sizeof(T) * XZ);
@@ -757,7 +868,10 @@ 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 XZ = R[0] * R[2];
 		unsigned long long XY = R[0] * R[1];
@@ -787,7 +901,11 @@ public:
 		return true;
 	}
  
-	//calculate correlation coefficient 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];
@@ -829,7 +947,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
@@ -856,7 +980,7 @@ public:
 	}
  
  
-	//close the file
+	/// Close the file.
 	bool close(){
 		file.close();
 		return true;
@@ -9,6 +9,14 @@
  
 namespace stim{
  
+/**
+	The BIP class represents a 3-dimensional binary file stored using band interleaved by pixel (BIP) image encoding. The binary file is stored
+	such that Z-X "frames" are stored sequentially to form an image stack along the y-axis. When accessing the data sequentially on disk,
+	the dimensions read, from fastest to slowest, are Z, X, Y.
+
+	This class is optimized for data streaming, and therefore supports extremely large (terabyte-scale) files. Data is loaded from disk
+	on request. Functions used to access data are written to support efficient reading.
+*/
 template <typename T>
  
 class bip: public binary<T> {
@@ -25,7 +33,14 @@ public:
 	using binary<T>::file;
 	using binary<T>::R;
  
-	//open a file, given the file and its header's names
+	/// 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
+	/// @param Y is the number of samples (lines) along dimension 2
+	/// @param B is the number of samples (bands) along dimension 3
+	/// @param header_offset is the number of bytes (if any) in the binary header
+	/// @param wavelengths is an optional STL vector of size B specifying a numerical label for each band
 	bool open(std::string filename, unsigned int X, unsigned int Y, unsigned int B, unsigned int header_offset, std::vector<double> wavelengths){
  
 		//copy the wavelengths to the BSQ file structure
@@ -37,7 +52,10 @@ public:
  
 	}
  
-	//save one band of the file into the memory, and return the pointer
+	/// 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.
 	bool band_index( T * p, unsigned int page){
  
 		if (page >= R[2]){										//make sure the bank number is right
@@ -56,6 +74,10 @@ public:
 		return true;
 	}
  
+	/// 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.
 	bool band( T * p, double wavelength){
  
 		//if there are no wavelengths in the BSQ file
@@ -247,7 +269,11 @@ public:
 		return true;
 	}
  
-	//save one pixel of the BIP file into the memory, and return the pointer
+	/// 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.
+	/// @param y is the y-coordinate (dimension 2) of the spectrum.
 	bool spectrum(T * p, unsigned x, unsigned y){
  
 		if ( x >= R[0] || y >= R[1]){							//make sure the sample and line number is right
@@ -262,7 +288,10 @@ public:
 		return true;	
 	}
  
-	//save one pixel into 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.
 	bool pixel(T * p, unsigned n){
  
 		unsigned bandnum = R[0] * R[1];		//calculate numbers in one band
@@ -291,7 +320,10 @@ public:
  
 	}
  
-	//(BIP) baseline correction
+	/// 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.	
 	bool baseline(std::string outname, std::vector<double> wls){
  
 		unsigned N = wls.size();			//get the number of baseline points
@@ -400,7 +432,11 @@ public:
  
 	}
  
-	// normalize the BIP 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.
+	///	@param t is a threshold specified such that a spectrum with a value at w less than t is set to zero. Setting this threshold allows the user to limit division by extremely small numbers.
 	bool normalize(std::string outname, double w, double t = 0.0)
 	{
 		unsigned int B = R[2];		//calculate the number of bands
@@ -447,7 +483,9 @@ public:
 		return true;
 	}
  
-	//convert BIP file to BSQ file and save it
+	/// Convert the current BIP file to a BSQ file with the specified file name.
+
+	/// @param outname is the name of the output BSQ file to be saved to disk.
 	bool bsq(std::string outname)
 	{	
 		std::string temp = outname + "_temp";
@@ -468,7 +506,9 @@ public:
 		return true;
 	}
  
-	//convert bip file to bil file and save it
+	/// Convert the current BIP 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)
 	{
 		unsigned int S = R[0] * R[2] * sizeof(T);		//calculate the number of bytes in a ZX slice
@@ -500,7 +540,14 @@ public:
 		return true;
 	}
  
-	//providing the left and the right bound data, return baseline-corrected band height
+	/// 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
+	/// @param lp is a pointer to an array holding the band image for the left baseline point
+	/// @param rp is a pointer to an array holding the band image for the right baseline point
+	/// @param wavelength is the label value for the requested baseline-corrected band
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size.
 	bool baseline_band(double lb, double rb, T* lp, T* rp, double wavelength, T* result){
  
 		unsigned XY = R[0] * R[1];
@@ -514,6 +561,12 @@ public:
 		return true;
 	}
  
+	/// 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
+	/// @param bandwavelength is the label value for the desired baseline-corrected band
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size.
 	bool height(double lb, double rb, double bandwavelength, T* result){
  
 		T* lp;
@@ -534,7 +587,13 @@ public:
 	}
  
  
-	//calculate the area between two bound point(including baseline correction)
+	/// 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
+	/// @param lab is the label value for the left bound (start of the integration)
+	/// @param rab is the label value for the right bound (end of the integration)
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool area(double lb, double rb, double lab, double rab, T* result){
  
 		T* lp;	//left band pointer
@@ -612,7 +671,15 @@ public:
 		return true;
 	}
  
-	//peak height ratio
+	/// 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)
+	/// @param pos1 is the label value for the first peak (numerator) position
+	/// @param lb2 is the label value for the left baseline point for the second peak (denominator)
+	/// @param rb2 is the label value for the right baseline point for the second peak (denominator)
+	/// @param pos2 is the label value for the second peak (denominator) position
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool ph_to_ph(double lb1, double rb1, double pos1, double lb2, double rb2, double pos2, T * result){
  
 		T* p1 = (T*)malloc(R[0] * R[1] * sizeof(T));	
@@ -634,7 +701,15 @@ public:
 		return true;	
 	}
  
-	//peak are to peak height ratio
+	/// 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)
+	/// @param pos1 is the label value for the first peak (numerator) position
+	/// @param lb2 is the label value for the left baseline point for the second peak (denominator)
+	/// @param rb2 is the label value for the right baseline point for the second peak (denominator)
+	/// @param pos2 is the label value for the second peak (denominator) position
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool pa_to_ph(double lb1, double rb1, double lab1, double rab1,
 					double lb2, double rb2, double pos, T* result){
  
@@ -657,7 +732,17 @@ public:
 		return true;	
 	}		
  
-	//peak area to peak area ratio
+	/// 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)
+	/// @param lab1 is the label value for the left bound (start of the integration) of the first peak (numerator)
+	/// @param rab1 is the label value for the right bound (end of the integration) of the first peak (numerator)
+	/// @param lb2 is the label value for the left baseline point for the second peak (denominator)
+	/// @param rb2 is the label value for the right baseline point for the second peak (denominator)
+	/// @param lab2 is the label value for the left bound (start of the integration) of the second peak (denominator)
+	/// @param rab2 is the label value for the right bound (end of the integration) of the second peak (denominator)	
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool pa_to_pa(double lb1, double rb1, double lab1, double rab1,
 					double lb2, double rb2, double lab2, double rab2, T* result){
  
@@ -680,7 +765,13 @@ public:
 		return true;	
 	}		
  
-	//x * f(x)
+	/// 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
+	/// @param lab is the label for the start of the definite integral
+	/// @param rab is the label for the end of the definite integral
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool x_area(double lb, double rb, double lab, double rab, T* result){
 		T* lp;	//left band pointer
 		T* rp;	//right band pointer
@@ -755,7 +846,13 @@ public:
 		return true;
 	}
  
-	//centroid point
+	/// 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
+	/// @param lab is the label for the start of the peak
+	/// @param rab is the label for the end of the peak
+	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
 	bool cpoint(double lb, double rb, double lab, double rab, T* result){
 		T* p1 = (T*)malloc(R[0] * R[1] * sizeof(T));	
 		T* p2 = (T*)malloc(R[0] * R[1] * sizeof(T));	
@@ -776,7 +873,13 @@ public:
 		return true;	
 	}
  
-	//create mask file
+	/// 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.
+	/// @param mask_band is the band used to specify the mask
+	/// @param threshold is the threshold used to determine if the mask value is true or false
+	/// @param p is a pointer to a pre-allocated array at least X * Y in size
 	bool build_mask(double mask_band, double threshold, unsigned char* p){
  
 		T* temp = (T*)malloc(R[0] * R[1] * sizeof(T));		//allocate memory for the certain band
@@ -794,7 +897,10 @@ public:
  
 	}
  
-	//apply mask
+	/// 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.
 	bool apply_mask(std::string outfile, unsigned char* p){
  
 		std::ofstream target(outfile.c_str(), std::ios::binary);
@@ -824,7 +930,9 @@ public:
 		return true;
 	}
  
-	//calculate the average band of the file
+	/// 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){
 		unsigned long long XY = R[0] * R[1];
 		//get every pixel and calculate average value
@@ -843,7 +951,10 @@ 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];
 		T* temp = (T*)malloc(sizeof(T) * R[2]);
@@ -870,7 +981,12 @@ public:
 		free(temp);
 		return true;
 	}
-	//calculate correlation coefficient 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];
@@ -912,7 +1028,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
@@ -937,7 +1059,7 @@ public:
 	}
  
  
-	//close the file
+	/// Close the file.
 	bool close(){
 		file.close();
 		return true;
@@ -66,9 +66,9 @@ public:
 			std::cout<<"ERROR: page out of range"<<std::endl;
 			return false;
 		}
-
+		//move the file pointer to the start of the page on disk
 		file.seekg(R[0] * R[1] * page * sizeof(T));
-
+		//read the page from disk
 		file.read((char *)p, sizeof(T) * R[0] * R[1]);
  
 		return true;
@@ -551,8 +551,6 @@ public:
 	/// @param rb2 is the label value for the right baseline point for the second peak (denominator)
 	/// @param pos2 is the label value for the second peak (denominator) position
 	/// @param result is a pointer to a pre-allocated array at least X * Y * sizeof(T) in size
-
-
 	bool pa_to_ph(double lb1, double rb1, double lab1, double rab1,
 					double lb2, double rb2, double pos, T* result){
  
 #ifndef STIM_IMAGE_H
 #define STIM_IMAGE_H
-#define cimg_use_jpeg         //necessary for JPG files
+//#define cimg_use_jpeg         //necessary for JPG files
 #include "CImg.h"
  
 #include <iostream>