text: //*******************************************************************
  //
  // License: MIT
  //
  // See LICENSE.txt file in the top level directory for more details.
  //
  // Author:  Oscar Kramer
  //
  //*******************************************************************
  //  $Id: ossimBitMaskTileSource.h 2644 2011-05-26 15:20:11Z oscar.kramer $
  
  #ifndef ossimBitMaskTileSource_HEADER
  #define ossimBitMaskTileSource_HEADER
  
  #include <ossim/imaging/ossimImageHandler.h>
  #include <ossim/imaging/ossimBitMaskWriter.h>
  
  class ossimImageGeometry;
  
  //*************************************************************************************************
  //! This is the image handler for providing mask pixels to an ossimMaskFilter object.
  //!
  //! This class takes care of reading the custom, bit-compressed OSSIM bit mask file format. 
  //! 
  //! When the developer needs to mask an image, the following needs to be done:
  //!
  //!   Creating the Mask:
  //!   1. A mask file first needs to be created using ossimBitMaskWriter and a source image. The app
  //!      "img2rr --create-mask" directs that program to use ossimBitMaskWriter to generate a mask  
  //!      during overview generation. There is also create-bitmask app that will generate the mask.
  //!   2. An OSSIM ".mask" file should exist on disk after step 0. This is typically the same base 
  //!      name as the source image file being masked.
  //!   
  //!   Using the Mask:
  //!   1. An ossimBitMaskTileSource (derived from ossimImageHandler) needs to be instantiated and
  //!      the mask file name used to open it. 
  //!   3. An ossimMaskFilter (derived from ossimImageCombiner) is the actual filter that combines
  //!      the source image handler and the ossimBitMaskTileSource object to provide the resultant 
  //!      masked tiles.
  //!      
  //! The OSSIM bit mask file contains a small header that consists of:
  //!    magic number,
  //!    starting res level,
  //!    number of res levels
  //!    num columns at starting res level,
  //!    num rows at starting res level, 
  //!    num columns at 2nd res level,
  //!    num rows at 2nd res level, 
  //!    etc., for all res levels
  //!    <space> 
  //!    <compressed binary mask data>
  //!
  //! The number of rows and columns represents the number of bytes in the mask, with each byte
  //! containing 8 alpha mask bits representing 8 pixels in the original image.
  //!
  //! This class functions as an image handler, returning 255 for unmasked pixels, and 0 for masked 
  //! pixels. 
  //! 
  //! For debug purposes, this code initializes the tile to all 128's so that the 
  //! ossimMaskFilter can recognize uninitialized mask data.
  //!
  //*************************************************************************************************
  
  class OSSIM_DLL ossimBitMaskTileSource : public ossimImageHandler
  {
  public:
  
     ossimBitMaskTileSource();
  
     //! Return a tile of masks. These are "bit masks", i.e., either 0 (hide) or 1 (show).
     //! The pixels' remaining 7 bits are cleared and should not be used.
     virtual ossimRefPtr<ossimImageData> getTile(const ossimIrect& tile_rect, ossim_uint32 rLevel=0);
     
     virtual bool         isValidRLevel     (ossim_uint32 res_level)   const;
     virtual ossim_uint32 getNumberOfLines  (ossim_uint32 res_level=0) const;
     virtual ossim_uint32 getNumberOfSamples(ossim_uint32 res_level=0) const;
  
     virtual ossim_uint32    getNumberOfInputBands()  const { return 1; }
     virtual ossim_uint32    getNumberOfOutputBands() const { return 1; }
     virtual ossimScalarType getOutputScalarType()    const { return OSSIM_UINT8; }
     virtual ossim_uint32    getImageTileWidth()      const { return 0; }
     virtual ossim_uint32    getImageTileHeight()     const { return 0; }   
  
     virtual bool isOpen() const;
     virtual bool open();
     virtual void close();
  
     virtual double getNullPixelValue(ossim_uint32 /*band=0*/) const { return 0; }
     virtual double getMinPixelValue (ossim_uint32 /*band=0*/) const { return 0; }
     virtual double getMaxPixelValue (ossim_uint32 /*band=0*/) const { return 1.0; }
  
     //! There is no geometry associated with a mask file -- it is pixel-for-pixel mapped to
     //! an image file. The image file must have the valid geometry.
     virtual ossimRefPtr<ossimImageGeometry> getImageGeometry();
  
     //! Overrides base class implementation.
     virtual ossim_uint32 getNumberOfDecimationLevels() const;
  
     //! For backward compatibility with older mask format ("Ming Mask"), provide for associating
     //! the mask with an image handler:
     void setAssociatedImageHandler(ossimImageHandler* handler);
  
     //! This class can be used during overview generation, in which case there will be a simultaneous
     //! mask writing. Instead of accessing a mask file (which may not yet exist), the mask buffer
     //! of the writer will be accessed directly instead of our own buffer.
     void setAssociatedMaskWriter(ossimBitMaskWriter* maskWriter);
  
  protected:
     virtual ~ossimBitMaskTileSource();
     
     //! Returns true if this handler recognizes the file name extension as an OSSIM raster mask file.
     bool isSupportedExtension();
  
     virtual void establishDecimationFactors();
  
     ossimRefPtr<ossimImageData>  m_tile;
     vector<ossim_uint8*>         m_buffers;
     vector<ossimIpt>             m_bufferSizes;
     
     //! For backward compatibility with older mask format ("Ming Mask"), provide for associating
     //! the mask with an image handler:
     ossimRefPtr<ossimImageHandler>  m_handler;
  
     //! This class can be used during overview generation, in which case there will be a simultaneous
     //! mask writing. Instead of accessing a mask file (which may not yet exist), the mask buffer
     //! of the writer will be accessed directly instead of our own buffer.
     ossimRefPtr<ossimBitMaskWriter>  m_maskWriter;
  
     TYPE_DATA
  };
  
  #endif
  
  
  