[mapguide-commits] r5133 - in sandbox/rfc94/Common:
CoordinateSystem Geometry/CoordinateSystem
svn_mapguide at osgeo.org
svn_mapguide at osgeo.org
Thu Sep 16 09:51:48 EDT 2010
Author: baertelchen
Date: 2010-09-16 13:51:48 +0000 (Thu, 16 Sep 2010)
New Revision: 5133
Modified:
sandbox/rfc94/Common/CoordinateSystem/CoordSysGeodeticTransformDef.cpp
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticAnalyticalTransformDefParams.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticInterpolationTransformDefParams.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticMultipleRegressionTransformDefParams.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPath.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathDictionary.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathElement.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDef.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefDictionary.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefParams.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefType.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFile.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFileFormat.h
sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformation.h
Log:
Added comments to the new interfaces that came in due to RFC94.
Modified: sandbox/rfc94/Common/CoordinateSystem/CoordSysGeodeticTransformDef.cpp
===================================================================
--- sandbox/rfc94/Common/CoordinateSystem/CoordSysGeodeticTransformDef.cpp 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/CoordinateSystem/CoordSysGeodeticTransformDef.cpp 2010-09-16 13:51:48 UTC (rev 5133)
@@ -185,6 +185,9 @@
MgCoordinateSystemGeodeticTransformation* CCoordinateSystemGeodeticTransformDef::CreateTransformation(bool createInverse)
{
VERIFY_INITIALIZED(L"CCoordinateSystemGeodeticTransformDef.CreateTransformation");
+
+ if (MgCoordinateSystemGeodeticTransformDefType::None == this->GetTransformDefType() || !this->IsValid())
+ throw new MgInvalidOperationException(L"CCoordinateSystemGeodeticTransformDef.CreateTransformation", __LINE__,__WFILE__, NULL, L"", NULL);
//we don't take ownership of the transformation being returned but
//will release [sourceDatum] and [targetDatum];
@@ -218,7 +221,7 @@
MgCoordinateSystemGeodeticTransformDefParams* CCoordinateSystemGeodeticTransformDef::GetParameters()
{
- VERIFY_INITIALIZED(L"CCoordinateSystemGeodeticTransformDef.CopyTo");
+ VERIFY_INITIALIZED(L"CCoordinateSystemGeodeticTransformDef.GetParameters");
switch(this->transformationDefType)
{
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticAnalyticalTransformDefParams.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticAnalyticalTransformDefParams.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticAnalyticalTransformDefParams.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -17,6 +17,15 @@
#ifndef _MGCOORDINATESYSTEMGEODETICANALYTICALTRANSFORMDEFPARAMS_H_
#define _MGCOORDINATESYSTEMGEODETICANALYTICALTRANSFORMDEFPARAMS_H_
+/// \defgroup MgCoordinateSystemGeodeticAnalyticalTransformDefParams MgCoordinateSystemGeodeticAnalyticalTransformDefParams
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// This class holds all parameters that are specific to analytical geodetic transformation methods, e.g.
+/// geocentric transformation, molodensky etc.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticAnalyticalTransformDefParams : public MgCoordinateSystemGeodeticTransformDefParams
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticAnalyticalTransformDefParams)
@@ -71,4 +80,6 @@
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICANALYTICALTRANSFORMDEFPARAMS_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticInterpolationTransformDefParams.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticInterpolationTransformDefParams.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticInterpolationTransformDefParams.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -17,6 +17,16 @@
#ifndef _MGCOORDINATESYSTEMGEODETICINTERPOLATIONTRANSFORMDEFPARAMS_H_
#define _MGCOORDINATESYSTEMGEODETICINTERPOLATIONTRANSFORMDEFPARAMS_H_
+/// \defgroup MgCoordinateSystemGeodeticInterpolationTransformDefParams MgCoordinateSystemGeodeticInterpolationTransformDefParams
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// This class holds all parameters that are specific to grid-file based transformation. That is,
+/// where the actual datum shift value for a coordinate is determined by interpolating between grid point values
+/// as defined in the respective grid file(s).
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticInterpolationTransformDefParams : public MgCoordinateSystemGeodeticTransformDefParams
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticInterpolationTransformDefParams)
@@ -25,12 +35,62 @@
//BEGIN: struct csGeodeticXfromParmsFile
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the grid files to be used by this transformation. See the description for
+ /// gridFiles parameter.
+ ///
+ /// \param gridFiles
+ /// A (possibly empty) ordered(!) collection of MgCoordinateSystemGeodeticTransformGridFile objects.
+ /// The order of the elements contained in the collection is important, because this
+ /// instructs the underlying API in which order to use the grid files, e.g. in case of an overlap.
+ ///
+ /// \remarks
+ /// The caller is responsible for disposing the collection of grid files. That is,
+ /// this parameter object will not take ownership of the collection passed in.
virtual void SetGridFiles(MgDisposableCollection* gridFiles) = 0;
+
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns an ordered, non-live collection MgCoordinateSystemGeodeticTransformGridFile elements
+ /// currently used by this parameter object. Changing the collection does NOT
+ /// have an affect on this parent parameter instance. Instead, any API client
+ /// has to modify the collection and then set it back via SetGridFiles.
+ /// The list returned can be an empty but will never be NULL.
+ ///
+ /// \remarks
+ /// The caller is responsible for disposing the collection of grid files being returned
+ /// here.
virtual MgDisposableCollection* GetGridFiles() = 0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the name of the transformation to fallback to in case the transformation using the
+ /// defined grid files doesn't succeed.
+ ///
+ /// \return
+ /// Returns the name of the fallback transformation. Can be empty if no such fallback transformation
+ /// is defined.
+ ///
virtual STRING GetFallback() = 0;
- virtual void SetFallback(CREFSTRING) = 0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the name of the transformation to fallback to, if the transformation could not
+ /// be performed using the grid files defined.
+ ///
+ /// \param fallbackTransformation
+ /// Name of the transformation to fallback to.
+ virtual void SetFallback(CREFSTRING fallbackTransformation) = 0;
+
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a new, empty MgCoordinateSystemGeodeticTransformGridFile object
+ /// that can be added to the collection set via SetGridFiles.
+ ///
+ /// \return
+ /// Returns a new, unitialized MgCoordinateSystemGeodeticTransformGridFile instance
+ /// The caller is resonsible for disposing the object if no longer needed.
virtual MgCoordinateSystemGeodeticTransformGridFile* NewGridFile() = 0;
//END: struct csGeodeticXfromParmsFile
@@ -50,4 +110,6 @@
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICINTERPOLATIONTRANSFORMDEFPARAMS_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticMultipleRegressionTransformDefParams.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticMultipleRegressionTransformDefParams.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticMultipleRegressionTransformDefParams.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -17,6 +17,14 @@
#ifndef _MGCOORDINATESYSTEMGEODETICMULTIPLEREGRESSIONTRANSFORMDEFPARAMS_H_
#define _MGCOORDINATESYSTEMGEODETICMULTIPLEREGRESSIONTRANSFORMDEFPARAMS_H_
+/// \defgroup MgCoordinateSystemGeodeticMultipleRegressionTransformDefParams MgCoordinateSystemGeodeticMultipleRegressionTransformDefParams
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// This class holds all parameters that are specific to the multiple regression transformation method.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticMultipleRegressionTransformDefParams : public MgCoordinateSystemGeodeticTransformDefParams
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticMultipleRegressionTransformDefParams)
@@ -87,4 +95,6 @@
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICMULTIPLEREGRESSIONTRANSFORMDEFPARAMS_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPath.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPath.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPath.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -18,15 +18,17 @@
#ifndef _MGCOORDINATESYSTEMGEODETICPATH_H_
#define _MGCOORDINATESYSTEMGEODETICPATH_H_
-/// \defgroup CoordinateSystemGeodeticTransformationPath CoordinateSystemGeodeticTransformationPath
+/// \defgroup MgCoordinateSystemGeodeticPath MgCoordinateSystemGeodeticPath
/// \ingroup Coordinate_System_classes
/// \{
////////////////////////////////////////////////////////////////
/// \brief
-/// Basic functionality for the geodetic transformation path
+/// A geodetic (transformation) path allows to concatenate multiple
+/// geodetic transformations. For example, converting between 2 datums
+/// cannot be achieved by doing 1 datum shift only but requires to
+/// do 1 or more datums shifts in between.
///
-
class MG_GEOMETRY_API MgCoordinateSystemGeodeticPath : public MgGuardDisposable
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticPath)
@@ -34,6 +36,7 @@
PUBLISHED_API:
//properties
+
virtual STRING GetPathName()=0;
virtual void SetPathName(CREFSTRING)=0;
@@ -64,14 +67,62 @@
virtual INT32 GetEpsgVariant()=0;
virtual void SetEpsgVariant(INT32 epsgVariant)=0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns an ordered collection of MgCoordinateSystemGeodeticPathElement objects
+ /// that form this geodetic transformation path. See remarks.
+ ///
+ /// \return
+ /// Returns a (possibly empty) collection of MgCoordinateSystemGeodeticPathElement instances.
+ /// The caller is responsible for disposing the collection being returned.
+ ///
+ /// \remarks
+ /// Changing the collection being returned has no affect on this parent geodetic
+ /// path instance. Instead, the collection can be modified and then re-set via
+ /// SetPathElements.
virtual MgDisposableCollection* GetPathElements() = 0;
+
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the individual transformation steps that form this geodetic transformation
+ /// path.
+ ///
+ /// \remarks
+ /// The caller is responsible for disposing the collection passed in, i.e.
+ /// this geodetic path instance will not take ownership of the elements.
virtual void SetPathElements(MgDisposableCollection* pathElements) = 0;
virtual bool IsProtected() = 0;
virtual bool IsValid() = 0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a new, unitialized MgCoordinateSystemGeodeticPathElement instance.
+ /// Calling this method does not affect the underlying dictionary file.
+ /// Typically, an API client will retrieve new objects through this method
+ /// so they can be added to the collection of path elements that can be set
+ /// via SetPathElements.
+ ///
+ /// \return
+ /// Returns a new MgCoordinateSystemGeodeticPathElement instance. The caller is responsible
+ /// for disposing the object being returned.
virtual MgCoordinateSystemGeodeticPathElement* NewPathElement() = 0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a deep clone of this geodetic path. That is, the cloned object
+ /// will also have its geodetic path element information cloned.
+ ///
+ /// \return
+ /// Returns a new MgCoordinateSystemGeodeticPath object that is an exact clone
+ /// of this MgCoordinateSystemGeodeticPath instance. The caller is responsible for
+ /// disposing the object being returned.
+ ///
+ /// \remarks:
+ /// The returned MgCoordinateSystemGeodeticPath instance will have its protected flag
+ /// unset. However, all other properties like name etc will be the same. Any caller will
+ /// have to change such values before trying to write the cloned instance into
+ /// the dictionary file.
virtual MgCoordinateSystemGeodeticPath* CreateClone() = 0;
protected:
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathDictionary.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathDictionary.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathDictionary.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -18,28 +18,46 @@
#ifndef _MGCOORDINATESYSTEMGEODETICPATHDICTIONARY_H_
#define _MGCOORDINATESYSTEMGEODETICPATHDICTIONARY_H_
-/// \defgroup MgCoordinateSystemCategoryDictionary MgCoordinateSystemCategoryDictionary
+/// \defgroup MgCoordinateSystemGeodeticPathDictionary MgCoordinateSystemGeodeticPathDictionary
/// \ingroup Coordinate_System_classes
/// \{
////////////////////////////////////////////////////////////////
/// \brief
-/// Basic functionality for the ellipsoid dictionary
+/// The MgCoordinateSystemGeodeticPathDictionary provides access to all geodetic transformation path
+/// definitions as defined in the dictionary file this instance reads from / writes to.
///
-
class MG_GEOMETRY_API MgCoordinateSystemGeodeticPathDictionary : public MgCoordinateSystemDictionaryBase
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticPathDictionary)
PUBLISHED_API:
- //create new path
- virtual MgCoordinateSystemGeodeticPath* NewGeodeticPath()=0;
- //working members - this won't throw an exception in case the path doesn't exist
- virtual MgCoordinateSystemGeodeticPath* GetGeodeticPath(CREFSTRING pathName)=0;
-
- //virtual void Rename(CREFSTRING sOldName, CREFSTRING sNewName)=0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a new, empty geodetic path object that has to be filled by an API client. This
+ /// method does not create a new entry in the dictionary. The caller is responsible
+ /// for disposing the object being returned.
+ ///
+ /// \return
+ /// Return a new, in-memory geodetic path object. No content is written to disk
+ /// when this method executes.
+ ///
+ virtual MgCoordinateSystemGeodeticPath* NewGeodeticPath()=0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the geodetic path object where the name is equal to the parameter
+ /// pathName. The caller is responsible for disposing the object.
+ ///
+ /// \param pathName
+ /// The name of the geodetic path to look up in the dictionary. Must not be an empty string.
+ ///
+ /// \return
+ /// Return the geodetic path if found. Otherwise NULL.
+ ///
+ virtual MgCoordinateSystemGeodeticPath* GetGeodeticPath(CREFSTRING pathName)=0;
+
protected:
/////////////////////////////////////////////////////////////////
/// \brief
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathElement.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathElement.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticPathElement.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -12,6 +12,15 @@
#ifndef _MGCOORDINATESYSTEMGEODETICPATHELEMENT_H_
#define _MGCOORDINATESYSTEMGEODETICPATHELEMENT_H_
+/// \defgroup MgCoordinateSystemGeodeticPathElement MgCoordinateSystemGeodeticPathElement
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// A geodetic transformation path element describes a single transformation step within a series
+/// of concatenated steps that eventually form a geodetic (transformation) path.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticPathElement : public MgGuardDisposable
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticPathElement)
@@ -41,4 +50,6 @@
static const INT32 m_cls_id = CoordinateSystem_CoordinateSystemGeodeticPathElement;
};
+/// \}
+
#endif
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDef.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDef.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDef.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -17,12 +17,25 @@
#ifndef _MGCOORDINATESYSTEMGEODETICTRANSFORMDEF_H_
#define _MGCOORDINATESYSTEMGEODETICTRANSFORMDEF_H_
+/// \defgroup MgCoordinateSystemGeodeticTransformDef MgCoordinateSystemGeodeticTransformDef
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// An instance of this class describes a geodetic transformation with all its parameters
+/// as it is defined in the dictionary file. The actual transformation operation
+/// is performed by the MgCoordinateSystemGeodeticTransformation objects
+/// that's being returned by the CreateTransformation method.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticTransformDef : public MgGuardDisposable
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticTransformDef)
PUBLISHED_API:
+ //BEGIN: struct cs_GeodeticTransform_
+
virtual STRING GetTransformName() = 0;
virtual void SetTransformName(CREFSTRING name) = 0;
@@ -64,17 +77,89 @@
virtual double GetAccuracy() = 0;
virtual void SetAccuracy(double accuracy) = 0;
+
+ //END: struct cs_GeodeticTransform_
virtual bool IsProtected() = 0;
virtual bool IsValid() = 0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the type of this geodetic transformation (as defined by MgCoordinateSystemGeodeticTransformDefType).
+ /// The type defines the parameters that are being returned by the GetParameters method.
virtual INT32 GetTransformDefType() = 0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the extended parameters object valid for this transformation definition. See remarks.
+ /// Depending on the type returned by GetTransformDefType(), this method returns one of the following:
+ ///
+ /// \li NULL if this is a NULL transformation
+ /// \li MgCoordinateSystemGeodeticAnalyticalTransformDefParams if this transformation uses an anylitical transformation method
+ /// \li MgCoordinateSystemGeodeticInterpolationTransformDefParams if this transformation uses grid files
+ /// \li MgCoordinateSystemGeodeticMultipleRegressionTransformDefParams if this transformation is a multiple regression transformation type
+ ///
+ /// \return
+ /// Returns the extended parameters (or NULL) object for this transformation object. The
+ /// caller is responsible for disposing the object being returned. See remarks.
+ ///
+ /// \remarks
+ /// If a caller needs to change the parameters of a transformation, the values
+ /// have to be changed on the object being returned here and then written
+ /// back via SetParameters. Setting the values on the parameters object
+ /// has no affect on this transformation definition.
virtual MgCoordinateSystemGeodeticTransformDefParams* GetParameters() = 0;
+
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the extended parameters for this transformation.
+ ///
+ /// \param parameters
+ /// The parameters to set for this transformation. The object passed in,
+ /// has to be of the same type as it has been returned by GetParameters. Otherwise,
+ /// an exception will be thrown. This parameter can only be NULL, if this is a NONE transformation.
+ ///
+ /// \remarks
+ /// The instance passed in has to be disposed by the caller, i.e. this transformation
+ /// object will not take ownership of it.
virtual void SetParameters(MgCoordinateSystemGeodeticTransformDefParams* parameters) = 0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a deep clone of this geodetic transformation. That is, the cloned object
+ /// will also have its extended parameters cloned.
+ ///
+ /// \return
+ /// Returns a new MgCoordinateSystemGeodeticTransformDef object that is an exact clone
+ /// of this MgCoordinateSystemGeodeticTransformDef instance. The caller is responsible for
+ /// disposing the object being returned.
+ ///
+ /// \remarks
+ /// The returned MgCoordinateSystemGeodeticTransformDef instance will have its protected flag
+ /// unset. However, all other properties like name etc will be the same. Any caller will
+ /// have to change such values before trying to write the cloned instance into
+ /// the dictionary file.
virtual MgCoordinateSystemGeodeticTransformDef* CreateClone() = 0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a new MgCoordinateSystemGeodeticTransformation object that
+ /// can be used to perform the actual transformation this transformation
+ /// definition describes. This method will fail with an exception,
+ /// if this is the NONE transformation.
+ ///
+ /// \param createInverse
+ /// If true, the MgCoordinateSystemGeodeticTransformation being returned will
+ /// perform the inverse of the transformation as defined in the dictionary file. That is,
+ /// it will convert from the actual target datum to the source datum. Note, that not all
+ /// transformations are invertible. This method will fail with an exception then.
+ /// If false, this method will return a MgCoordinateSystemGeodeticTransformation
+ /// instance that performs the default forward datum transformation.
+ ///
+ /// \return
+ /// Returns the MgCoordinateSystemGeodeticTransformation that performs the actual
+ /// datum transformation as described by this definition instance. The caller
+ /// is reponsible for disposing the object being returned.
virtual MgCoordinateSystemGeodeticTransformation* CreateTransformation(bool createInverse) = 0;
protected:
@@ -91,4 +176,6 @@
static const INT32 m_cls_id = CoordinateSystem_CoordinateSystemGeodeticTransformDef;
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICTRANSFORMDEF_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefDictionary.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefDictionary.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefDictionary.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -17,16 +17,46 @@
#ifndef _MGCOORDINATESYSTEMGEODETICTRANSFORMDEFDICTIONARY_H_
#define _MGCOORDINATESYSTEMGEODETICTRANSFORMDEFDICTIONARY_H_
+
+/// \defgroup MgCoordinateSystemGeodeticTransformDefDictionary MgCoordinateSystemGeodeticTransformDefDictionary
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// The MgCoordinateSystemGeodeticTransformDefDictionary provides access to all geodetic transformation
+/// definitions as defined in the dictionary file this instance reads from / writes to.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticTransformDefDictionary : public MgCoordinateSystemDictionaryBase
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticTransformDefDictionary)
PUBLISHED_API:
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a new, empty geodetic transformation definition object that has to be filled by an API client. This
+ /// method does not create a new entry in the dictionary. The caller is responsible
+ /// for disposing the object being returned.
+ ///
+ /// \return
+ /// Return a new, in-memory geodetic transformation definition object. No content is written to disk
+ /// when this method executes.
+ ///
virtual MgCoordinateSystemGeodeticTransformDef* NewGeodeticTransformationDef(INT32 transformationDefType) = 0;
- //working members - this won't throw an exception in case the transformation doesn't exist
- virtual MgCoordinateSystemGeodeticTransformDef* GetGeodeticTransformationDef(CREFSTRING pathName)=0;
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the geodetic transformation definition object where the name is equal to the parameter
+ /// pathName. The caller is responsible for disposing the object.
+ ///
+ /// \param transformationName
+ /// The name of the geodetic transformation to look up in the dictionary. Must not be an empty string.
+ ///
+ /// \return
+ /// Return the geodetic transformation if found. Otherwise NULL.
+ ///
+ virtual MgCoordinateSystemGeodeticTransformDef* GetGeodeticTransformationDef(CREFSTRING transformationName)=0;
protected:
/////////////////////////////////////////////////////////////////
@@ -42,4 +72,6 @@
static const INT32 m_cls_id = CoordinateSystem_CoordinateSystemGeodeticTransformDefDictionary;
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICTRANSFORMDEFDICTIONARY_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefParams.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefParams.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefParams.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -17,28 +17,42 @@
#ifndef _MGCOORDINATESYSTEMGEODETICTRANSFORMDEFPARAMS_H_
#define _MGCOORDINATESYSTEMGEODETICTRANSFORMDEFPARAMS_H_
+/// \defgroup MgCoordinateSystemGeodeticTransformDefParams MgCoordinateSystemGeodeticTransformDefParams
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// Common base class for all geodetic transformation parameters.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticTransformDefParams : public MgGuardDisposable
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticTransformDefParams)
PUBLISHED_API:
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Checks, whether this transformation parameter object's content is considered (technically) valid.
+ /// That is, even if this method returns true, the transformation might still fail due to
+ /// other reasons, e.g. a grid file does not exist.
+ ///
+ /// \return
+ /// Returns true, if this parameter object is considered valid. Otherwise false.
virtual bool IsValid() = 0;
+
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Checks, whether this transformation object is protected, i.e. any attempts to change its
+ /// content will fail. All definitions contained in the dictionaries at compile time
+ /// are protected by default.
+ ///
+ /// \return
+ /// Returns true, if this parameter object is read-only. Otherwise false.
virtual bool IsProtected() = 0;
-//protected:
-// /////////////////////////////////////////////////////////////////
-// /// \brief
-// /// Get the class Id
-// ///
-// /// \return
-// /// The integer value
-// ///
-// INT32 GetClassId(){return m_cls_id;};
-//
-//CLASS_ID:
-// static const INT32 m_cls_id = CoordinateSystem_CoordinateSystemGeodeticTransformDefParams;
-
};
+/// \}
+
#endif _MGCOORDINATESYSTEMGEODETICTRANSFORMDEFPARAMS_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefType.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefType.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformDefType.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -18,15 +18,46 @@
#ifndef _MGCOORDINATESYSTEMGEODETICTRANSFORMDEFTYPE_H_
#define _MGCOORDINATESYSTEMGEODETICTRANSFORMDEFTYPE_H_
+/// \defgroup MgCoordinateSystemGeodeticTransformDefType MgCoordinateSystemGeodeticTransformDefType
+/// \ingroup Coordinate_System_classes
+/// \{
+
+///////////////////////////////////////////////////////////////
+/// \brief
+/// This class contains the constants for all current transformation definition types.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticTransformDefType
{
PUBLISHED_API:
+ ///////////////////////////////////////////////////////////////
+ /// \brief
+ /// The transformation definition describes the NONE transformation. That is, that
+ /// transformation doesn't actually perform a datum shift but is basically a NOOP.
static const INT32 None = 0;
+
+ ///////////////////////////////////////////////////////////////
+ /// \brief
+ /// The transformation definition describes an analytical transformation where
+ /// the transformation between the source and the target datum is defined
+ /// through a formular that's fed with up to 10 parameters.
static const INT32 Analytical = 1;
+
+ ///////////////////////////////////////////////////////////////
+ /// \brief
+ /// The transformation definition describes a transformation that
+ /// uses grid files to calculate the actual datum shift for a given
+ /// coordinate by interpolating between given grid points.
static const INT32 Interpolation = 2;
+
+ ///////////////////////////////////////////////////////////////
+ /// \brief
+ /// The transformation definition describes a transformation that
+ /// uses a multiple regression calculation to perform the actual datum shift.
static const INT32 MultipleRegression = 4;
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICTRANSFORMDEFTYPE_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFile.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFile.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFile.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -17,16 +17,55 @@
#ifndef _MGCOORDINATESYSTEMGEODETICTRANSFORMGRIDFILE_H_
#define _MGCOORDINATESYSTEMGEODETICTRANSFORMGRIDFILE_H_
+/// \defgroup MgCoordinateSystemGeodeticTransformGridFile MgCoordinateSystemGeodeticTransformGridFile
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// The MgCoordinateSystemGeodeticInterpolationTransformDefParams parameter class requires
+/// instances of MgCoordinateSystemGeodeticTransformGridFile to be set via its
+/// SetGridFiles method. An MgCoordinateSystemGeodeticTransformGridFile object simply describes
+/// the grid file rather than containing the (grid file) information itself.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticTransformGridFile : public MgGuardDisposable
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticTransformGridFile)
PUBLISHED_API:
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the format of the grid file as a constant value as defined in
+ /// MgCoordinateSystemGeodeticTransformGridFileFormat.
+ ///
+ /// \return
+ /// Returns the file format as an INT32 value.
virtual INT32 GetFileFormat() = 0;
+
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets this file's format. Has to be constant
+ /// as defined by MgCoordinateSystemGeodeticTransformGridFileFormat.
virtual void SetFileFormat(INT32 gridFileFormat) = 0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// When used within a geodetic transformation that defines a source and a target
+ /// datum, this flag instructs the API whether to consider the grid file's content
+ /// to be the inverse of the actual conversion direction.
+ ///
+ /// \return
+ /// Returns true, if the grid file provides information to transform between
+ /// 2 datums in the inversed direction to what's actually specified in
+ /// the parent transformation definition.
virtual bool GetIsInverseDirection() = 0;
+
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the flag, whether this grid file carries the information
+ /// to perform a datum transformation in the inversed direction
+ /// to what's specified in the parent transformation definition.
virtual void SetIsInverseDirection(bool isInverseDirection) = 0;
virtual STRING GetFileName() = 0;
@@ -50,4 +89,6 @@
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICTRANSFORMGRIDFILE_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFileFormat.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFileFormat.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformGridFileFormat.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -18,10 +18,18 @@
#ifndef _MGCOORDINATESYSTEMGEODETICTRANSFORMGRIDFILEFORMAT_H_
#define _MGCOORDINATESYSTEMGEODETICTRANSFORMGRIDFILEFORMAT_H_
+/// \defgroup MgCoordinateSystemGeodeticTransformGridFileFormat MgCoordinateSystemGeodeticTransformGridFileFormat
+/// \ingroup Coordinate_System_classes
+/// \{
+////////////////////////////////////////////////////////////////
+/// \brief
+/// This class contains the constants for all currently supported grid file formats.
+///
class MG_GEOMETRY_API MgCoordinateSystemGeodeticTransformGridFileFormat
{
PUBLISHED_API:
+
static const INT32 None = 0;
static const INT32 NTv1 = 1;
static const INT32 NTv2 = 2;
@@ -29,7 +37,8 @@
static const INT32 RGF = 4;
static const INT32 PAR = 5;
static const INT32 ATS77 = 6;
-
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICTRANSFORMGRIDFILEFORMAT_H_
\ No newline at end of file
Modified: sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformation.h
===================================================================
--- sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformation.h 2010-09-16 09:43:06 UTC (rev 5132)
+++ sandbox/rfc94/Common/Geometry/CoordinateSystem/CoordinateSystemGeodeticTransformation.h 2010-09-16 13:51:48 UTC (rev 5133)
@@ -18,6 +18,16 @@
#ifndef _MGCOORDINATESYSTEMGEODETICTRANSFORMATION_H_
#define _MGCOORDINATESYSTEMGEODETICTRANSFORMATION_H_
+/// \defgroup MgCoordinateSystemGeodeticTransformation MgCoordinateSystemGeodeticTransformation
+/// \ingroup Coordinate_System_classes
+/// \{
+
+////////////////////////////////////////////////////////////////
+/// \brief
+/// An instance of this class allow a caller do perform a geodetic transformation (datum shift).
+/// That is, this class does not operate on coordinate system level, but rather on
+/// datum level.
+///
class MgCoordinateSystemGeodeticTransformation : public MgGuardDisposable
{
DECLARE_CLASSNAME(MgCoordinateSystemGeodeticTransformation)
@@ -31,25 +41,95 @@
virtual MgCoordinate* Shift(double dLongitude, double dLatitude)=0;
virtual MgCoordinate* Shift(double dLongitude, double dLatitude, double dZ)=0;
- //TODO: Add comments - don't use the following members any more
-
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetOffsetX()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetOffsetY()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetOffsetZ()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual void SetOffset(double x, double y, double z)=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetBursaWolfeTransformRotationX()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetBursaWolfeTransformRotationY()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetBursaWolfeTransformRotationZ()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetBursaWolfeTransformBwScale()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual void SetBursaWolfeTransform(double dRotationX, double dRotationY, double dRotationZ, double dBwScale)=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual INT32 GetGeodeticTransformationMethod()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual void SetGeodeticTransformationMethod(INT32 nGeodeticTransformationMethod)=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetMaxOffset()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual bool IsLegalOffset(double dOffset)=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetMaxRotation()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual bool IsLegalRotation(double dRotation)=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetBwScaleMin()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual double GetBwScaleMax()=0;
+ ////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Obsolete. Use MgCoordinateSystemGeodeticTransformDef and
+ /// MgCoordinateSystemGeodeticTransformDefParams (plus derived classes) instead.
virtual bool IsLegalBwScale(double dBwScale)=0;
protected:
@@ -66,4 +146,6 @@
static const INT32 m_cls_id = CoordinateSystem_CoordinateSystemGeodeticTransformation;
};
+/// \}
+
#endif //_MGCOORDINATESYSTEMGEODETICTRANSFORMATION_H_
More information about the mapguide-commits
mailing list