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