1 /*========================================================================= 2 * 3 * Copyright Insight Software Consortium 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0.txt 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 *=========================================================================*/ 18 #ifndef itkImage_h 19 #define itkImage_h 20 21 #include "itkImageRegion.h" 22 #include "itkImportImageContainer.h" 23 #include "itkDefaultPixelAccessor.h" 24 #include "itkDefaultPixelAccessorFunctor.h" 25 #include "itkPoint.h" 26 #include "itkFixedArray.h" 27 #include "itkWeakPointer.h" 28 #include "itkNeighborhoodAccessorFunctor.h" 29 30 namespace itk 31 { 32 /** \class Image 33 * \brief Templated n-dimensional image class. 34 * 35 * Images are templated over a pixel type (modeling the dependent 36 * variables), and a dimension (number of independent variables). The 37 * container for the pixel data is the ImportImageContainer. 38 * 39 * Within the pixel container, images are modelled as arrays, defined by a 40 * start index and a size. 41 * 42 * The superclass of Image, ImageBase, defines the geometry of the 43 * image in terms of where the image sits in physical space, how the 44 * image is oriented in physical space, the size of a pixel, and the 45 * extent of the image itself. ImageBase provides the methods to 46 * convert between the index and physical space coordinate frames. 47 * 48 * Pixels can be accessed direcly using the SetPixel() and GetPixel() 49 * methods or can be accessed via iterators that define the region of 50 * the image they traverse. 51 * 52 * The pixel type may be one of the native types; a Insight-defined 53 * class type such as Vector; or a user-defined type. Note that 54 * depending on the type of pixel that you use, the process objects 55 * (i.e., those filters processing data objects) may not operate on 56 * the image and/or pixel type. This becomes apparent at compile-time 57 * because operator overloading (for the pixel type) is not supported. 58 * 59 * The data in an image is arranged in a 1D array as [][][][slice][row][col] 60 * with the column index varying most rapidly. The Index type reverses 61 * the order so that with Index[0] = col, Index[1] = row, Index[2] = slice, 62 * ... 63 * 64 * \sa ImageBase 65 * \sa ImageContainerInterface 66 * 67 * \ingroup ImageObjects 68 * \ingroup ITKCommon 69 * 70 * \wiki 71 * \wikiexample{SimpleOperations/SetPixels,Set specified pixels to specified values} 72 * \endwiki 73 */ 74 template< typename TPixel, unsigned int VImageDimension = 2 > 75 class ITK_TEMPLATE_EXPORT Image:public ImageBase< VImageDimension > 76 { 77 public: 78 ITK_DISALLOW_COPY_AND_ASSIGN(Image); 79 80 /** Standard class type aliases */ 81 using Self = Image; 82 using Superclass = ImageBase< VImageDimension >; 83 using Pointer = SmartPointer< Self >; 84 using ConstPointer = SmartPointer< const Self >; 85 using ConstWeakPointer = WeakPointer< const Self >; 86 87 /** Method for creation through the object factory. */ 88 itkNewMacro(Self); 89 90 /** Run-time type information (and related methods). */ 91 itkTypeMacro(Image, ImageBase); 92 93 /** Pixel type alias support. Used to declare pixel type in filters 94 * or other operations. */ 95 using PixelType = TPixel; 96 97 /** Typedef alias for PixelType */ 98 using ValueType = TPixel; 99 100 /** Internal Pixel representation. Used to maintain a uniform API 101 * with Image Adaptors and allow to keep a particular internal 102 * representation of data while showing a different external 103 * representation. */ 104 using InternalPixelType = TPixel; 105 106 using IOPixelType = PixelType; 107 108 /** Accessor type that convert data between internal and external 109 * representations. */ 110 using AccessorType = DefaultPixelAccessor< PixelType >; 111 using AccessorFunctorType = DefaultPixelAccessorFunctor< Self >; 112 113 /** Typedef for the functor used to access a neighborhood of pixel 114 * pointers. */ 115 using NeighborhoodAccessorFunctorType = NeighborhoodAccessorFunctor< Self >; 116 117 /** Type of image dimension */ 118 using ImageDimensionType = typename Superclass::ImageDimensionType; 119 120 /** Index type alias support. An index is used to access pixel values. */ 121 using IndexType = typename Superclass::IndexType; 122 using IndexValueType = typename Superclass::IndexValueType; 123 124 /** Offset type alias support. An offset is used to access pixel values. */ 125 using OffsetType = typename Superclass::OffsetType; 126 127 /** Size type alias support. A size is used to define region bounds. */ 128 using SizeType = typename Superclass::SizeType; 129 using SizeValueType = typename Superclass::SizeValueType; 130 131 /** Container used to store pixels in the image. */ 132 using PixelContainer = ImportImageContainer< SizeValueType, PixelType >; 133 134 /** Direction type alias support. A matrix of direction cosines. */ 135 using DirectionType = typename Superclass::DirectionType; 136 137 /** Region type alias support. A region is used to specify a subset of an image. 138 */ 139 using RegionType = typename Superclass::RegionType; 140 141 /** Spacing type alias support. Spacing holds the size of a pixel. The 142 * spacing is the geometric distance between image samples. */ 143 using SpacingType = typename Superclass::SpacingType; 144 using SpacingValueType = typename Superclass::SpacingValueType; 145 146 /** Origin type alias support. The origin is the geometric coordinates 147 * of the index (0,0). */ 148 using PointType = typename Superclass::PointType; 149 150 /** A pointer to the pixel container. */ 151 using PixelContainerPointer = typename PixelContainer::Pointer; 152 using PixelContainerConstPointer = typename PixelContainer::ConstPointer; 153 154 /** Offset type alias (relative position between indices) */ 155 using OffsetValueType = typename Superclass::OffsetValueType; 156 157 /** 158 * example usage: 159 * using OutputImageType = typename ImageType::template Rebind< float >::Type; 160 * 161 * \deprecated Use RebindImageType instead 162 */ 163 template <typename UPixelType, unsigned int NUImageDimension = VImageDimension> 164 struct Rebind 165 { 166 using Type = itk::Image<UPixelType, NUImageDimension>; 167 }; 168 169 170 template <typename UPixelType, unsigned int NUImageDimension = VImageDimension> 171 using RebindImageType = itk::Image<UPixelType, NUImageDimension>; 172 173 174 /** Allocate the image memory. The size of the image must 175 * already be set, e.g. by calling SetRegions(). */ 176 void Allocate(bool initializePixels = false) override; 177 178 /** Restore the data object to its initial state. This means releasing 179 * memory. */ 180 void Initialize() override; 181 182 /** Fill the image buffer with a value. Be sure to call Allocate() 183 * first. */ 184 void FillBuffer(const TPixel & value); 185 186 /** \brief Set a pixel value. 187 * 188 * Allocate() needs to have been called first -- for efficiency, 189 * this function does not check that the image has actually been 190 * allocated yet. */ SetPixel(const IndexType & index,const TPixel & value)191 void SetPixel(const IndexType & index, const TPixel & value) 192 { 193 OffsetValueType offset = this->FastComputeOffset(index); 194 ( *m_Buffer )[offset] = value; 195 } 196 197 /** \brief Get a pixel (read only version). 198 * 199 * For efficiency, this function does not check that the 200 * image has actually been allocated yet. */ GetPixel(const IndexType & index)201 const TPixel & GetPixel(const IndexType & index) const 202 { 203 OffsetValueType offset = this->FastComputeOffset(index); 204 return ( ( *m_Buffer )[offset] ); 205 } 206 207 /** \brief Get a reference to a pixel (e.g. for editing). 208 * 209 * For efficiency, this function does not check that the 210 * image has actually been allocated yet. */ GetPixel(const IndexType & index)211 TPixel & GetPixel(const IndexType & index) 212 { 213 OffsetValueType offset = this->FastComputeOffset(index); 214 return ( ( *m_Buffer )[offset] ); 215 } 216 217 /** \brief Access a pixel. This version can be an lvalue. 218 * 219 * For efficiency, this function does not check that the 220 * image has actually been allocated yet. */ 221 TPixel & operator[](const IndexType & index) 222 { return this->GetPixel(index); } 223 224 /** \brief Access a pixel. This version can only be an rvalue. 225 * 226 * For efficiency, this function does not check that the 227 * image has actually been allocated yet. */ 228 const TPixel & operator[](const IndexType & index) const 229 { return this->GetPixel(index); } 230 231 /** Return a pointer to the beginning of the buffer. This is used by 232 * the image iterator class. */ GetBufferPointer()233 virtual TPixel * GetBufferPointer() 234 { return m_Buffer ? m_Buffer->GetBufferPointer() : nullptr; } GetBufferPointer()235 virtual const TPixel * GetBufferPointer() const 236 { return m_Buffer ? m_Buffer->GetBufferPointer() : nullptr; } 237 238 /** Return a pointer to the container. */ GetPixelContainer()239 PixelContainer * GetPixelContainer() 240 { return m_Buffer.GetPointer(); } 241 GetPixelContainer()242 const PixelContainer * GetPixelContainer() const 243 { return m_Buffer.GetPointer(); } 244 245 /** Set the container to use. Note that this does not cause the 246 * DataObject to be modified. */ 247 void SetPixelContainer(PixelContainer *container); 248 249 /** Graft the data and information from one image to another. This 250 * is a convenience method to setup a second image with all the meta 251 * information of another image and use the same pixel 252 * container. Note that this method is different than just using two 253 * SmartPointers to the same image since separate DataObjects are 254 * still maintained. This method is similar to 255 * ImageSource::GraftOutput(). The implementation in ImageBase 256 * simply calls CopyInformation() and copies the region ivars. 257 * The implementation here refers to the superclass' implementation 258 * and then copies over the pixel container. */ 259 virtual void Graft(const Self *data); 260 261 /** Return the Pixel Accessor object */ GetPixelAccessor()262 AccessorType GetPixelAccessor() 263 { return AccessorType(); } 264 265 /** Return the Pixel Accesor object */ GetPixelAccessor()266 const AccessorType GetPixelAccessor() const 267 { return AccessorType(); } 268 269 /** Return the NeighborhoodAccessor functor */ GetNeighborhoodAccessor()270 NeighborhoodAccessorFunctorType GetNeighborhoodAccessor() 271 { return NeighborhoodAccessorFunctorType(); } 272 273 /** Return the NeighborhoodAccessor functor */ GetNeighborhoodAccessor()274 const NeighborhoodAccessorFunctorType GetNeighborhoodAccessor() const 275 { return NeighborhoodAccessorFunctorType(); } 276 277 unsigned int GetNumberOfComponentsPerPixel() const override; 278 279 protected: 280 Image(); 281 void PrintSelf(std::ostream & os, Indent indent) const override; 282 void Graft(const DataObject *data) override; 283 284 ~Image() override = default; 285 286 /** Compute helper matrices used to transform Index coordinates to 287 * PhysicalPoint coordinates and back. This method is virtual and will be 288 * overloaded in derived classes in order to provide backward compatibility 289 * behavior in classes that did not used to take image orientation into 290 * account. */ 291 void ComputeIndexToPhysicalPointMatrices() override; 292 using Superclass::Graft; 293 private: 294 /** Memory for the current buffer. */ 295 PixelContainerPointer m_Buffer; 296 }; 297 } // end namespace itk 298 299 #ifndef ITK_MANUAL_INSTANTIATION 300 #include "itkImage.hxx" 301 #endif 302 303 #endif 304