nullmask.h

Go to the documentation of this file.

/***
 * \file rvc/nullmask.h 
 * \brief interface for the RVC::NULLMASK class.
 *
 * \if NODOC
 * $Id: nullmask.h_v 1.19 2005/08/19 14:39:10 scowan Exp $
 *
 * $Log: nullmask.h_v $
 * Revision 1.19  2005/08/19 14:39:10  scowan
 * Impolemented special copy object virtual method.
 *
 * Revision 1.18  2004/09/01 12:43:24  mju
 * Add 'allvalid' parm to Make().
 *
 * Revision 1.17  2004/08/31 17:46:14  scowan
 * Support cache size virtual methods.
 *
 * Revision 1.16  2004/07/20 17:23:07  scowan
 *  Added write method that takes a bool.
 *
 * Revision 1.15  2004/02/24 18:34:08  scowan
 * Simplified to only use binary masks.
 *
 * Revision 1.14  2003/11/21 22:17:07  scowan
 * Support new Capabilities system.
 *
 * Revision 1.13  2003/10/31 17:17:28  scowan
 * Added get object filter.
 *
 * Revision 1.12  2003/10/30 18:27:35  scowan
 * Updated pyramid creation.
 *
 * Revision 1.11  2003/10/23 21:25:15  scowan
 * Changed get pyramid list function.
 *
 * Revision 1.10  2003/10/07 17:32:19  scowan
 * Object virtual method changes.
 *
 * Revision 1.9  2003/09/30 16:52:06  dwilliss
 * Doxygen
 *
 * Revision 1.8  2003/09/25 21:20:04  dwilliss
 * Fixed doxygen comment
 *
 * Revision 1.7  2003/09/15 23:17:33  scowan
 * Support new set null value virtual method.
 *
 * Revision 1.6  2003/09/15 13:49:45  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.5  2003/08/27 21:26:37  scowan
 * Supports usage of rgba and argb raster cell types.
 *
 * Revision 1.4  2003/06/27 20:37:18  scowan
 * Updated to actually be useful.
 *
 * Revision 1.3  2003/05/07 15:20:30  scowan
 * Updated to new virtual method setting.
 *
 * Revision 1.2  2003/03/17 21:42:40  scowan
 * nc.
 *
 * Revision 1.1  2002/03/12 17:33:35  scowan
 * Initial revision
 *
 * \endif
***/

//!   \class RVC::NULLMASK rvc/nullmask.h
//!   \brief Manages RVC::OBJTYPE_Raster RVC::RASTER::USAGE_NullBand child 1-bit raster objects.
//!   
//!   RVC Object Types that this class supports: RVC::OBJTYPE_Raster (RVC::RASTER::USAGE_NullBand).
//!
//!   Default RVC Object Type for this class: RVC::OBJTYPE_Raster.
//!
//!   Valid parents for this class:
//!      - RVC::OBJTYPE_Raster
//!      - RVC::OBJTYPE_Hyperspectral
//!      - RVC::OBJTYPE_RasterSet
//!      - RVC::OBJTYPE_Thumbnail

#ifndef INC_RVC_NULLMASK_H
#define INC_RVC_NULLMASK_H

#ifndef INC_RVC_RASTER_H
   #include <rvc/raster.h>
#endif

#ifndef INC_MI32_SIMPLEAR_H
   #include <mi32/simplear.h>
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
class BITSET_UNOWNED;
#endif // GENERATING_DOXYGEN_OUTPUT

namespace RVC {

class NULLMASK : public RVC::IMAGE {
   public:
      
      #ifndef GENERATING_DOXYGEN_OUTPUT
      class GETOBJFILTER_ISVALIDNULLMASK;
      class OBJECT_FILTER;
      #endif // GENERATING_DOXYGEN_OUTPUT

      //! Default constructor.
      NULLMASK (
         );

      //! Copy constructor.
      NULLMASK (
         const RVC::NULLMASK& rhs
         );

      //! Destructor
      virtual ~NULLMASK (
         );

      //! Assignment.
      RVC::NULLMASK& operator= (
         const RVC::NULLMASK& rhs
         );

      //! Obtain nullmask cell type.
      //! @return RVC::IMAGE::CELLTYPE of the raster
      IMAGE::CELLTYPE GetCellType (
         ) const { return (IMAGE::CELLTYPE_Binary); }
         
      //! Obtain number of columns in a nullmask tile
      //! @return number of columns in the nullmask tile
      INT32 GetNumTileColumns (
         ) const;

      //! Obtain number of lines in a nullmask tile
      //! @return number of lines in the nullmask tile
      INT32 GetNumTileLines (
         ) const;

      //! Obtain number of tiles in a nullmask row
      //! @return number of row tiles
      INT32 GetNumXTiles (
         ) const;

      //! Obtain number of tiles in a nullmask column
      //! @return number of column tiles
      INT32 GetNumYTiles (
         ) const;

      //! Return list of available raster pyramid sub-rasters.
      //!   The sample rate list will be sorted in ascending order and the array and list are aligned.
      ERRVALUE GetPyramidList (
         SIMPLE_ARRAY<INT32>& SampleList,       //!< Simple array of available sample rates RETURNED
         RVC::OBJITEMLIST& PyramidList          //!< List of pyramid raster NullMask ObjItem's RETURNED
         );
         
      //! Obtain number of bytes in a nullmask tile
      //! @return size of nullmask tile in bytes
      INT32 GetTileSizeBytes (
         ) const;

      //! Determine if a mask is present or the image has a null value defined
      //! @return 'True' if a meaningful null value or mask exists, 'false' otherwise
      bool HasNullValues (
         ) const;

      //! Create a null mask object under the RVC::IMAGE parent.
      //! If a null mask raster already exists, it will perform an Open(*this, OBJECT::OPENMODE_Write).
      //! If the parent raster has a null value set it will be used to initialize the mask, otherwise
      //! the initvalue parameter will determine the initial mask state.
      //! CellType == RVC::IMAGE::CELLTYPE_Binary
      //! Compression type == RVC::RASTER::COMPTYPE_RLE
      //! Tile Size == Same as parent
      //! Scale == Same as parent
      ERRVALUE Make (
         const RVC::IMAGE& parent,              //!< Parent object to create nullmask under
         bool initvalid,                        //!< Initialize to be all 'valid' if cannot determine from parent
         const char* Source = 0                 //!< Source of nullmask creation, default is GetAppName()
         );

      //! Create a null mask object under the RVC::IMAGE parent.
      //! If a null mask raster already exists, it will perform an Open(*this, OBJECT::OPENMODE_Write).
      //! If the parent raster has a null value set it will be used to initialize the mask, otherwise
      //! the initvalue parameter will determine the initial mask state.
      //! CellType == RVC::IMAGE::CELLTYPE_Binary
      //! Compression type == RVC::RASTER::COMPTYPE_RLE
      //! Tile Size == Same as parent
      //! Scale == Same as parent
      ERRVALUE Make (
         const RVC::OBJITEM& ObjItem,           //!< Parent object to create nullmask under
         bool initvalid,                        //!< Initialize to be all 'valid' if cannot determine from parent
         const char* Source = 0                 //!< Source of nullmask creation, default is GetAppName()
         );

      //! Create pyramid null mask set under the existing raster pyramids
      ERRVALUE MakePyramidSet (
         IMAGE::PYRAMID flags = IMAGE::PYRAMID_None
         );

      //! Open a null mask under the RVC::IMAGE parent.
      //! If a null mask cannot be found, it will use the null value from the parent 
      //! and treat it like a null mask
      ERRVALUE Open (
         const RVC::IMAGE& parent,              //!< Parent image object to open null mask under
         OBJECT::OPENMODE OpenMode = OBJECT::OPENMODE_Read
         );       

      //! Read a line of nullmask cells up to a certain length
      //! False values in the bitset are nulls
      //! @return '>0' if there can exist null values, '0' if all values are known to be not null, '<0' error
      int Read (
         INT32 Line,                            //!< Raster line to read
         INT32 StartColumn,                     //!< Raster column to start reading on
         BITSET_UNOWNED& data,                  //!< Buffer to read into
         INT32 Length = 1                       //!< Number of columns to read
         ) const;

      //! Read a line of nullmask cells up to a certain length
      //! Values == 0 are nulls, values == 255 are not
      //! @return '>0' if there can exist null values, '0' if all values are known to be not null, '<0' error
      int Read (
         INT32 Line,                            //!< Raster line to read
         INT32 StartColumn,                     //!< Raster column to start reading on
         UINT8 *data,                           //!< Buffer to read into
         INT32 Length = 1                       //!< Number of columns to read
         ) const;

      //! Read a column of nullmask cells up to a certain length
      //! False values in the bitset are nulls
      //! @return '>0' if there can exist null values, '0' if all values are known to be not null, '<0' error
      int ReadColumn (
         INT32 StartLine,                       //!< Raster line to start reading on
         INT32 Column,                          //!< Raster column to read
         BITSET_UNOWNED& data,                  //!< Buffer to read into
         INT32 Length = 1                       //!< Number of lines to read
         ) const;

      //! Read a column of nullmask cells up to a certain length
      //! Values == 0 are nulls, values == 255 are not
      //! @return '>0' if there can exist null values, '0' if all values are known to be not null, '<0' error
      int ReadColumn (
         INT32 StartLine,                       //!< Raster line to start reading on
         INT32 Column,                          //!< Raster column to read
         UINT8 *data,                           //!< Buffer to read into
         INT32 Length = 1                       //!< Number of lines to read
         ) const;

      //! Write a line of nullmask cells up to a certain length
      //! If the null values are from the parent image, a NullMask raster will
      //! be created under the parent image with a celltype of IMAGE::CELLTYPE_Binary, the
      //! current null values setup in the new object, then the buffer will be written
      ERRVALUE Write (
         INT32 Line,                            //!< Raster line to write
         INT32 StartColumn,                     //!< Raster column to start writing on
         BITSET_UNOWNED& data,            //!< Buffer to write from
         INT32 Length = 1                       //!< Number of columns to write
         );

      //! Write a line of nullmask cells up to a certain length.
      //! If the null values are from the parent image, a NullMask raster will
      //! be created under the parent image with a celltype of IMAGE::CELLTYPE_Binary, the
      //! current null values setup in the new object, then the buffer will be written
      ERRVALUE Write (
         INT32 Line,                            //!< Raster line to write
         INT32 StartColumn,                     //!< Raster column to start writing on
         UINT8* data,                  //!< Buffer to write from
         INT32 Length = 1                       //!< Number of columns to write
         );

      //! Write a line of nullmask values up to a certain length
      //! If the null values are from the parent image, a NullMask raster will
      //! be created under the parent image with a celltype of IMAGE::CELLTYPE_Binary, the
      //! current null values setup in the new object, then the buffer will be written
      ERRVALUE Write (
         INT32 Line,                            //!< Raster line to write
         INT32 StartColumn,                     //!< Raster column to start writing on
         bool valid,                            //!< Value to write, 'true' for valid, 'false' for not valid
         INT32 Length = 1                       //!< Number of columns to write
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      IMAGE* m_Image;         //!< Open image object
      RASTER m_MaskObj;       //!< Open raster mask object
      NULLVALUE m_NullValue;
      bool m_HasNullValue;
      IMAGE::CELLTYPE m_ParentCellType;
      mutable SIMPLE_ARRAY<UINT8> m_Buffer;
      class NULLOBSERVER;
      friend class NULLOBSERVER;
      NULLOBSERVER* m_Observer;
      SIMPLE_ARRAY<UINT8> m_TrueBuffer;
      SIMPLE_ARRAY<UINT8> m_FalseBuffer;
      
      //! Implementation of RVC::OBJECT virtual methods
      virtual ERRVALUE v_CloseObject ();
      virtual ERRVALUE v_CopyObject (RVC::OBJECT& DestParentObj, RVC::OBJECT& DestObj, FILTER* filter, COPYFLAGS CopyFlags) const;
      virtual RVC::OBJTYPE v_GetDftObjectType () const;
      virtual bool v_IsObjectOpen () const;              
      virtual ERRVALUE v_OpenObject (OPENMODE OpenFlags, MDLGPARENT parent);
         
      //! Implementation of RVC::GEOSPATIAL virtual methods
      virtual void v_GetExtents (DRECT3D &extents) const;
      virtual void v_GetScale (double& xscale, double& yscale) const;
      virtual double v_GetZScale () const;
      virtual double v_GetZOffset () const;
      virtual bool v_HasCapability (int Capability) const;
      virtual void v_SetScale (double xscale, double yscale);
      virtual void v_SetZScale (double zscale);
      virtual void v_SetZOffset (double zoffset);
      
      //! Implementation of RVC::IMAGE virtual methods
      virtual ERRVALUE v_GetBandParms (INT32 BandNum, BANDPARMS& BandParms) const;
      virtual double v_GetColumnScale () const;
      virtual double v_GetLineScale () const;
      virtual ERRVALUE v_GetNullValue (INT32 BandNum, NULLVALUE& NullValue) const;
      virtual INT32 v_GetNumBands () const;
      virtual INT32 v_GetNumColumns () const;
      virtual INT32 v_GetNumLines () const;
      virtual bool v_HasNullValue (INT32 BandNum) const;
      virtual ERRVALUE v_ReadBand (INT32 Band, INT32 Line, INT32 StartColumn, void *data, INT32 Length, CONVMODE Convert) const;
      virtual ERRVALUE v_ReadColumnBand (INT32 Band, INT32 Line, INT32 StartColumn, void *data, INT32 Length, CONVMODE Convert) const;
      virtual ERRVALUE v_SetCacheSize (INT32 NumTiles);
      virtual ERRVALUE v_SetCacheSize (CACHEMODE CacheFlags);
      virtual ERRVALUE v_SetNullValue (INT32 BandNum, const NULLVALUE* NullValue);
      virtual ERRVALUE v_WriteBand (INT32 Band, INT32 Line, INT32 StartColumn, void *data, INT32 Length, CONVMODE Convert);
      #endif // GENERATING_DOXYGEN_OUTPUT

   };


//! Convenience filter for raster null mask selection.  
//! Valid null mask raster selection is based on the size of the image to select for
class NULLMASK::GETOBJFILTER_ISVALIDNULLMASK : public GETOBJFILTER {
   public:
      explicit GETOBJFILTER_ISVALIDNULLMASK (
         const RASTER& RastObj
         );
         
      explicit GETOBJFILTER_ISVALIDNULLMASK (
         const RASTER::MAKEPARMS& MakeParms
         );
         
      GETOBJFILTER_ISVALIDNULLMASK (
         INT32 NumLines,
         INT32 NumColumns
         );
         
   private:
      INT32 m_NumLines;
      INT32 m_NumColumns;
      
      virtual bool v_HasSelectableSubObjects (const RVC::OBJITEM& objitem);
      virtual bool v_IsSelectable (const RVC::OBJITEM& objitem, int position = -1);
   };
   

//! Object filter for finding NULLMASK raster objects
class NULLMASK::OBJECT_FILTER : public OBJECT::FILTER {
   public:
      OBJECT_FILTER () {}
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      virtual bool Filter (const RVC::OBJECT& obj);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

}     //! End of RVC namespace

#endif      //!< INC_RVC_NULLMASK_H

---