documentation for binary.h

David Mayerich
1 parent cb455f98
Showing 1 changed file with 31 additions and 11 deletions Show diff stats
envi/binary.h
@@ -10,7 +10,13 @@
 namespace stim{
-//This class contains a bunch of functions useful for multidimensional binary file access
+/** This class manages the streaming of large multidimensional binary files.
+ *  Generally these are hyperspectral files with 2 spatial and 1 spectral dimension. However, this class supports
+ *  other dimensions via the template parameter D.
+ *
+ *  @param T is the data type used to store data to disk (generally float or double)
+ *  @param D is the dimension of the data (default 3)
+ */
 template< typename T, unsigned int D = 3 >
 class binary{
@@ -25,15 +31,14 @@ protected:
-	//basic initialization
+	/// Private initialization function used to set default parameters in the data structure.
 	void init(){
 		memset(R, 0, sizeof(unsigned int) * D);		//initialize the resolution to zero
 		header = 0;									//initialize the header size to zero
 		mask = NULL;
 	}
-	//returns the file size
-	//	reads the file size from disk and returns it (in bytes)
+	/// Private helper function that returns the size of the file on disk using system functions.
 	long long int get_file_size(){
 #ifdef _WIN32
 		struct _stat64 results;
@@ -47,8 +52,7 @@ protected:
 		else return 0;
 	}
-	//make sure that the specified file size matches the file size on disk
-	//	returns true/false
+	/// Private helper function that tests to make sure that the calculated data size specified by the structure is the same as the data size on disk.
 	bool test_file_size(){
 		long long int npts = 1;				//initialize the number of data points to 1
 		for(unsigned int i = 0; i<D; i++)	//iterate over each dimension
@@ -60,7 +64,9 @@ protected:
 	}
-	//open the file specified in "name" for binary reading and writing
+	/// Private helper file that opens a specified binary file.
+
+	/// @param filename is the name of the binary file to stream
 	bool open_file(std::string filename){
 		//open the file as binary for reading and writing
 		file.open(filename.c_str(), std::ios::in | std::ios::out | std::ios::binary);
@@ -77,7 +83,11 @@ protected:
 public:
-	//open a file, given the file name, resolution (as a vector) and header size
+	/// Open a binary file for streaming.
+
+	/// @param filename is the name of the binary file
+	/// @param r is a STIM vector specifying the size of the binary file along each dimension
+	/// @param h is the length (in bytes) of any header file (default zero)
 	bool open(std::string filename, vec<unsigned int, D> r, unsigned int h = 0){
 		for(unsigned int i = 0; i < D; i++)		//set the dimensions of the binary file object
@@ -90,7 +100,11 @@ public:
 		return test_file_size();
 	}
-	//crete a new binary file
+	/// Creates a new binary file for streaming
+
+	/// @param filename is the name of the binary file to be created
+	/// @param r is a STIM vector specifying the size of the file along each dimension
+	/// @offset specifies how many bytes to offset the file (used to leave room for a header)
 	bool create(std::string filename, vec<unsigned int, D> r, unsigned int offset = 0){
 		std::ofstream target(filename.c_str(), std::ios::binary);
@@ -111,7 +125,10 @@ public:
 		return test_file_size();
 	}
-	//save one band from the memory to the file
+	/// Writes a single page of data to disk. A page consists of a sequence of data of size R[0] * R[1] * ... * R[D-1].
+
+	/// @param p is a pointer to the data to be written
+	/// @param page is the page number (index of the highest-numbered dimension)
 	bool write_page( T * p, unsigned int page){
 		if(p == NULL){
@@ -125,7 +142,10 @@ public:
 		return true;
 	}
-	//save one band of the file into the memory, and return the pointer
+	/// Reads a page from disk. A page consists of a sequence of data of size R[0] * R[1] * ... * R[D-1].
+
+	/// @param p is a pointer to pre-allocated memory equal to the page size
+	/// @param page is the index of the page
 	bool read_page( T * p, unsigned int page){
 		if (page >= R[2]){										//make sure the bank number is right