codebase / stimlib

Commit 33d7d3cf66f23847f92d85a149293c11cfaf49e5

Authored by David Mayerich
1 parent cb455f98

documentation for binary.h

Showing 1 changed file with 31 additions and 11 deletions   Show diff stats
Inline Side-by-side
envi/binary.h
  Show/Hide comments   View file @33d7d3c
... ... @@ -10,7 +10,13 @@
10 10  
11 11 namespace stim{
12 12  
13   -//This class contains a bunch of functions useful for multidimensional binary file access
  13 +/** This class manages the streaming of large multidimensional binary files.
  14 + * Generally these are hyperspectral files with 2 spatial and 1 spectral dimension. However, this class supports
  15 + * other dimensions via the template parameter D.
  16 + *
  17 + * @param T is the data type used to store data to disk (generally float or double)
  18 + * @param D is the dimension of the data (default 3)
  19 + */
14 20 template< typename T, unsigned int D = 3 >
15 21 class binary{
16 22  
... ... @@ -25,15 +31,14 @@ protected:
25 31  
26 32  
27 33  
28   - //basic initialization
  34 + /// Private initialization function used to set default parameters in the data structure.
29 35 void init(){
30 36 memset(R, 0, sizeof(unsigned int) * D); //initialize the resolution to zero
31 37 header = 0; //initialize the header size to zero
32 38 mask = NULL;
33 39 }
34 40  
35   - //returns the file size
36   - // reads the file size from disk and returns it (in bytes)
  41 + /// Private helper function that returns the size of the file on disk using system functions.
37 42 long long int get_file_size(){
38 43 #ifdef _WIN32
39 44 struct _stat64 results;
... ... @@ -47,8 +52,7 @@ protected:
47 52 else return 0;
48 53 }
49 54  
50   - //make sure that the specified file size matches the file size on disk
51   - // returns true/false
  55 + /// 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.
52 56 bool test_file_size(){
53 57 long long int npts = 1; //initialize the number of data points to 1
54 58 for(unsigned int i = 0; i<D; i++) //iterate over each dimension
... ... @@ -60,7 +64,9 @@ protected:
60 64  
61 65 }
62 66  
63   - //open the file specified in "name" for binary reading and writing
  67 + /// Private helper file that opens a specified binary file.
  68 +
  69 + /// @param filename is the name of the binary file to stream
64 70 bool open_file(std::string filename){
65 71 //open the file as binary for reading and writing
66 72 file.open(filename.c_str(), std::ios::in | std::ios::out | std::ios::binary);
... ... @@ -77,7 +83,11 @@ protected:
77 83  
78 84 public:
79 85  
80   - //open a file, given the file name, resolution (as a vector) and header size
  86 + /// Open a binary file for streaming.
  87 +
  88 + /// @param filename is the name of the binary file
  89 + /// @param r is a STIM vector specifying the size of the binary file along each dimension
  90 + /// @param h is the length (in bytes) of any header file (default zero)
81 91 bool open(std::string filename, vec<unsigned int, D> r, unsigned int h = 0){
82 92  
83 93 for(unsigned int i = 0; i < D; i++) //set the dimensions of the binary file object
... ... @@ -90,7 +100,11 @@ public:
90 100 return test_file_size();
91 101 }
92 102  
93   - //crete a new binary file
  103 + /// Creates a new binary file for streaming
  104 +
  105 + /// @param filename is the name of the binary file to be created
  106 + /// @param r is a STIM vector specifying the size of the file along each dimension
  107 + /// @offset specifies how many bytes to offset the file (used to leave room for a header)
94 108 bool create(std::string filename, vec<unsigned int, D> r, unsigned int offset = 0){
95 109  
96 110 std::ofstream target(filename.c_str(), std::ios::binary);
... ... @@ -111,7 +125,10 @@ public:
111 125 return test_file_size();
112 126 }
113 127  
114   - //save one band from the memory to the file
  128 + /// 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].
  129 +
  130 + /// @param p is a pointer to the data to be written
  131 + /// @param page is the page number (index of the highest-numbered dimension)
115 132 bool write_page( T * p, unsigned int page){
116 133  
117 134 if(p == NULL){
... ... @@ -125,7 +142,10 @@ public:
125 142 return true;
126 143 }
127 144  
128   - //save one band of the file into the memory, and return the pointer
  145 + /// Reads a page from disk. A page consists of a sequence of data of size R[0] * R[1] * ... * R[D-1].
  146 +
  147 + /// @param p is a pointer to pre-allocated memory equal to the page size
  148 + /// @param page is the index of the page
129 149 bool read_page( T * p, unsigned int page){
130 150  
131 151 if (page >= R[2]){ //make sure the bank number is right
... ...