Issue2798 - BOV Reader

include/vapor/BOVCollection.h

@@ -24,11 +24,12 @@ class BOVCollection : public Wasp::MyBase {
     DC::XType                  GetDataFormat() const;
     std::array<double, 3>      GetBrickOrigin() const;
     std::array<double, 3>      GetBrickSize() const;
-    std::string                GetDataEndian() const;
 
     template<class T> int ReadRegion(std::string varname, size_t ts, const std::vector<size_t> &min, const std::vector<size_t> &max, T region);
 
 private:
+    std::string _currentFilePath;
+
     float                    _time;
     std::vector<float>       _times;
     std::string              _dataFile;
@@ -37,21 +38,22 @@ class BOVCollection : public Wasp::MyBase {
     DC::XType                _dataFormat;
     std::string              _variable;
     std::vector<std::string> _variables;
-    std::string              _dataEndian;
-    std::string              _centering;
     std::array<double, 3>    _brickOrigin;
     std::array<double, 3>    _brickSize;
     size_t                   _byteOffset;
-    bool                     _divideBrick;
-    std::array<size_t, 3>    _dataBricklets;
-    int                      _dataComponents;
+
+    // These values are currently parsed and assigned, but are unimplemented (not used)
+    bool                  _divideBrick;
+    std::string           _dataEndian;
+    std::string           _centering;
+    int                   _dataComponents;
+    std::array<size_t, 3> _dataBricklets;
 
     // Placeholder variables to store values read from BOV descriptor files.
     // These values must be consistent among BOV files, and are validated before
     // assigning to "actual" values such as _gridSize, declaired above.
     std::array<size_t, 3> _tmpGridSize;
     DC::XType             _tmpDataFormat;
-    std::string           _tmpDataEndian;
     std::array<double, 3> _tmpBrickOrigin;
     std::array<double, 3> _tmpBrickSize;
     size_t                _tmpByteOffset;
@@ -60,7 +62,6 @@ class BOVCollection : public Wasp::MyBase {
     bool _formatAssigned;
     bool _brickOriginAssigned;
     bool _brickSizeAssigned;
-    bool _dataEndianAssigned;
     bool _byteOffsetAssigned;
 
     // _dataFileMap allows us to access binary data files with a
@@ -79,26 +80,30 @@ class BOVCollection : public Wasp::MyBase {
 
     void _findTokenValue(std::string &line) const;
 
-    int  _sizeOfFormat(DC::XType) const;
-    void _swapBytes(void *vptr, size_t size, size_t n) const;
+    int _sizeOfFormat(DC::XType) const;
 
-    int _invalidDimensionError(std::string token) const;
-    int _invalidFormatError(std::string token) const;
-    int _failureToReadError(std::string token) const;
-    int _inconsistentValueError(std::string token) const;
-    int _invalidValueError(std::string token) const;
-    int _missingValueError(std::string token) const;
+    int _invalidVarNameError() const;
+    int _invalidFileSizeError(size_t numElements) const;
+    int _invalidFileError() const;
+    int _invalidDimensionError(const std::string &token) const;
+    int _invalidFormatError(const std::string &token) const;
+    int _failureToReadError(const std::string &token) const;
+    int _inconsistentValueError(const std::string &token) const;
+    int _invalidValueError(const std::string &token) const;
+    int _missingValueError(const std::string &token) const;
 
     static const std::string TIME_TOKEN;
     static const std::string DATA_FILE_TOKEN;
     static const std::string GRID_SIZE_TOKEN;
     static const std::string FORMAT_TOKEN;
     static const std::string VARIABLE_TOKEN;
-    static const std::string ENDIAN_TOKEN;
-    static const std::string CENTERING_TOKEN;
     static const std::string ORIGIN_TOKEN;
     static const std::string BRICK_SIZE_TOKEN;
     static const std::string OFFSET_TOKEN;
+
+    // These tokens are currently parsed but are not used
+    static const std::string ENDIAN_TOKEN;
+    static const std::string CENTERING_TOKEN;
     static const std::string DIVIDE_BRICK_TOKEN;
     static const std::string DATA_BRICKLETS_TOKEN;
     static const std::string DATA_COMPONENTS_TOKEN;
@@ -107,15 +112,17 @@ class BOVCollection : public Wasp::MyBase {
     static const std::string           _defaultFile;
     static const DC::XType             _defaultFormat;
     static const std::string           _defaultVar;
-    static const std::string           _defaultEndian;
-    static const std::string           _defaultCentering;
     static const size_t                _defaultByteOffset;
-    static const size_t                _defaultComponents;
-    static const bool                  _defaultDivBrick;
     static const std::array<double, 3> _defaultOrigin;
     static const std::array<double, 3> _defaultBrickSize;
     static const std::array<size_t, 3> _defaultGridSize;
+
+    // These defaults are currently unimplemented in the BOV reader logic
+    static const std::string           _defaultEndian;
+    static const std::string           _defaultCentering;
+    static const bool                  _defaultDivBrick;
     static const std::array<size_t, 3> _defaultBricklets;
+    static const size_t                _defaultComponents;
 
     static const std::string _xDim;
     static const std::string _yDim;

include/vapor/DCBOV.h

@@ -16,6 +16,33 @@ namespace VAPoR {
 
 class BOVCollection;
 
+// Example BOV header file, bovA1.bov
+//
+// # TIME is a floating point value specifying the timestep being read in DATA_FILE
+// TIME: 1.1
+//
+// # DATA_FILE points to a binary data file.  It can be a full file path, or a path relative to the BOV header.
+// DATA_FILE: bovA1.bin
+//
+// # The data size corresponds to NX,NY,NZ in the above example code.  It must contain three values
+// DATA_SIZE: 10 10 10
+//
+// # Allowable values for DATA_FORMAT are: INT,FLOAT,DOUBLE
+// DATA_FORMAT: FLOAT
+//
+// # VARIABLE is a string that specifies the variable being read in DATA_FILE.  Must be alphanumeric (abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_-)
+// VARIABLE: myVariable
+//
+// # BRICK_ORIGIN lets you specify a new coordinate system origin for # the mesh that will be created to suit your data.  It must contain three values.
+// BRICK_ORIGIN: 0. 0. 0.
+//
+// # BRICK_SIZE lets you specify the size of the brick on X, Y, and Z.  It must contain three values.
+// BRICK_SIZE: 10. 20. 5.
+//
+// # BYTE_OFFSET is optional and lets you specify some number of
+// # bytes to skip at the front of the file. This can be useful for # skipping the 4-byte header that Fortran tends to write to files. # If your file does not have a header then DO NOT USE
+// BYTE_OFFSET. BYTE_OFFSET: 4
+
 //!
 //! \class DCBOV
 //! \ingroup Public_VDCBOV
@@ -29,23 +56,27 @@ class BOVCollection;
 //! - DATA_FORMAT
 //!
 //! The following BOV tags are optional:
-//! - BRICK_ORIGIN
-//! - BRICK_SIZE
-//! - DATA_ENDIAN
-//! - TIME
-//! - VARIABLE
+//! - BRICK_ORIGIN (default: 0., 0., 0.)
+//! - BRICK_SIZE   (default: 1., 1., 1.)
+//! - TIME         (default: 0.)
+//! - VARIABLE     (default: "brickVar")
+//! - BYTE_OFFSET  (default: 0)
 //!
-//! The following BOV tags are currently unsupported:
+//! The following BOV tags are currently unsupported.  They can be included in a BOV header,
+//! but they will be unused.
+//! - DATA_ENDIAN
 //! - CENTERING
-//! - BYTE_OFFSET
 //! - DIVIDE_BRICK
 //! - DATA_BRICKLETS
 //! - DATA_COMPONENTS
 //!
+//! If duplicate key/value pairs exist in a BOV header, the value closest to the bottom of the file will be used.
+//! If duplicate values exist for whatever reason, all entries must be valid (except for DATA_FILE, which gets validated after parsing)
 //! Scientific notation is supported for floating point values like BRICK_ORIGIN and BRICK_SIZE.
 //! Scientific notation is not supported for integer values like DATA_SIZE.
 //! Wild card characters are not currently supported in the DATA_FILE token.
 //! Each .bov file can only refer to a single data file.
+//! VARIABLE must be alphanumeric (abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890_-)
 //!
 //! \author Scott Pearse
 //! \date    May, 2021