[mapguide-commits] r10190 - in branches/4.0/MgDev/Common/Geometry: . CoordinateSystem
svn_mapguide at osgeo.org
svn_mapguide at osgeo.org
Thu Sep 11 04:19:40 PDT 2025
Author: jng
Date: 2025-09-11 04:19:39 -0700 (Thu, 11 Sep 2025)
New Revision: 10190
Modified:
branches/4.0/MgDev/Common/Geometry/ArcSegment.h
branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystem.h
branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemCategory.h
branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEllipsoid.h
branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnum.h
branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnumInteger32.h
branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemProjectionInformation.h
Log:
API doc sweep on parts of MgCoordinateSystem API
Modified: branches/4.0/MgDev/Common/Geometry/ArcSegment.h
===================================================================
--- branches/4.0/MgDev/Common/Geometry/ArcSegment.h 2025-09-11 09:19:39 UTC (rev 10189)
+++ branches/4.0/MgDev/Common/Geometry/ArcSegment.h 2025-09-11 11:19:39 UTC (rev 10190)
@@ -168,6 +168,10 @@
///
virtual bool IsClosed();
+ ///////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a copy of this instance
+ ///
/// <!-- Syntax in .Net, Java, and PHP -->
/// \htmlinclude DotNetSyntaxTop.html
/// virtual MgGeometricEntity Copy();
Modified: branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystem.h
===================================================================
--- branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystem.h 2025-09-11 09:19:39 UTC (rev 10189)
+++ branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystem.h 2025-09-11 11:19:39 UTC (rev 10190)
@@ -27,6 +27,11 @@
/// \defgroup MgCoordinateSystem MgCoordinateSystem
/// \ingroup Coordinate_System_classes
/// \{
+
+///////////////////////////////////////////////////////////////////////////////////////////////
+/// \brief
+/// Represents a coordinate system definition
+///
class MgCoordinateSystem : public MgGuardDisposable
{
DECLARE_CLASSNAME(MgCoordinateSystem)
@@ -475,7 +480,39 @@
/// true if this coordinate system is a valid one. false otherwise
///
virtual bool IsValid()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets whether the def is usable in the context of the given catalog.The
+ /// IsValid() function, above, simply checks the def for internal validity in
+ /// its own right. This function, on the other hand, checks for other
+ /// conditions such as unresolved references and so forth which can only be
+ /// evaluated in a larger context. For example, a coordinate system definition
+ /// may specify that it uses datum "FOO", which is a perfectly legitimate datum
+ /// name, so IsValid() would return true; but unless there is in fact a datum
+ /// "FOO" present in the catalog where we try to use the coordinate system, it
+ /// can't be used and IsUsable() would return false. Note that this function
+ /// will always return false if IsValid() returns false.
+ ///
+ /// \param pCatalog (MgCoordinateSystemCatalog)
+ /// The coordinate system catalog
+ ///
+ /// \return
+ /// true if this coordinate system is a valid one. false otherwise
+ ///
virtual bool IsUsable(MgCoordinateSystemCatalog *pCatalog)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Checks whether the specified def is the "same" as this one.
+ /// (Key name is ignored for purposes of comparison.)
+ ///
+ /// \param pDef (MgGuardDisposable)
+ /// The coordinate system to compare with
+ ///
+ /// \return
+ /// true if this coordinate system is the same. false otherwise
+ ///
virtual bool IsSameAs(MgGuardDisposable *pDef)=0;
///////////////////////////////////////////////////////////////////////////////////////////////
@@ -567,7 +604,29 @@
/// true if this coordinate system is protected. false otherwise
///
virtual bool IsProtected()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the age of the item, in days since last modification, if it's a
+ /// user-defined item (i.e., isn't marked as protected). If it's read-only,
+ /// then returns -1.
+ ///
+ /// \return
+ /// The age of this coordinate system
+ ///
virtual INT16 GetAge()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets whether this item is protected or not. When protected,
+ /// methods which attempt to modify the object will
+ /// throw an exception MgCoordinateSystemProtectedException
+ /// (Except for SetProtectMode and SetEncryptMode,
+ /// which can be called even on protected objects.)
+ ///
+ /// \param bIsProtected (boolean/bool)
+ /// The protection flag
+ ///
virtual void SetProtectMode(bool bIsProtected)=0;
///////////////////////////////////////////////////////////////////////////////////////////////
@@ -578,7 +637,23 @@
/// true if this coordinate system is encrypted. false otherwise
///
virtual bool IsEncrypted()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets whether this item is encrypted or not.
+ ///
+ /// \param bIsProtected (boolean/bool)
+ /// The encryption flag
+ ///
virtual void SetEncryptMode(bool bIsEncrypted)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the list of error codes listing all the things wrong with this coordinate system
+ ///
+ /// \return
+ /// The list of error codes
+ ///
virtual MgCoordinateSystemEnumInteger32* GetErrors()=0;
///////////////////////////////////////////////////////////////////////////////////////////////
@@ -818,8 +893,41 @@
/// The map scale
///
virtual void SetMapScale(double dMapScale)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the "zero limits" of the coordinate system. Absolute values of X
+ /// and Y which are smaller than this will be converted to hard zeroes.
+ /// (This is to prevent values like 1.23E-11, which are generally undesirable.)
+ ///
+ /// \return
+ /// The zero limit of this coordinate system
+ ///
virtual double GetZeroX()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the "zero limits" of the coordinate system. Absolute values of X
+ /// and Y which are smaller than this will be converted to hard zeroes.
+ /// (This is to prevent values like 1.23E-11, which are generally undesirable.)
+ ///
+ /// \return
+ /// The zero limit of this coordinate system
+ ///
virtual double GetZeroY()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the "zero limits" of the coordinate system. Absolute values of X
+ /// and Y which are smaller than this will be converted to hard zeroes.
+ /// Passing in values of zero or less will disable this feature.
+ ///
+ /// \param dXZero (double)
+ /// The X zero limit
+ ///
+ /// \param dYZero (double)
+ /// The Y zero limit
+ ///
virtual void SetZeroes(double dXZero, double dYZero)=0;
@@ -1093,9 +1201,74 @@
///
virtual MgCoordinate* ConvertFromLonLat(double dLongitude, double dLatitude, double dZ)=0;
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the convergence angle, in degrees east of north, of the
+ /// coordinate system at the specified longitude/latitude point.
+ /// Throws an exception MgCoordinateSystemNotReadyException
+ /// if the coordinate system has not been
+ /// successfully initialized; InvalidArgument of the
+ /// specified coordinate is not mathematically valid.
+ ///
+ /// \param dLongitude (double)
+ /// The longitude coordinate
+ /// \param dLatitude (double)
+ /// The latitude coordinate
+ ///
+ /// \return
+ /// The convergence angle
+ ///
virtual double GetConvergence(double dLongitude, double dLatitude)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the grid scale of the coordinate system at the specified
+ /// longitude/latitude point.
+ /// Throws an exception MgCoordinateSystemNotReadyException if the
+ /// coordinate system has not been successfully initialized;
+ /// InvalidArgument of the specified coordinate is not
+ /// mathematically valid.
+ ///
+ /// \param dLongitude (double)
+ /// The longitude coordinate
+ /// \param dLatitude (double)
+ /// The latitude coordinate
+ ///
+ /// \return
+ /// The grid scale
+ ///
virtual double GetScale(double dLongitude, double dLatitude)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the grid scale along meridians of the coordinate system at
+ /// the specified longitude/latitude point.
+ ///
+ /// \param dLongitude (double)
+ /// The longitude coordinate
+ /// \param dLatitude (double)
+ /// The latitude coordinate
+ ///
+ /// \return
+ /// The grid scale along meridians of the coordinate system at
+ /// the specified longitude/latitude point.
+ ///
virtual double GetScaleH(double dLongitude, double dLatitude)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the grid scale along parallels of the coordinate system at
+ /// the specified longitude/latitude point.
+ ///
+ /// \param dLongitude (double)
+ /// The longitude coordinate
+ /// \param dLatitude (double)
+ /// The latitude coordinate
+ ///
+ /// \return
+ /// The grid scale along parallels of the coordinate system at
+ /// the specified longitude/latitude point.
+ ///
virtual double GetScaleK(double dLongitude, double dLatitude)=0;
///////////////////////////////////////////////////////////////////////////////////////////////
Modified: branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemCategory.h
===================================================================
--- branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemCategory.h 2025-09-11 09:19:39 UTC (rev 10189)
+++ branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemCategory.h 2025-09-11 11:19:39 UTC (rev 10190)
@@ -66,7 +66,44 @@
/// true if this category is valid
///
virtual bool IsValid()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets whether the def is usable in the context of the given catalog.
+ /// The IsValid() function, above, simply checks the def for internal
+ /// validity in its own right. This function, on the other hand,
+ /// checks for other conditions such as unresolved references and so
+ /// forth which can only be evaluated in a larger context. For
+ /// example, a coordinate system definition may specify that it uses
+ /// datum "FOO", which is a perfectly legitimate datum name, so
+ /// IsValid() would return true; but unless there is in fact a datum
+ /// "FOO" present in the catalog where we try to use the coordinate
+ /// system, it can't be used and IsUsable() would return false.
+ /// Note that this function will always return false if IsValid()
+ /// returns false.
+ ///
+ /// In the specific case of a category definition, it has no dependencies
+ /// on anything other than itself, so IsUsable() simply returns the
+ /// result of IsValid(). (The catalog will not attempt to make sure
+ /// that the coordinate systems listed in the category are in fact
+ /// present in the catalog.)
+ ///
+ /// \return
+ /// true if this category is usable
+ ///
virtual bool IsUsable(MgCoordinateSystemCatalog *pCatalog)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Compares the def with another and returns true if they're the
+ /// "same," false otherwise. The comparison does not consider the name
+ /// (i.e., two defs which have different key names but are otherwise
+ /// identical will return true), but does consider everything else. If
+ /// the two defs are not of the same type, returns false.
+ ///
+ /// \return
+ /// true if this category is the same
+ ///
virtual bool IsSameAs(MgGuardDisposable *pDef)=0;
///////////////////////////////////////////////////////////////////////////////////////////////
@@ -95,7 +132,29 @@
/// The coordinate system enumerator
///
virtual MgCoordinateSystemEnum* GetEnum()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Adds the specified coordinate system key name to the category.
+ /// Throws an exception MgInvalidArgumentException (if the specified string is not a legal
+ /// coordinate system key name) or MgCoordinateSystemCategoryDuplicateException (if the specified
+ /// coordinate system name already exists in the category).
+ ///
+ /// \param sName (String/string)
+ /// The coordinate system key name
+ ///
virtual void AddCoordinateSystem(CREFSTRING sName)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Removes the specified coordinate system key name from the category.
+ /// Throws an exception MgInvalidArgumentException (if the specified string is not a legal
+ /// coordinate system key name) or throws if there is no such
+ /// coordinate system name in the category.
+ ///
+ /// \param sName (String/string)
+ /// The coordinate system key name
+ ///
virtual void RemoveCoordinateSystem(CREFSTRING sName)=0;
///////////////////////////////////////////////////////////////////////////////////////////////
@@ -109,6 +168,11 @@
/// true if the specified name exists. false otherwise
///
virtual bool HasCoordinateSystem(CREFSTRING sName)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Clears the object to a freshly constructed state.
+ ///
virtual void Clear()=0;
///////////////////////////////////////////////////////////////////////////////////////////////
Modified: branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEllipsoid.h
===================================================================
--- branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEllipsoid.h 2025-09-11 09:19:39 UTC (rev 10189)
+++ branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEllipsoid.h 2025-09-11 11:19:39 UTC (rev 10190)
@@ -60,45 +60,448 @@
/// This method used to be called IsLegalCode prior to MapGuide Open Source 2.2 / MapGuide Enterprise 2011 / AutoCAD Map3D 2011
///
virtual bool IsLegalElCode(CREFSTRING sCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets whether the def is "valid." Validity, in this case, is defined in
+ /// terms of whether a catalog will accept this def when attempting to add it.
+ ///
+ /// \return
+ /// true if valid
+ ///
virtual bool IsValid()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets whether the def is usable in the context of the given catalog.
+ /// The IsValid() function, above, simply checks the def for internal
+ /// validity in its own right. This function, on the other hand, checks
+ /// for other conditions such as unresolved references and so forth which
+ /// can only be evaluated in a larger context. For example, a coordinate
+ /// system definition may specify that it uses datum "FOO", which is a
+ /// perfectly legitimate datum name, so IsValid() would return true; but
+ /// unless there is in fact a datum "FOO" present in the catalog where we
+ /// try to use the coordinate system, it can't be used and IsUsable() would
+ /// return false. Note that this function will always return false if
+ /// IsValid() returns false.
+ ///
+ /// In the specific case of an ellipsoid, we're not referencing anything,
+ /// so there are no checks to do here. We'll simply return whether the
+ /// ellipsoid itself is valid.
+ ///
+ /// \return
+ /// true if usable
+ ///
virtual bool IsUsable()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Checks whether the specified def is the "same" as this one.
+ /// (Key name is ignored for purposes of comparison.)
+ ///
+ /// \return
+ /// true if same
+ ///
virtual bool IsSameAs(MgGuardDisposable *pDef)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Makes a copy of this object and returns it to the caller.
+ ///
+ /// \return
+ /// The cloned instance
+ ///
virtual MgCoordinateSystemEllipsoid* CreateClone()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Get the description of the ellipsoid definition
+ ///
+ /// \return
+ /// The description
+ ///
virtual STRING GetDescription()=0; /// __get
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the description of the ellipsoid definition
+ ///
+ /// \param sDesc (String/string)
+ /// The description
+ ///
virtual void SetDescription(CREFSTRING sDesc)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified string is a legal description.
+ ///
+ /// \param sDesc (String/string)
+ /// The description
+ ///
+ /// \return
+ /// true if legal
+ ///
virtual bool IsLegalDescription(CREFSTRING sDesc)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the group of the def (provided by Mentor for grouping purposes; not
+ /// currently used by any Autodesk GIS products, although that could change in
+ /// the future).
+ ///
+ /// \return
+ /// The group
+ ///
virtual STRING GetGroup()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the group of the ellipsoid.
+ ///
+ /// \param sGroup (String/string)
+ /// The group
+ ///
virtual void SetGroup(CREFSTRING sGroup)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified string is a legal group string.
+ ///
+ /// \param sGroup (String/string)
+ /// The group
+ ///
+ /// \return
+ /// true if legal
+ ///
virtual bool IsLegalGroup(CREFSTRING sGroup)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Get the source of the ellipsoid definition.
+ ///
+ /// \return
+ /// The source
+ ///
virtual STRING GetSource()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the source of the ellipsoid.
+ ///
+ /// \param sSource (String/string)
+ /// The source
+ ///
virtual void SetSource(CREFSTRING sSource)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Get the EPSG code
+ ///
+ /// \return
+ /// The EPSG code
+ ///
/// \since 2.3
+ ///
virtual INT16 GetEpsgCode()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the EPSG code
+ ///
+ /// \param epsgCode (int)
+ /// The EPSG code
+ ///
virtual void SetEpsgCode(INT16 epsgCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified string is a legal source string
+ ///
+ /// \param sSource (String/string)
+ /// The source
+ ///
+ /// \return
+ /// true if legal
+ ///
virtual bool IsLegalSource(CREFSTRING sSource)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets whether the item is protected or not. "Read-only" items are defined
+ /// as having their protect flag set to 1.
+ ///
+ /// \return
+ /// true if protected
+ ///
virtual bool IsProtected()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the age of the item, in days since last modification, if it's a
+ /// user-defined item (i.e., isn't marked as protected). If it's read-only,
+ /// then returns -1.
+ ///
+ /// \return
+ /// the age
+ ///
virtual INT16 GetAge()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets whether this item is protected or not. When protected,
+ /// methods which attempt to modify the object will
+ /// throw an exception (Except for SetProtectMode and SetEncryptMode,
+ /// which can be called even on protected objects.)
+ ///
+ /// \param bIsProtected (boolean/bool)
+ /// The protection flag
+ ///
virtual void SetProtectMode(bool bIsProtected)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether this item is encrypted or not. The only effect
+ /// of its "encrypted" state is how it behaves when persisted to or
+ /// from a stream.
+ ///
+ /// \return
+ /// true if encrypted
+ ///
virtual bool IsEncrypted()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets whether this item is encrypted or not.
+ ///
+ /// \param bIsEncrypted (boolean/bool)
+ /// The encryption flag
+ ///
virtual void SetEncryptMode(bool bIsEncrypted)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the equatorial radius of the ellipsoid definition.
+ ///
+ /// \return
+ /// The equatorial radius
+ ///
virtual double GetEquatorialRadius()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the polar radius of the ellipsoid definition.
+ ///
+ /// \return
+ /// The polar radius
+ ///
virtual double GetPolarRadius()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the flattening ratio of the ellipsoid definition.
+ ///
+ /// \return
+ /// The flattening ratio
+ ///
virtual double GetFlatteningRatio()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the eccentricity of the ellipsoid definition.
+ ///
+ /// \return
+ /// The eccentricity
+ ///
virtual double GetEccentricity()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Sets the radii, in meters, of the ellipsoid.
+ /// Throws an exception if the numbers provided are not mathematically
+ /// valid. (Flattening and eccentricity will automatically be
+ /// calculated from the provided radii.)
+ ///
+ /// \param dEquatorialRadius (double)
+ /// The equatiorial radius
+ ///
+ /// \param dPolarRadius (double)
+ /// The polar radius
+ ///
virtual void SetRadii(double dEquatorialRadius, double dPolarRadius)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Utility function which calculates an eccentricity from the given
+ /// flattening ratio.
+ ///
+ /// \return
+ /// The eccentricity
+ ///
virtual double FlatteningRatioToEccentricity(double dFlat)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Utility function which calculates a flattening ratio from the
+ /// given eccentricity.
+ ///
+ /// \return
+ /// The flattening ratio
+ ///
virtual double EccentricityToFlatteningRatio(double dEccent)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Utility function which calculates an equatorial radius from the given
+ /// polar radius and flattening ratio.
+ ///
+ /// \param dPolarRadius (double)
+ /// The polar radius
+ ///
+ /// \param dFlatteningRatio (double)
+ /// The flattening ratio
+ ///
virtual double EquatorialRadiusFromPolarRadiusFlatteningRatio(double dPolarRadius, double dFlatteningRatio)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Utility function which calculates a polar radius from the given equatorial
+ /// radius and flattening ratio
+ ///
+ /// \param dEquatorialRadius (double)
+ /// The equatorial radius
+ ///
+ /// \param dFlatteningRatio (double)
+ /// The flattening ratio
+ ///
+ /// \return
+ /// The polar radius
+ ///
virtual double PolarRadiusFromEquatorialRadiusFlatteningRatio(double dEquatorialRadius, double dFlatteningRatio)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Calculates the great circle distance between two points on the ellipsoid surface
+ ///
+ /// \param dLongitude1 (double)
+ /// The longitude of the first point in radians
+ ///
+ /// \param dLatitude1 (double)
+ /// The latitude of the first point in radians
+ ///
+ /// \param dLongitude2 (double)
+ /// The longitude of the second point in radians
+ ///
+ /// \param dLatitude2 (double)
+ /// The latitude of the second point in radians
+ ///
+ /// \return
+ /// The great circle distance in meters
+ ///
virtual double GetGreatCircleDistance(double dLongitude1, double dLatitude1, double dLongitude2, double dLatitude2)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Calculates the great circle azimuth between two points on the ellipsoid surface
+ ///
+ /// \param dLongitude1 (double)
+ /// The longitude of the first point in radians
+ ///
+ /// \param dLatitude1 (double)
+ /// The latitude of the first point in radians
+ ///
+ /// \param dLongitude2 (double)
+ /// The longitude of the second point in radians
+ ///
+ /// \param dLatitude2 (double)
+ /// The latitude of the second point in radians
+ ///
+ /// \return
+ /// The great circle azimuth in radians
+ ///
virtual double GetGreatCircleAzimuth(double dLongitude1, double dLatitude1, double dLongitude2, double dLatitude2)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the minimum allowed radius value for this ellipsoid
+ ///
+ /// \return
+ /// The minimum radius value in meters
+ ///
virtual double GetRadiusMin()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the maximum allowed radius value for this ellipsoid
+ ///
+ /// \return
+ /// The maximum radius value in meters
+ ///
virtual double GetRadiusMax()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Checks if the given radius value is valid for this ellipsoid
+ ///
+ /// \param dRadius (double)
+ /// The radius to check
+ ///
+ /// \return
+ /// true if the radius is valid, false otherwise
+ ///
virtual bool IsLegalRadius(double dRadius)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the minimum allowed flattening ratio for this ellipsoid
+ ///
+ /// \return
+ /// The minimum flattening ratio
+ ///
virtual double GetFlatteningRatioMin()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the maximum allowed flattening ratio for this ellipsoid
+ ///
+ /// \return
+ /// The maximum flattening ratio
+ ///
virtual double GetFlatteningRatioMax()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Checks if the given flattening ratio is valid for this ellipsoid
+ ///
+ /// \param dFlat (double)
+ /// The flattening ratio to check
+ ///
+ /// \return
+ /// true if the flattening ratio is valid, false otherwise
+ ///
virtual bool IsLegalFlatteningRatio(double dFlat)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Calculates the flattening ratio from the given equatorial and polar radii
+ ///
+ /// \param dEquatorialRadius (double)
+ /// The equatorial radius
+ ///
+ /// \param dPolarRadius (double)
+ /// The polar radius
+ ///
+ /// \return
+ /// The flattening ratio
+ ///
virtual double FlatteningRatioFromRadii(double dEquatorialRadius, double dPolarRadius)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the coordinate system catalog that contains this ellipsoid
+ ///
+ /// \return
+ /// The coordinate system catalog
+ ///
virtual MgCoordinateSystemCatalog* GetCatalog()=0;
INTERNAL_API:
Modified: branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnum.h
===================================================================
--- branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnum.h 2025-09-11 09:19:39 UTC (rev 10189)
+++ branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnum.h 2025-09-11 11:19:39 UTC (rev 10190)
@@ -23,12 +23,76 @@
DECLARE_CLASSNAME(MgCoordinateSystemEnum)
PUBLISHED_API:
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Reads the next set of entries from the parent dictionary
+ ///
+ /// \param ulCount (UINT32)
+ /// The number of entries to read
+ ///
+ /// \return
+ /// Collection of coordinate system definitions
+ ///
virtual MgDisposableCollection* Next(UINT32 ulCount)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Skips the next ulSkipCount names in the enumeration
+ ///
+ /// \param ulSkipCount (UINT32)
+ /// The number of items to skip
+ ///
+ /// \remarks
+ /// Throws an exception if ulSkipCount items could not be skipped
+ ///
virtual void Skip(UINT32 ulSkipCount)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Resets the enumerator to the start of the collection
+ ///
virtual void Reset()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a copy of the enumerator with the same enumeration state
+ ///
+ /// \return
+ /// A clone of the current enumerator
+ ///
virtual MgCoordinateSystemEnum* CreateClone()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Adds a filter to the enumeration
+ ///
+ /// \param pFilter (MgCoordinateSystemFilter)
+ /// The filter to add
+ ///
virtual void AddFilter(MgCoordinateSystemFilter *pFilter)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Fetches the names of the next set of items
+ ///
+ /// \param ulCount (UINT32)
+ /// The number of names to retrieve
+ ///
+ /// \return
+ /// Collection of coordinate system names
+ ///
virtual MgStringCollection* NextName(UINT32 ulCount)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Fetches the descriptions of the next set of items
+ ///
+ /// \param ulCount (UINT32)
+ /// The number of descriptions to retrieve
+ ///
+ /// \return
+ /// Collection of coordinate system descriptions
+ ///
virtual MgStringCollection* NextDescription(UINT32 ulCount)=0;
protected:
Modified: branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnumInteger32.h
===================================================================
--- branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnumInteger32.h 2025-09-11 09:19:39 UTC (rev 10189)
+++ branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemEnumInteger32.h 2025-09-11 11:19:39 UTC (rev 10190)
@@ -24,11 +24,52 @@
DECLARE_CLASSNAME(MgCoordinateSystemEnumInteger32)
PUBLISHED_API:
-// virtual MgIntCollection* Next(UINT32 ulCount)=0;
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the next set of values from the enumeration as strings
+ ///
+ /// \param ulCount (UINT32)
+ /// The number of values to retrieve
+ ///
+ /// \return
+ /// Collection of string representations of the values
+ ///
virtual MgStringCollection* Next(UINT32 ulCount)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Skips the next ulSkipCount values in the enumeration
+ ///
+ /// \param ulSkipCount (UINT32)
+ /// The number of items to skip
+ ///
+ /// \remarks
+ /// Throws an exception if ulSkipCount items could not be skipped
+ ///
virtual void Skip(UINT32 ulSkipCount)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Resets the enumerator to the start of the collection
+ ///
virtual void Reset()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Creates a copy of the enumerator with the same enumeration state
+ ///
+ /// \return
+ /// A clone of the current enumerator
+ ///
virtual MgCoordinateSystemEnumInteger32* CreateClone()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Adds a filter to the enumeration
+ ///
+ /// \param pFilter (MgCoordinateSystemFilterInteger32)
+ /// The filter to add
+ ///
virtual void AddFilter(MgCoordinateSystemFilterInteger32 *pFilter)=0;
protected:
Modified: branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemProjectionInformation.h
===================================================================
--- branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemProjectionInformation.h 2025-09-11 09:19:39 UTC (rev 10189)
+++ branches/4.0/MgDev/Common/Geometry/CoordinateSystem/CoordinateSystemProjectionInformation.h 2025-09-11 11:19:39 UTC (rev 10190)
@@ -27,21 +27,255 @@
DECLARE_CLASSNAME(MgCoordinateSystemProjectionInformation)
PUBLISHED_API:
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets an enumerator for listing all the projections supported by the API
+ ///
+ /// \return
+ /// Enumerator containing all supported projection codes
+ /// Caller is responsible for releasing the enumerator when done with it
+ ///
virtual MgCoordinateSystemEnumInteger32* GetEnumProjections()=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns the number of parameters the specified projection is using
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code to check
+ ///
+ /// \return
+ /// Number of parameters in the range 1-24 (corresponding to prj_prm1 through prj_prm24)
+ ///
virtual INT32 GetParameterCount(INT32 nProjectionCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified projection uses the given parameter index
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code to check
+ ///
+ /// \param ulIndex (UINT32)
+ /// The parameter index (1-24, corresponding to prj_prm1 through prj_prm24)
+ ///
+ /// \return
+ /// true if the projection uses this parameter, false otherwise
+ ///
virtual bool IsUsingParameter(INT32 nProjectionCode, UINT32 ulIndex)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified projection uses the "origin longitude" attribute
+ /// (corresponding to cs_Csdef_'s org_lng member)
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code to check
+ ///
+ /// \return
+ /// true if the projection uses origin longitude, false otherwise
+ ///
virtual bool IsUsingOriginLongitude(INT32 nProjectionCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified projection uses the "origin latitude" attribute
+ /// (corresponding to cs_Csdef_'s org_lat member)
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code to check
+ ///
+ /// \return
+ /// true if the projection uses origin latitude, false otherwise
+ ///
virtual bool IsUsingOriginLatitude(INT32 nProjectionCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified projection uses the "scale reduction" attribute
+ /// (corresponding to cs_Csdef_'s scl_red member)
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code to check
+ ///
+ /// \return
+ /// true if the projection uses scale reduction, false otherwise
+ ///
virtual bool IsUsingScaleReduction(INT32 nProjectionCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified projection uses the "quadrant" attribute
+ /// (corresponding to cs_Csdef_'s quad member)
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code to check
+ ///
+ /// \return
+ /// true if the projection uses quadrant, false otherwise
+ ///
virtual bool IsUsingQuadrant(INT32 nProjectionCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Returns whether the specified projection uses the "offset" attribute
+ /// (corresponding to cs_Csdef_'s x_off and y_off members),
+ /// otherwise known as false northing and false easting
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code to check
+ ///
+ /// \return
+ /// true if the projection uses offset, false otherwise
+ ///
virtual bool IsUsingOffset(INT32 nProjectionCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the mathematical minimum limit of the specified parameter for the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \param ulIndex (UINT32)
+ /// The parameter index (1-24)
+ ///
+ /// \return
+ /// The minimum value allowed for this parameter
+ ///
+ /// \remarks
+ /// Throws MgCoordinateSystemMismatchException if ulIndex does not specify a parameter
+ /// which this projection uses
+ ///
virtual double GetParameterMin(INT32 nProjectionCode, UINT32 ulIndex)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the mathematical maximum limit of the specified parameter for the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \param ulIndex (UINT32)
+ /// The parameter index (1-24)
+ ///
+ /// \return
+ /// The maximum value allowed for this parameter
+ ///
+ /// \remarks
+ /// Throws MgCoordinateSystemMismatchException if ulIndex does not specify a parameter
+ /// which this projection uses
+ ///
virtual double GetParameterMax(INT32 nProjectionCode, UINT32 ulIndex)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the "reasonable default" value of the specified parameter for the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \param ulIndex (UINT32)
+ /// The parameter index (1-24)
+ ///
+ /// \return
+ /// The default value for this parameter
+ ///
+ /// \remarks
+ /// Throws MgCoordinateSystemMismatchException if ulIndex does not specify a parameter
+ /// which this projection uses
+ ///
virtual double GetParameterDefault(INT32 nProjectionCode, UINT32 ulIndex)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the logical type of the specified parameter for the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \param ulIndex (UINT32)
+ /// The parameter index (1-24)
+ ///
+ /// \return
+ /// One of the values defined in MgCoordinateSystemProjectionLogicalType
+ ///
+ /// \remarks
+ /// This information could be used to tell a UI how to format an edit box for entering values
+ /// Throws MgCoordinateSystemMismatchException if ulIndex does not specify a parameter
+ /// which this projection uses
+ ///
virtual INT32 GetParameterLogicalType(INT32 nProjectionCode, UINT32 ulIndex)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the format type of the specified parameter for the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \param ulIndex (UINT32)
+ /// The parameter index (1-24)
+ ///
+ /// \return
+ /// One of the values defined in MgCoordinateSystemProjectionFormatType
+ ///
+ /// \remarks
+ /// This information could be used to tell a UI how to format an edit box for entering values
+ /// Throws MgCoordinateSystemMismatchException if ulIndex does not specify a parameter
+ /// which this projection uses
+ ///
virtual INT32 GetParameterFormatType(INT32 nProjectionCode, UINT32 ulIndex)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the type of the specified parameter for the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \param ulIndex (UINT32)
+ /// The parameter index (1-24)
+ ///
+ /// \return
+ /// One of the values defined in MgCoordinateSystemProjectionParameterType
+ ///
+ /// \remarks
+ /// Indicates if parameter is longitude of central meridian, latitude of standard parallel, etc
+ /// This information could be used to tell a UI how to label an edit box for entering values
+ /// Throws MgCoordinateSystemMismatchException if ulIndex does not specify a parameter
+ /// which this projection uses
+ ///
virtual INT32 GetParameterType(INT32 nProjectionCode, UINT32 ulIndex)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets the unit type (linear or angular) of the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \return
+ /// kCsUnitTypeLinear if linear units
+ /// kCsUnitTypeAngular if angular units
+ /// kCsUnitTypeUnknown if invalid projection code
+ ///
virtual INT32 GetUnitType(INT32 nProjectionCode)=0;
+
+ ///////////////////////////////////////////////////////////////////////////////////////////////
+ /// \brief
+ /// Gets Mentor's "tag string" for the specified projection
+ ///
+ /// \param nProjectionCode (INT32)
+ /// The projection code
+ ///
+ /// \return
+ /// Tag string (e.g. "LL" for Lat/Long, "TM" for Transverse Mercator)
+ ///
+ /// \remarks
+ /// The returned string is not localized and should not be used for UI display
+ /// This function is provided mainly for debugging and utility purposes
+ ///
virtual STRING GetTagString(INT32 nProjectionCode)=0;
protected:
More information about the mapguide-commits
mailing list