CiftiLib
A C++ library for CIFTI-2 and CIFTI-1 files
CiftiFile.h
1 #ifndef __CIFTI_FILE_H__
2 #define __CIFTI_FILE_H__
3 
4 /*LICENSE_START*/
5 /*
6  * Copyright (c) 2014, Washington University School of Medicine
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without modification,
10  * are permitted provided that the following conditions are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
28  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 #include "Common/AString.h"
32 #include "Common/CiftiException.h"
33 #include "Common/MultiDimIterator.h"
34 #include "Cifti/CiftiXML.h"
35 #include "Nifti/nifti1.h"
36 
37 #include "boost/shared_ptr.hpp"
38 
39 #include <vector>
40 
42 namespace cifti
43 {
45  class CiftiFile
46  {
47  public:
48 
49  enum ENDIAN
50  {
51  ANY,//so that writeFile() with default endian argument can do nothing after setWritingFile with any endian argument - uses native if there is no rewrite to avoid
52  NATIVE,//as long as there are more than two options anyway, provide a convenience option so people don't need to figure out the machine endianness for a common case
53  LITTLE,
54  BIG
55  };
56 
57  CiftiFile();
58 
60  explicit CiftiFile(const AString &fileName);
61 
63  void openFile(const AString& fileName);
64 
66  void setWritingFile(const AString& fileName, const CiftiVersion& writingVersion = CiftiVersion(), const ENDIAN& endian = NATIVE);
67 
69  void writeFile(const AString& fileName, const CiftiVersion& writingVersion = CiftiVersion(), const ENDIAN& endian = ANY);
70 
72  void close();
73 
75  void convertToInMemory();
76 
77  const CiftiXML& getCiftiXML() const { return m_xml; }
78  bool isInMemory() const;
79 
81  void getRow(float* dataOut, const std::vector<int64_t>& indexSelect, const bool& tolerateShortRead = false) const;
82  const std::vector<int64_t>& getDimensions() const { return m_dims; }
83 
86  {
87  return MultiDimIterator<int64_t>(std::vector<int64_t>(m_dims.begin() + 1, m_dims.end()));
88  }
89 
91  void getColumn(float* dataOut, const int64_t& index) const;
92 
93  void setCiftiXML(const CiftiXML& xml, const bool useOldMetadata = true);
94  void setRow(const float* dataIn, const std::vector<int64_t>& indexSelect);
95 
97  void setColumn(const float* dataIn, const int64_t& index);
98 
100  void getRow(float* dataOut, const int64_t& index, const bool& tolerateShortRead = false) const;
101 
103  void setRow(const float* dataIn, const int64_t& index);
104 
106  void setWritingDataTypeNoScaling(const int16_t& type = NIFTI_TYPE_FLOAT32);
107  void setWritingDataTypeAndScaling(const int16_t& type, const double& minval, const double& maxval);
108 
109  //implementation details from here down
111  {
112  public:
113  virtual void getRow(float* dataOut, const std::vector<int64_t>& indexSelect, const bool& tolerateShortRead) const = 0;
114  virtual void getColumn(float* dataOut, const int64_t& index) const = 0;
115  virtual bool isInMemory() const { return false; }
116  virtual ~ReadImplInterface();
117  };
118  //assume if you can write to it, you can also read from it
120  {
121  public:
122  virtual void setRow(const float* dataIn, const std::vector<int64_t>& indexSelect) = 0;
123  virtual void setColumn(const float* dataIn, const int64_t& index) = 0;
124  virtual void close() {}
125  virtual ~WriteImplInterface();
126  };
127  private:
128  std::vector<int64_t> m_dims;
129  boost::shared_ptr<WriteImplInterface> m_writingImpl;//this will be equal to m_readingImpl when non-null
130  boost::shared_ptr<ReadImplInterface> m_readingImpl;
131  AString m_writingFile;
132  CiftiXML m_xml;
133  CiftiVersion m_onDiskVersion;
134  ENDIAN m_endianPref;
135  bool m_doWriteScaling;
136  int16_t m_writingDataType;
137  double m_minScalingVal, m_maxScalingVal;
138 
139  void verifyWriteImpl();
140  static void copyImplData(const ReadImplInterface* from, WriteImplInterface* to, const std::vector<int64_t>& dims);
141  };
142 
143 }
144 
145 #endif //__CIFTI_FILE_H__
Definition: CiftiFile.h:111
Definition: CiftiFile.h:120
class for reading and writing cifti files
Definition: CiftiFile.h:46
void getColumn(float *dataOut, const int64_t &index) const
for 2D only, will be slow if on disk!
Definition: CiftiFile.cxx:266
void setWritingDataTypeNoScaling(const int16_t &type=NIFTI_TYPE_FLOAT32)
data type and scaling options - should be set before setRow, etc, to avoid rewriting of file
Definition: CiftiFile.cxx:171
void getRow(float *dataOut, const std::vector< int64_t > &indexSelect, const bool &tolerateShortRead=false) const
the tolerateShortRead parameter is useful for on-disk writing when it is easiest to do RMW multiple t...
Definition: CiftiFile.cxx:259
void convertToInMemory()
reads file into memory, closes file
Definition: CiftiFile.cxx:235
void openFile(const AString &fileName)
starts on-disk reading
Definition: CiftiFile.cxx:153
void writeFile(const AString &fileName, const CiftiVersion &writingVersion=CiftiVersion(), const ENDIAN &endian=ANY)
does nothing if filename, version, and effective endianness match file currently open,...
Definition: CiftiFile.cxx:189
void close()
closes the underlying file to flush it, so that exceptions can be thrown
Definition: CiftiFile.cxx:219
void setWritingFile(const AString &fileName, const CiftiVersion &writingVersion=CiftiVersion(), const ENDIAN &endian=NATIVE)
starts on-disk writing
Definition: CiftiFile.cxx:163
void setColumn(const float *dataIn, const int64_t &index)
for 2D only, will be slow if on disk!
Definition: CiftiFile.cxx:301
MultiDimIterator< int64_t > getIteratorOverRows() const
convenience function for iterating over arbitrary numbers of dimensions
Definition: CiftiFile.h:85
Definition: CiftiVersion.h:38
class for retrieving and setting mapping information of cifti files
Definition: CiftiXML.h:49
Definition: MultiDimIterator.h:39
const int32_t NIFTI_TYPE_FLOAT32
Definition: nifti1.h:552
namespace for all CiftiLib functionality
Definition: CiftiBrainModelsMap.h:42