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 
36 #include "boost/shared_ptr.hpp"
37 
38 #include <vector>
39 
41 namespace cifti
42 {
44  class CiftiFile
45  {
46  public:
47 
48  enum ENDIAN
49  {
50  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
51  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
52  LITTLE,
53  BIG
54  };
55 
56  CiftiFile() { m_endianPref = NATIVE; }
57 
59  explicit CiftiFile(const AString &fileName);
60 
62  void openFile(const AString& fileName);
63 
65  void setWritingFile(const AString& fileName, const CiftiVersion& writingVersion = CiftiVersion(), const ENDIAN& endian = NATIVE);
66 
68  void writeFile(const AString& fileName, const CiftiVersion& writingVersion = CiftiVersion(), const ENDIAN& endian = ANY);
69 
71  void convertToInMemory();
72 
73  const CiftiXML& getCiftiXML() const { return m_xml; }
74  bool isInMemory() const;
75 
77  void getRow(float* dataOut, const std::vector<int64_t>& indexSelect, const bool& tolerateShortRead = false) const;
78  const std::vector<int64_t>& getDimensions() const { return m_dims; }
79 
82  {
83  return MultiDimIterator<int64_t>(std::vector<int64_t>(m_dims.begin() + 1, m_dims.end()));
84  }
85 
87  void getColumn(float* dataOut, const int64_t& index) const;
88 
89  void setCiftiXML(const CiftiXML& xml, const bool useOldMetadata = true);
90  void setRow(const float* dataIn, const std::vector<int64_t>& indexSelect);
91 
93  void setColumn(const float* dataIn, const int64_t& index);
94 
96  void getRow(float* dataOut, const int64_t& index, const bool& tolerateShortRead = false) const;
97 
99  void setRow(const float* dataIn, const int64_t& index);
100 
101  //implementation details from here down
103  {
104  public:
105  virtual void getRow(float* dataOut, const std::vector<int64_t>& indexSelect, const bool& tolerateShortRead) const = 0;
106  virtual void getColumn(float* dataOut, const int64_t& index) const = 0;
107  virtual bool isInMemory() const { return false; }
108  virtual ~ReadImplInterface();
109  };
110  //assume if you can write to it, you can also read from it
112  {
113  public:
114  virtual void setRow(const float* dataIn, const std::vector<int64_t>& indexSelect) = 0;
115  virtual void setColumn(const float* dataIn, const int64_t& index) = 0;
116  virtual ~WriteImplInterface();
117  };
118  private:
119  std::vector<int64_t> m_dims;
120  boost::shared_ptr<WriteImplInterface> m_writingImpl;//this will be equal to m_readingImpl when non-null
121  boost::shared_ptr<ReadImplInterface> m_readingImpl;
122  AString m_writingFile;
123  CiftiXML m_xml;
124  CiftiVersion m_onDiskVersion;
125  ENDIAN m_endianPref;
126 
127  void verifyWriteImpl();
128  static void copyImplData(const ReadImplInterface* from, WriteImplInterface* to, const std::vector<int64_t>& dims);
129  };
130 
131 }
132 
133 #endif //__CIFTI_FILE_H__
void openFile(const AString &fileName)
starts on-disk reading
Definition: CiftiFile.cxx:144
MultiDimIterator< int64_t > getIteratorOverRows() const
convenience function for iterating over arbitrary numbers of dimensions
Definition: CiftiFile.h:81
namespace for all CiftiLib functionality
Definition: CiftiBrainModelsMap.h:41
Definition: CiftiFile.h:111
class for retrieving and setting mapping information of cifti files
Definition: CiftiXML.h:48
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, otherwise writes complete file
Definition: CiftiFile.cxx:164
void convertToInMemory()
reads file into memory, closes file
Definition: CiftiFile.cxx:193
void setWritingFile(const AString &fileName, const CiftiVersion &writingVersion=CiftiVersion(), const ENDIAN &endian=NATIVE)
starts on-disk writing
Definition: CiftiFile.cxx:156
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...
class for reading and writing cifti files
Definition: CiftiFile.h:44
Definition: CiftiVersion.h:37
void getColumn(float *dataOut, const int64_t &index) const
for 2D only, will be slow if on disk!
Definition: CiftiFile.cxx:224
Definition: CiftiFile.h:102
void setColumn(const float *dataIn, const int64_t &index)
for 2D only, will be slow if on disk!
Definition: CiftiFile.cxx:258
Definition: MultiDimIterator.h:38