core/vil/vil_image_resource.h
Go to the documentation of this file.
00001 // This is core/vil/vil_image_resource.h
00002 #ifndef vil_image_resource_h_
00003 #define vil_image_resource_h_
00004 #ifdef VCL_NEEDS_PRAGMA_INTERFACE
00005 #pragma interface
00006 #endif
00007 //:
00008 // \file
00009 // \brief Representation of a generic image source or destination.
00010 //
00011 // \author Ian Scott
00012 // \date 20 Sep 2002
00013 
00014 #include <vil/vil_image_view_base.h>
00015 #include <vcl_cassert.h>
00016 #include <vcl_atomic_count.h>
00017 #include <vil/vil_smart_ptr.h>
00018 #include <vil/vil_pixel_format.h>
00019 
00020 #include <vil/vil_image_resource_sptr.h>
00021 
00022 //:
00023 // Abstract representation of an image source or image destination.
00024 // Most references to vil_image_resource objects should usually be done
00025 // through smart pointers - vil_image_resource_sptr;
00026 //
00027 // All image data is presumed to be in planes, not components. This
00028 // does not say whether the data is stored on disk or in memory
00029 // as RGBRGBRGB.. or RRR..GGG..BBB.., just that the interface will
00030 // always tell you that it has a multi-plane single-component view.
00031 class vil_image_resource
00032 {
00033  public:
00034   vil_image_resource();
00035   virtual ~vil_image_resource();
00036 
00037   //: Dimensions:  Planes x ni x nj.
00038   // This concept is treated as a synonym to components.
00039   virtual unsigned nplanes() const = 0;
00040   //: Dimensions:  Planes x ni x nj.
00041   // The number of pixels in each row.
00042   virtual unsigned ni() const = 0;
00043   //: Dimensions:  Planes x ni x nj.
00044   // The number of pixels in each column.
00045   virtual unsigned nj() const = 0;
00046 
00047   //: Pixel Format.
00048   //  A standard RGB RGB RGB of chars image has
00049   // pixel_format() == VIL_PIXEL_FORMAT_BYTE
00050   virtual enum vil_pixel_format pixel_format() const = 0;
00051 
00052   //: Create a read/write view of the data.
00053   // Modifying this view might modify the actual data.
00054   // If you want to modify this data in place, call put_view after you done, and
00055   // it should work efficiently. This function will always return a
00056   // multi-plane scalar-pixel view of the data.
00057   // \return 0 if unable to get view of correct size, or if resource is write-only.
00058   //
00059   // If you want to fill an existing view (e.g. a window onto some other image),
00060   // then use
00061   // \verbatim
00062   // vil_reformat(data->get_view(..), window);
00063   //\endverbatim
00064   virtual vil_image_view_base_sptr get_view(unsigned i0, unsigned n_i,
00065                                             unsigned j0, unsigned n_j) const
00066   { return get_copy_view (i0, n_i, j0, n_j); }
00067 
00068   //: Create a read/write view of all the data.
00069   vil_image_view_base_sptr get_view() const
00070   { return get_view (0, ni(), 0, nj()); }
00071 
00072   //: Create a read/write view of a copy of this data.
00073   // This function will always return a
00074   // multi-plane scalar-pixel view of the data.
00075   // \return 0 if unable to get view of correct size, or if resource is write-only.
00076   virtual vil_image_view_base_sptr get_copy_view(unsigned i0, unsigned n_i,
00077                                                  unsigned j0, unsigned n_j) const = 0;
00078 
00079   //: Create a read/write view of a copy of all the data.
00080   vil_image_view_base_sptr get_copy_view() const
00081   { return get_copy_view (0, ni(), 0, nj()); }
00082 
00083   //: Put the data in this view back into the image source.
00084   // The view must be of scalar components. Assign your
00085   // view to a scalar-component view if this is not the case.
00086   // \return false if failed, because e.g. resource is read-only,
00087   // format of view is not correct (if it is a compound pixel type, try
00088   // assigning it to a multi-plane scalar pixel view.)
00089   virtual bool put_view(const vil_image_view_base& im, unsigned i0, unsigned j0) = 0;
00090 
00091   //: Put the data in this view back into the image source at the origin
00092   virtual bool put_view(const vil_image_view_base& im)
00093   { return put_view(im, 0, 0); }
00094 
00095   //: Check that a view will fit into the data at the given offset.
00096   // This includes checking that the pixel type is scalar.
00097   virtual bool view_fits(const vil_image_view_base& im, unsigned i0, unsigned j0);
00098 
00099   //: Return a string describing the file format.
00100   // Only file images have a format, others return 0
00101   virtual char const* file_format() const { return 0; }
00102 
00103   //: Extra property information
00104   virtual bool get_property(char const* tag, void* property_value = 0) const =0;
00105 
00106  protected:
00107   // You probably should not use a vil_image_resource in a vbl_smart_ptr, so the
00108   // ref functions are private
00109   friend class vil_smart_ptr<vil_image_resource>;
00110   void ref() { ++reference_count_; }
00111   void unref() {
00112     assert(reference_count_>0);
00113     if (--reference_count_<=0) delete this;}
00114   vcl_atomic_count reference_count_;
00115 };
00116 
00117 #endif // vil_image_resource_h_