1 // This is mul/vil3d/vil3d_image_resource.h 2 #ifndef vil3d_image_resource_h_ 3 #define vil3d_image_resource_h_ 4 //: 5 // \file 6 // \brief Representation of a generic image source or destination. 7 // 8 // \author Ian Scott 9 // \date 2 Mar 2003 10 11 #include <vil3d/vil3d_image_view_base.h> 12 #include <cassert> 13 #ifdef _MSC_VER 14 # include <vcl_msvc_warnings.h> 15 #endif 16 #include <vil/vil_smart_ptr.h> 17 #include <vil/vil_pixel_format.h> 18 19 //: 20 // Abstract representation of an image source or image destination. 21 // Most references to vil3d_image_resource objects should usually be done 22 // through smart pointers - vil3d_image_resource_sptr; 23 // 24 // All image data is presumed to be in planes, not components. This 25 // does not say whether the data is stored on disk or in memory 26 // as RGBRGBRGB.. or RRR..GGG..BBB.., just that the interface will 27 // always tell you that it has a multi-plane single-component view. 28 class vil3d_image_resource 29 { 30 public: 31 vil3d_image_resource() = default; 32 virtual ~vil3d_image_resource() = default; 33 34 //: Dimensions: Planes x ni x nj. 35 // This concept is treated as a synonym to components. 36 virtual unsigned nplanes() const = 0; 37 //: Dimensions: Planes x ni x nj x nk. 38 // The number of pixels in each row. 39 virtual unsigned ni() const = 0; 40 //: Dimensions: Planes x ni x nj x nk. 41 // The number of pixels in each column. 42 virtual unsigned nj() const = 0; 43 //: Dimensions: Planes x ni x nj x nk. 44 // The number of pixels in each column. 45 virtual unsigned nk() const = 0; 46 47 //: Pixel Format. 48 // pixel_format() == VIL_PIXEL_FORMAT_BYTE 49 virtual enum vil_pixel_format pixel_format() const = 0; 50 51 //: Create a read/write view of the data. 52 // Modifying this view might modify the actual data. 53 // If you want to modify this data in place, call put_view after you done, 54 // and it should work efficiently. This function will always return a 55 // multi-plane scalar-pixel view of the data. 56 // \return 0 if unable to get view of correct size, or if resource is 57 // write-only. 58 // 59 // If you want to fill an existing view (e.g. a window onto some other 60 // image), then use \code vil3d_reformat(data->get_view(..), window); 61 //\endcode get_view(unsigned i0,unsigned ni,unsigned j0,unsigned nj,unsigned k0,unsigned nk)62 virtual vil3d_image_view_base_sptr get_view(unsigned i0, unsigned ni, 63 unsigned j0, unsigned nj, 64 unsigned k0, unsigned nk) const { 65 return get_copy_view(i0, ni, j0, nj, k0, nk); } 66 67 //: Create a read/write view of all the data. get_view()68 vil3d_image_view_base_sptr get_view() const 69 { return get_view (0, ni(), 0, nj(), 0, nk()); } 70 71 72 //: Set the size of the each voxel in the i,j,k directions in mm 73 // You can get the voxel sizes via get_properties(). 74 // Note that get_properties() returns voxel sizes in metres, not mm. 75 // \return false if underlying image doesn't store pixel sizes. set_voxel_size_mm(float,float,float)76 virtual bool set_voxel_size_mm(float/*i*/,float/*j*/,float/*k*/) {return false;} 77 78 //: Create a read/write view of a copy of this data. 79 // This function will always return a 80 // multi-plane scalar-pixel view of the data. 81 // \return 0 if unable to get view of correct size, or if resource is write-only. 82 virtual vil3d_image_view_base_sptr get_copy_view(unsigned i0, unsigned ni, 83 unsigned j0, unsigned nj, 84 unsigned k0, unsigned nk) const = 0; 85 86 //: Put the data in this view back into the image source. 87 // The view must be of scalar components. Assign your 88 // view to a scalar-component view if this is not the case. 89 // \return false if failed, because e.g. resource is read-only, 90 // format of view is not correct (if it is a compound pixel type, try 91 // assigning it to a multi-plane scalar pixel view.) 92 virtual bool put_view(const vil3d_image_view_base& im, 93 unsigned i0=0, unsigned j0=0, unsigned k0=0) = 0; 94 95 //: Check that a view will fit into the data at the given offset. 96 // This includes checking that the pixel type is scalar. view_fits(const vil3d_image_view_base & im,unsigned i0,unsigned j0,unsigned k0)97 virtual bool view_fits(const vil3d_image_view_base& im, 98 unsigned i0, unsigned j0, unsigned k0) 99 { 100 return (i0 + im.ni() <= ni() && j0 + im.nj() <= nj() && 101 k0 + im.nk() <= nk() && im.nplanes() == nplanes() && 102 vil_pixel_format_num_components(im.pixel_format()) == 1); 103 } 104 105 //: Return a string describing the file format. 106 // Only file images have a format, others return 0 file_format()107 virtual char const* file_format() const { return nullptr; } 108 109 //: Extra property information 110 // Note that get_properties() returns voxel sizes in metres, not mm. 111 virtual bool get_property(char const* label, void* property_value = nullptr) const =0; 112 113 private: 114 // You probably should not use a vil3d_image_resource in a vbl_smart_ptr, so the 115 // ref functions are private 116 friend class vil_smart_ptr<vil3d_image_resource>; ref()117 void ref() { ++reference_count_; } unref()118 void unref() { 119 assert(reference_count_>0); 120 if (--reference_count_<=0) delete this;} 121 int reference_count_{0}; 122 }; 123 124 //: Use this type to refer to and store a vil3d_image_resource 125 // This object is used to provide safe manipulation of 126 // vil3d_image_resource derivatives. If you want to 127 // store an image resource (e.g. an image on disk, type-agnostic 128 // memory image), then use this type. 129 typedef vil_smart_ptr<vil3d_image_resource> vil3d_image_resource_sptr; 130 131 #endif // vil3d_image_resource_h_ 132