geospatl.h

Go to the documentation of this file.

/**
 * \file rvc/geospatl.h 
 * \brief interface for the RVCGEOSPATIAL class.
 *
 * \if NODOC
 * $Id: geospatl.h_v 1.34 2004/12/03 17:15:05 scowan Exp $
 *
 * $Log: geospatl.h_v $
 * Revision 1.34  2004/12/03 17:15:05  scowan
 * Updated docs on has capability..
 *
 * Revision 1.33  2004/10/01 20:32:15  mju
 * Remove unused computeObjectScale variants previously deprecated.
 *
 * Revision 1.32  2004/09/09 15:49:52  mju
 * Add convertToMeters parm for computeObjectScale and computeScaleFromGeoref.
 * Deprecate other variants of aforementioned methods.
 *
 * Revision 1.31  2004/07/19 23:23:13  scowan
 * Removed legacy method.
 *
 * Revision 1.30  2004/07/13 15:37:35  mju
 * Add getobjfilter_hasgeoreference.
 *
 * Revision 1.29  2004/06/24 16:25:59  scowan
 * Better support for region2d.
 *
 * Revision 1.28  2004/03/12 14:53:05  mju
 * Add getobjfilter_hasgeoreference.
 *
 * Revision 1.27  2004/03/04 18:42:42  scowan
 * Added dtor for filter.
 *
 * Revision 1.26  2004/02/09 20:33:19  scowan
 * Added new get object region method.
 *
 * Revision 1.25  2003/11/21 22:17:05  scowan
 * Support new Capabilities system.
 *
 * Revision 1.24  2003/10/22 16:17:05  scowan
 * Added get objtype set static method.
 *
 * Revision 1.23  2003/09/30 16:52:06  dwilliss
 * Doxygen
 *
 * Revision 1.22  2003/09/25 21:56:37  dwilliss
 * doxygen
 *
 * Revision 1.21  2003/09/15 13:49:45  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.20  2003/09/11 17:55:34  scowan
 * Added is geospatial method.
 *
 * Revision 1.19  2003/08/13 16:31:18  scowan
 * Added another copy georef to method.
 *
 * Revision 1.18  2003/08/12 21:07:41  scowan
 * Added copy georef to methods.
 *
 * Revision 1.17  2003/08/04 16:45:47  scowan
 * Added method to compute translation betrween two geospatial objects.
 *
 * Revision 1.16  2003/08/01 19:52:46  scowan
 * Fixed ignore and end ignore items.
 *
 * Revision 1.15  2003/08/01 19:09:25  scowan
 * Added is overlapping filter.
 *
 * Revision 1.14  2003/07/23 17:20:15  mju
 * Remove 'allow arbitrary' parm from ChkGeoref and GetDftGeoref methods.
 *
 * Revision 1.13  2003/07/23 17:00:32  scowan
 * Added enum.
 *
 * Revision 1.12  2003/05/30 21:33:29  scowan
 * Added is selectable filter.
 *
 * Revision 1.11  2003/05/07 22:19:23  scowan
 * Changed virutal method format.
 *
 * Revision 1.10  2002/04/26 22:44:32  scowan
 * Added more virtual methods.
 *
 * Revision 1.9  2002/04/24 19:30:44  scowan
 * Added check name method.
 *
 * Revision 1.8  2002/04/24 16:02:18  scowan
 * Added get object region method.
 *
 * Revision 1.7  2002/03/01 15:31:46  scowan
 * Added another get geospatial method.
 *
 * Revision 1.6  2001/10/25 21:54:28  scowan
 * Changed check to get.
 *
 * Revision 1.5  2001/06/14 15:14:46  scowan
 * Added to RVC namespace.
 *
 * Revision 1.4  2001/05/31 21:43:21  scowan
 * More const.
 *
 * Revision 1.3  2000/11/24 22:47:48  scowan
 * oops.
 *
 * Revision 1.2  2000/10/19 17:56:00  scowan
 * Checked in for vacation.
 *
 * Revision 1.1  2000/09/29 15:26:32  scowan
 * Initial revision
 * \endif
**/

//!   \class RVC::GEOSPATIAL rvc/geospatl.h
//!   \brief Interface for RVC objects that support a georeferences paradigm.
//!
//!   This includes methods to get the scale, offset, and retrieving the correct georeference.
//!
//!   RVC Object Types that this class supports: Derived class
//!
//!   Default RVC Object Type for this class: Derived class
//!
//!   Valid parents for this class: Derived class

#ifndef INC_RVC_GEOSPATL_H
#define INC_RVC_GEOSPATL_H

#ifndef INC_RVC_OBJECT_H
   #include <rvc/object.h>
#endif

#ifndef INC_RVC_GETOBJF_H
   #include <rvc/getobjf.h>
#endif

#ifndef INC_MI32_TRANS2DC_H
   #include <mi32/trans2dc.h>
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
class REGION2D;         // Forward declarations
#endif // GENERATING_DOXYGEN_OUTPUT

namespace RVC {

#ifndef GENERATING_DOXYGEN_OUTPUT
class GEOREFERENCE;  // Forward declarations
#endif // GENERATING_DOXYGEN_OUTPUT

class GEOSPATIAL : public RVC::OBJECT {
   public:
   
      //Ignore
      class GETOBJFILTER_ISSELECTABLE;
      class GETOBJFILTER_ISOVERLAPPING;
      class GETOBJFILTER_HASGEOREFERENCE;
      class GETOBJFILTER_HASNOGEOREFERENCE;
      //End Ignore
      
      enum CAPABILITY {
         CAPABILITY_None =         0,
         CAPABILITY_RandomAccess = 256,      //!< Object is capable of random access to elements
         CAPABILITY_CanBeModified,           //!< Object can be modified
         CAPABILITY_LoginRequired            //!< A login ( username and password ) is required to access this object
         };
         
      enum MAKELINKFLAGS {
         MAKELINKFLAG_None =              0x0000,
         MAKELINKFLAG_NoGeoreference =    0x0001,  //!< Don't create georeference subobjects
         MAKELINKFLAG_NoPyramidLinks =    0x0002,  //!< Don't create raster pyramid tier links
         MAKELINKFLAG_BuildHistograms =   0x0004,  //!< Build raster histogram subobjects when make link
         MAKELINKFLAG_BuildPyramids =     0x0008,  //!< Build raster pyramid tiers when make link
         MAKELINKFLAG_NoContrastTables =  0x0010,  //!< Don't create raster contrast tables
         MAKELINKFLAG_ColorComposite =    0x0020,  //!< Create raster links as color-composite (RGB) where appropriate
         MAKELINKFLAG_ColorSeparate =     0x0040   //!< Create raster links as color separates where appropriate
         };
         
      enum OBJECTREGIONFLAGS {
         OBJECTREGION_Default =           0x0000,
         OBJECTREGION_UseGeorefModel =    0x0001,  //!< Use warping model specified by georeference
         OBJECTREGION_ForceArbitrary =    0x0002   //!< Force region to use arbitrary
         };

      //! Default constructor
      GEOSPATIAL (
         );

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

      //! Destructor
      virtual ~GEOSPATIAL (
         ) = 0;

      //! Check if the georeference object name exists under this object
      //! Will get the default georeference if the named object does not exist
      ERRVALUE CheckGeorefName (
         RVC::OBJECTNAME& GeorefName         //!< Changed if default georef is searched for
         );

      //! Compute object scale from specified or default georeference.
      //! If ObjGeoref is not attached the default georeference will be used and returned.
      //! @returns -1 if no scale available, 0 if no georeference, 1 if georeference, < -1 if error
      INT32 ComputeObjectScale (
         RVC::GEOREFERENCE& ObjGeoref,       //!< Georeference object used passed/returned
         double& xscale,                     //!< X scale or cellsize returned
         double& yscale,                     //!< Y scale or cellsize returned
         bool ConvertToMeters                //!< Return scale in meters per object unit
         ) const;

   #ifndef NO_DEPRECATED      
      //! Compute object scale from default georeference in meters per object unit.
      //! \deprecated Use variant specifying GEOREFERENCE and whether to convert to meters or not
      //! @returns 0 if used value in obj hdr, 1 if used georef, -1 if no scale, < -1 if error
      DEPRECATED INT32 ComputeObjectScale (
         double& xscale,                     //!< X scale or cellsize returned in meters per object unit
         double& yscale                      //!< Y scale or cellsize returned in meters per object unit
         ) const;
   #endif

      //! Compute a translation between the source (this) and the target (ObjTarget)
      //! This function will return an EBadFuncParm error if either object has an arbitrary 
      //! georeference and the other does not.
      ERRVALUE ComputeObjectTranslation (
         const RVC::GEOSPATIAL& ObjTarget,
         TRANS2D_MAPGEN& SrcToDest
         );

      //! Compute object scale from georeference
      //! Specified georeference object must be attached or an error will be returned.
      ERRVALUE ComputeScaleFromGeoref (
         const RVC::GEOREFERENCE& DftGeoref, //!< Attached georeference object to use
         double& xscale,                     //!< X scale or cellsize returned
         double& yscale,                     //!< Y scale or cellsize returned
         bool ConvertToMeters                //!< Return scale in meters per object unit
         ) const;

   #ifndef NO_DEPRECATED      
      //! Compute object scale from georeference
      //! \deprecated Use variant specifying whether to convert to meters or not
      //! Specified georeference object must be attached or an error will be returned.
      DEPRECATED ERRVALUE ComputeScaleFromGeoref (
         const RVC::GEOREFERENCE& DftGeoref, //!< Attached georeference object to use
         double& xscale,                     //!< X scale or cellsize returned in meters per object unit
         double& yscale                      //!< Y scale or cellsize returned in meters per object unit
         ) const;
   #endif

      //! Copy the "default" georeference from the source to the destination
      //! using the extents of the two objects to compute a translation for the georeference.
      //! If the Source or Dest is an RVC::IMAGE instance, the center of the cells will be used.
      //! This method assumes that the Source and Dest objects extents are valid.
      //! If no georeference exists under the Source object, an arbitrary georeference will be
      //! created under both the Source and Dest so that they match.
      ERRVALUE CopyGeorefTo (
         const RVC::GEOSPATIAL& DestObj
         );

      //! Copy the "default" georeference from the source to the destination
      //! using the supplied translation for the georeference.
      //! If no georeference exists under the Source object, an arbitrary georeference will be
      //! created under both the Source and Dest so that they match.
      ERRVALUE CopyGeorefTo (
         const RVC::GEOSPATIAL& DestObj,
         const TRANS2D_AFFINE& SrcToDest
         );

      //! Copy the "default" georeference from the source to the destination
      //! using the supplied translation for the georeference.
      //! If no georeference exists under the Source object, an arbitrary georeference will be
      //! created under both the Source and Dest so that they match.
      ERRVALUE CopyGeorefTo (
         const RVC::GEOSPATIAL& DestObj,
         const TRANS2D_MAPGEN& SrcToDest
         );

      //! Determine if the capability requested is supported by the object.  The object could be a RVC object or a link to another file
      //! Only one capability at a time can be queried using the method.
      //! @return 'True' if the object supports the capability, 'false' if not
      bool HasCapability (
         int Capability                      //!< CAPABILITY enums from this and derived classes
         ) const;
         
      //! Determine if georeference is valid, if not, get default georeference.
      //! If a georeference is found, it will be read into 'GeorefObj' and method will return TRUE.
      //! If not found, 'GeorefObj' will be set up with an arbitrary georeference and will return FALSE.
      //! @return TRUE if found existing object, FALSE if not, < 0 if error.
      int GetDefaultGeoref (
         RVC::GEOREFERENCE& GeorefObj        //!< Georeference object to check
         ) const;
         
      //! Obtain extents of derived class in rvc object coordinates
      void GetExtents (
         DRECT3D& extents                    //!< Extents of rvc object RETURNED
         ) const { v_GetExtents(extents); }

      //! Obtain a geospatial type beased on the rvc object type.
      //! @returns Pointer to created RVCGEOSPATIAL type (Vector, CAD, Raster, ...) that "obj" refers to, 0 if invalid rvc object
      static RVC::GEOSPATIAL* GetGeospatial (
         const RVC::OBJECT& obj              //!< Base rvc object instance to create derived rvc class object from
         );

      //! Obtain a geospatial type beased on the rvc object type.
      //! @returns Pointer to created RVCGEOSPATIAL type (Vector, CAD, Raster, ...) that "obj" refers to, 0 if invalid rvc object
      static RVC::GEOSPATIAL* GetGeospatial (
         const RVC::OBJITEM& ObjItem         //!< Base RVC::OBJITEM instance to create derived rvc class object from
         );

      //! Get the region defined by the georeference parameter
      ERRVALUE GetObjectMapRegion (
         RVC::GEOREFERENCE& GeorefObj,       //!< If not attached, it will look for the default georeference
         REGION2D& region,                   //!< The region to fill in, its Coordinate Reference System will be set
         OBJECTREGIONFLAGS flags = OBJECTREGION_Default
         ) const;

      //! Get the region defined by this object
      ERRVALUE GetObjectRegion (
         RVC::GEOREFERENCE& GeorefObj,       //!< If not attached, it will look for the default georeference
         REGION2D& region,                   //!< The region to fill in, its Coordinate Reference System will be set if the georeference is IMPLIED
         TRANS2D_MAPGEN& ObjectToMap,        //!< Setup input side as object to map transformation
         OBJECTREGIONFLAGS flags = OBJECTREGION_Default
         ) const;

      //! Get correct OBJTYPESET for all geospatial OBJTYPE's
      //! @return OBJTYPESET for all geospatial OBJTYPE's
      static RVC::OBJTYPESET GetObjTypeSet (
         );
         
      //! Determine derived rvc class object x and y scale values
      void GetScale (
         double& xscale,                     //!< X scale of object RETURNED
         double& yscale                      //!< Y scale of object RETURNED
         ) const { v_GetScale(xscale, yscale); }

      //! Determine derived rvc class object z offset value
      //! @return Object Z offset value
      double GetZOffset (
         ) const { return (v_GetZOffset()); }
         
      //! Determine derived rvc class object z scale value
      //! @return Object Z scale value
      double GetZScale (
         ) const { return (v_GetZScale()); }

      //! Determine if the object type is a geospatial object        
      static bool IsGeospatial (
         RVC::OBJTYPE ObjType
         );

      //! Set object scale
      ERRVALUE SetObjectScale (
         double xscale,                      //!< X scale to set in object
         double yscale,                      //!< Y scale to set in object
         bool onlyifzero                     //!< Set if only zero?
         );

      //! Set object scale from georeference
      ERRVALUE SetScaleFromGeoref (
         RVC::GEOREFERENCE& GeorefObj,
         bool onlyifzero
         );

      //! Set object Z offset
      void SetZOffset (
         double zoffset
         ) { v_SetZOffset(zoffset); }
         
      //! Set object Z value
      void SetZScale (
         double zscale
         ) { v_SetZScale(zscale); }
         
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      virtual void v_GetExtents (DRECT3D& extents) const = 0;
      virtual void v_GetScale (double& xscale, double& yscale) const = 0;
      virtual double v_GetZScale () const = 0;
      virtual double v_GetZOffset () const = 0;
      virtual bool v_HasCapability (int Capability) const = 0;
      virtual void v_SetZScale (double zscale) = 0;
      virtual void v_SetZOffset (double zoffset) = 0;
      virtual void v_SetScale (double xscale, double yscale) = 0;
      #endif // GENERATING_DOXYGEN_OUTPUT

   };

DEFINE_ENUM_OP_BITWISE(GEOSPATIAL::MAKELINKFLAGS);
DEFINE_ENUM_OP_BITWISE(GEOSPATIAL::OBJECTREGIONFLAGS);

//! Geospatial object selection filter to disallow selection of non geospatial objects
class GEOSPATIAL::GETOBJFILTER_ISSELECTABLE : public GETOBJFILTER {
   public:
      GETOBJFILTER_ISSELECTABLE () {}
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      virtual bool v_IsSelectable (const RVC::OBJITEM& ObjItem, int position);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };
   
//! Geospatial object selection filter to allow selection of objects that overlap by extents the initial object
class GEOSPATIAL::GETOBJFILTER_ISOVERLAPPING : public GETOBJFILTER {
   public:
      GETOBJFILTER_ISOVERLAPPING (
         const RVC::OBJITEM& SrcObjItem
         ) : m_SrcObjItem(SrcObjItem) {}
         
      virtual ~GETOBJFILTER_ISOVERLAPPING () {}
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      const OBJITEM& m_SrcObjItem;
      TRANS2D_MAPGEN m_SrcToSelect;
      DRECT3D m_SrcExtents;
      bool m_SrcArb;
      
      virtual bool v_IsSelectable (const RVC::OBJITEM& ObjItem, int position);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };
   
//! Geospatial object selection filter to disallow selection of non-georeferenced geospatial objects
class GEOSPATIAL::GETOBJFILTER_HASGEOREFERENCE : public GETOBJFILTER {
   public:
      GETOBJFILTER_HASGEOREFERENCE () {}
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      virtual bool v_IsSelectable (const RVC::OBJITEM& ObjItem, int position);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };
   
//! Geospatial object selection filter to disallow selection of already georeferenced geospatial objects
class GEOSPATIAL::GETOBJFILTER_HASNOGEOREFERENCE : public GETOBJFILTER {
   public:
      GETOBJFILTER_HASNOGEOREFERENCE () {}
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      virtual bool v_IsSelectable (const RVC::OBJITEM& ObjItem, int position);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };
   
}     //! End of RVC namespace

#endif      //!< INC_RVC_GEOSPATL_H

---