Improve QgsCoordinateReferenceSystem documentation

This commit is contained in:
Nyall Dawson 2016-02-03 07:51:54 +11:00
parent 9e292d0cca
commit d4ea95ea49
2 changed files with 116 additions and 96 deletions

View File

@ -33,7 +33,7 @@ class QgsCoordinateReferenceSystem
/** Use this constructor when you want to create a CRS object using
* a postgis SRID, an EpsgCrsId id or a QGIS CRS_ID.
* @note We encourage you to use EpsgCrsId, Wkt or Proj4 to describe CRS's in your code
* @note We encourage you to use EpsgCrsId, WKT or Proj4 to describe CRS's in your code
* wherever possible. QGSI CRS_IDs are not guaranteed to be permanent / involatile.
* @param theId The ID no valid for the chosen coordinate system id type
* @param theType One of the types described in QgsCoordinateReferenceSystem::CrsType
@ -53,7 +53,7 @@ class QgsCoordinateReferenceSystem
*/
bool createFromOgcWmsCrs( QString theCrs );
/** Set up this srs by fetching the appropriate information from the
/** Set up this CRS by fetching the appropriate information from the
* sqlite backend. First the system level read only srs.db will be checked
* and then the users ~/.qgis/qgis.db database will be checked for a match.
* @note Any members will be overwritten during this process.
@ -61,19 +61,19 @@ class QgsCoordinateReferenceSystem
*/
bool createFromSrid( const long theSrid );
/** Set up this srs using a Wkt spatial ref sys definition.
* The wkt will be converted to a proj4 string using OGR helper
* functions. After this the srs databasses will be searched for matches.
/** Set up this CRS using a WKT spatial ref sys definition.
* The WKT will be converted to a proj4 string using OGR helper
* functions. After this the SRS databases will be searched for matches.
* First the system level read only srs.db will be checked
* and then the users ~/.qgis/qgis.db database will be checked for a match.
* @note Any members will be overwritten during this process.
* @note SRID and EpsgCrsId may be blank if no match can be found on srs db.
* @param theWkt The Wkt for the desired spatial reference system.
* @note SRID and EpsgCrsId may be blank if no match can be found on SRS db.
* @param theWkt The WKT for the desired spatial reference system.
* @return bool TRUE if success else false
*/
bool createFromWkt( const QString &theWkt );
/** Set up this srs by fetching the appropriate information from the
/** Set up this CRS by fetching the appropriate information from the
* sqlite backend. If the srsid is < 100000, only the system srs.db
* will be checked. If the srsid > 100000 the srs will be retrieved from
* the ~/.qgis/qgis.db
@ -83,7 +83,7 @@ class QgsCoordinateReferenceSystem
*/
bool createFromSrsId( const long theSrsId );
/** Set up this srs by passing it a proj4 style formatted string.
/** Set up this CRS by passing it a proj4 style formatted string.
* The string will be parsed and the projection and ellipsoid
* members set and the remainder of the proj4 string will be stored
* in the parameters member. The reason for this is so that we
@ -94,7 +94,7 @@ class QgsCoordinateReferenceSystem
*
* We try to match the proj string to and srsid using the following logic:
*
* - perform a whole text search on srs name (if not null). The srs name will
* - perform a whole text search on CRS name (if not null). The CRS name will
* have been set if this method has been delegated to from createFromWkt.
* - if the above does not match perform a whole text search on proj4 string (if not null)
* - if none of the above match convert the proj4 string to an OGR CRS
@ -111,7 +111,7 @@ class QgsCoordinateReferenceSystem
*/
bool createFromProj4( const QString &theProjString );
/** Set up this srs from a string definition, by default a WKT definition. Otherwise
/** Set up this CRS from a string definition, by default a WKT definition. Otherwise
* the string defines a authority, followed by a colon, followed by the definition.
* The authority can be one of "epsg", "postgis", "internal" for integer definitions,
* and "wkt" or "proj4" for string definitions. The implementation of each authority
@ -120,7 +120,7 @@ class QgsCoordinateReferenceSystem
*/
bool createFromString( const QString &theDefinition );
/** Set up this srs from a various text formats.
/** Set up this CRS from a various text formats.
*
* Valid formats: WKT string, "EPSG:n", "EPSGA:n", "AUTO:proj_id,unit_id,lon0,lat0",
* "urn:ogc:def:crs:EPSG::n", PROJ.4 string, filename (with WKT, XML or PROJ.4 string),
@ -145,7 +145,7 @@ class QgsCoordinateReferenceSystem
*/
static void setupESRIWktFix();
/** Find out whether this CRS is correctly initialised and usable */
/** Returns whether this CRS is correctly initialised and usable */
bool isValid() const;
/** Perform some validation on this CRS. If the sts doesn't validate the
@ -155,7 +155,7 @@ class QgsCoordinateReferenceSystem
* if that involves resorting to a hard coded default of geocs:wgs84.
*
* @note It is not usually necessary to use this function, unless you
* are trying to force this srs to be valid.
* are trying to force this CRS to be valid.
*/
void validate();
@ -219,65 +219,75 @@ class QgsCoordinateReferenceSystem
// Accessors -----------------------------------
/** Get the SrsId - if possible
* @return long theSrsId The internal sqlite3 srs.db primary key for this srs
*/
/** Returns the SrsId, if available.
* @return the internal sqlite3 srs.db primary key for this srs
* @see postgisSrid()
*/
long srsid() const;
/** Get the postgis srid for this srs
* @return long theSRID the Postgis spatial_ref_sys identifier for this srs (defaults to 0)
/** Returns PostGIS SRID for the CRS.
* @return the PostGIS spatial_ref_sys identifier for this CRS (defaults to 0)
*/
long postgisSrid() const;
/** Get the authority identifier for this srs
* @return QString the Authority identifier for this srs
/** Returns the authority identifier for the CRS, which includes both the authority (eg EPSG)
* and the CRS number (eg 4326). This is the best method to use when showing a very short CRS
* identifier to a user, eg "EPSG:4326".
* @returns the authority identifier for this CRS
* @see description()
*/
QString authid() const;
/** Get the Description
* @return QString the Description A textual description of the srs.
* @note A zero length string will be returned if the description is uninitialised
/** Returns the descriptive name of the CRS, eg "WGS 84" or "GDA 94 / Vicgrid94". In most
* cases this is the best method to use when showing a friendly identifier for the CRS to a
* user.
* @returns descriptive name of the CRS
* @note an empty string will be returned if the description is not available for the CRS
* @see authid()
*/
QString description() const;
/** Get the Projection Acronym
* @return QString theProjectionAcronym The official proj4 acronym for the projection family
* @note A zero length string will be returned if the projectionAcronym is uninitialised
/** Returns the projection acronym for the projection used by the CRS.
* @returns the official proj4 acronym for the projection family
* @note an empty string will be returned if the projectionAcronym is not available for the CRS
* @see ellipsoidAcronym()
*/
QString projectionAcronym() const;
/** Get the Ellipsoid Acronym
* @return QString theEllipsoidAcronym The official proj4 acronym for the ellipoid
* @note A zero length string will be returned if the ellipsoidAcronym is uninitialised
/** Returns the ellipsoid acronym for the ellipsoid used by the CRS.
* @returns the official proj4 acronym for the ellipoid
* @note an empty string will be returned if the ellipsoidAcronym is not available for the CRS
* @see projectionAcronym()
*/
QString ellipsoidAcronym() const;
/** A helper to get an wkt representation of this srs
* @return string containing Wkt of the srs
/** Returns a WKT representation of this CRS.
* @return string containing WKT of the CRS
* @see toProj4()
*/
QString toWkt() const;
/** Get the Proj Proj4 string representation of this srs.
/** Returns a Proj4 string representation of this CRS.
* If proj and ellps keys are found in the parameters,
* they will be stripped out and the Projection and ellipsoid acronyms will be
* they will be stripped out and the projection and ellipsoid acronyms will be
* overridden with these.
* @return QString theProj4String Proj4 format specifies that define this srs.
* @note A zero length string will be returned if the toProj4 is uninitialised
* @return Proj4 format string that defines this CRS.
* @note an empty string will be returned if the CRS could not be represented by a Proj4 string
* @see toWkt()
*/
QString toProj4() const;
/** Get this Geographic? flag
* @return bool theGeoFlag Whether this is a geographic or projected coordinate system
/** Returns whether the CRS is a geographic CRS.
* @returns true if CRS is geographic, or false if it is a projected CRS
*/
bool geographicFlag() const;
/** Return if axis is inverted (eg. for WMS 1.3)
* @return bool Whether this is crs axis is inverted
/** Returns whether axis is inverted (eg. for WMS 1.3) for the CRS.
* @returns true if CRS axis is inverted
*/
bool axisInverted() const;
/** Get the units that the projection is in
* @return QGis::UnitType that gives the units for the coordinate system
/** Returns the units for the projection used by the CRS.
*/
QGis::UnitType mapUnits() const;

View File

@ -72,7 +72,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
/** Use this constructor when you want to create a CRS object using
* a postgis SRID, an EpsgCrsId id or a QGIS CRS_ID.
* @note We encourage you to use EpsgCrsId, Wkt or Proj4 to describe CRS's in your code
* @note We encourage you to use EpsgCrsId, WKT or Proj4 to describe CRS's in your code
* wherever possible. QGSI CRS_IDs are not guaranteed to be permanent / involatile.
* @param theId The ID no valid for the chosen coordinate system id type
* @param theType One of the types described in QgsCoordinateReferenceSystem::CrsType
@ -98,7 +98,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*/
bool createFromOgcWmsCrs( QString theCrs );
/** Set up this srs by fetching the appropriate information from the
/** Set up this CRS by fetching the appropriate information from the
* sqlite backend. First the system level read only srs.db will be checked
* and then the users ~/.qgis/qgis.db database will be checked for a match.
* @note Any members will be overwritten during this process.
@ -106,19 +106,19 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*/
bool createFromSrid( const long theSrid );
/** Set up this srs using a Wkt spatial ref sys definition.
* The wkt will be converted to a proj4 string using OGR helper
* functions. After this the srs databasses will be searched for matches.
/** Set up this CRS using a WKT spatial ref sys definition.
* The WKT will be converted to a proj4 string using OGR helper
* functions. After this the SRS databases will be searched for matches.
* First the system level read only srs.db will be checked
* and then the users ~/.qgis/qgis.db database will be checked for a match.
* @note Any members will be overwritten during this process.
* @note SRID and EpsgCrsId may be blank if no match can be found on srs db.
* @param theWkt The Wkt for the desired spatial reference system.
* @note SRID and EpsgCrsId may be blank if no match can be found on SRS db.
* @param theWkt The WKT for the desired spatial reference system.
* @return bool TRUE if success else false
*/
bool createFromWkt( const QString &theWkt );
/** Set up this srs by fetching the appropriate information from the
/** Set up this CRS by fetching the appropriate information from the
* sqlite backend. If the srsid is < 100000, only the system srs.db
* will be checked. If the srsid > 100000 the srs will be retrieved from
* the ~/.qgis/qgis.db
@ -128,7 +128,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*/
bool createFromSrsId( const long theSrsId );
/** Set up this srs by passing it a proj4 style formatted string.
/** Set up this CRS by passing it a proj4 style formatted string.
* The string will be parsed and the projection and ellipsoid
* members set and the remainder of the proj4 string will be stored
* in the parameters member. The reason for this is so that we
@ -139,7 +139,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*
* We try to match the proj string to and srsid using the following logic:
*
* - perform a whole text search on srs name (if not null). The srs name will
* - perform a whole text search on CRS name (if not null). The CRS name will
* have been set if this method has been delegated to from createFromWkt.
* - if the above does not match perform a whole text search on proj4 string (if not null)
* - if none of the above match convert the proj4 string to an OGR CRS
@ -156,7 +156,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*/
bool createFromProj4( const QString &theProjString );
/** Set up this srs from a string definition, by default a WKT definition. Otherwise
/** Set up this CRS from a string definition, by default a WKT definition. Otherwise
* the string defines a authority, followed by a colon, followed by the definition.
* The authority can be one of "epsg", "postgis", "internal" for integer definitions,
* and "wkt" or "proj4" for string definitions. The implementation of each authority
@ -165,7 +165,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*/
bool createFromString( const QString &theDefinition );
/** Set up this srs from a various text formats.
/** Set up this CRS from a various text formats.
*
* Valid formats: WKT string, "EPSG:n", "EPSGA:n", "AUTO:proj_id,unit_id,lon0,lat0",
* "urn:ogc:def:crs:EPSG::n", PROJ.4 string, filename (with WKT, XML or PROJ.4 string),
@ -190,7 +190,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*/
static void setupESRIWktFix();
/** Find out whether this CRS is correctly initialised and usable */
/** Returns whether this CRS is correctly initialised and usable */
bool isValid() const;
/** Perform some validation on this CRS. If the sts doesn't validate the
@ -200,7 +200,7 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
* if that involves resorting to a hard coded default of geocs:wgs84.
*
* @note It is not usually necessary to use this function, unless you
* are trying to force this srs to be valid.
* are trying to force this CRS to be valid.
*/
void validate();
@ -264,65 +264,75 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
// Accessors -----------------------------------
/** Get the SrsId - if possible
* @return long theSrsId The internal sqlite3 srs.db primary key for this srs
/** Returns the SrsId, if available.
* @return the internal sqlite3 srs.db primary key for this srs
* @see postgisSrid()
*/
long srsid() const;
/** Get the postgis srid for this srs
* @return long theSRID the Postgis spatial_ref_sys identifier for this srs (defaults to 0)
/** Returns PostGIS SRID for the CRS.
* @return the PostGIS spatial_ref_sys identifier for this CRS (defaults to 0)
*/
long postgisSrid() const;
/** Get the authority identifier for this srs
* @return QString the Authority identifier for this srs
/** Returns the authority identifier for the CRS, which includes both the authority (eg EPSG)
* and the CRS number (eg 4326). This is the best method to use when showing a very short CRS
* identifier to a user, eg "EPSG:4326".
* @returns the authority identifier for this CRS
* @see description()
*/
QString authid() const;
/** Get the Description
* @return QString the Description A textual description of the srs.
* @note A zero length string will be returned if the description is uninitialised
/** Returns the descriptive name of the CRS, eg "WGS 84" or "GDA 94 / Vicgrid94". In most
* cases this is the best method to use when showing a friendly identifier for the CRS to a
* user.
* @returns descriptive name of the CRS
* @note an empty string will be returned if the description is not available for the CRS
* @see authid()
*/
QString description() const;
/** Get the Projection Acronym
* @return QString theProjectionAcronym The official proj4 acronym for the projection family
* @note A zero length string will be returned if the projectionAcronym is uninitialised
/** Returns the projection acronym for the projection used by the CRS.
* @returns the official proj4 acronym for the projection family
* @note an empty string will be returned if the projectionAcronym is not available for the CRS
* @see ellipsoidAcronym()
*/
QString projectionAcronym() const;
/** Get the Ellipsoid Acronym
* @return QString theEllipsoidAcronym The official proj4 acronym for the ellipoid
* @note A zero length string will be returned if the ellipsoidAcronym is uninitialised
/** Returns the ellipsoid acronym for the ellipsoid used by the CRS.
* @returns the official proj4 acronym for the ellipoid
* @note an empty string will be returned if the ellipsoidAcronym is not available for the CRS
* @see projectionAcronym()
*/
QString ellipsoidAcronym() const;
/** A helper to get an wkt representation of this srs
* @return string containing Wkt of the srs
/** Returns a WKT representation of this CRS.
* @return string containing WKT of the CRS
* @see toProj4()
*/
QString toWkt() const;
/** Get the Proj Proj4 string representation of this srs.
/** Returns a Proj4 string representation of this CRS.
* If proj and ellps keys are found in the parameters,
* they will be stripped out and the Projection and ellipsoid acronyms will be
* they will be stripped out and the projection and ellipsoid acronyms will be
* overridden with these.
* @return QString theProj4String Proj4 format specifies that define this srs.
* @note A zero length string will be returned if the toProj4 is uninitialised
* @return Proj4 format string that defines this CRS.
* @note an empty string will be returned if the CRS could not be represented by a Proj4 string
* @see toWkt()
*/
QString toProj4() const;
/** Get this Geographic? flag
* @return bool theGeoFlag Whether this is a geographic or projected coordinate system
/** Returns whether the CRS is a geographic CRS.
* @returns true if CRS is geographic, or false if it is a projected CRS
*/
bool geographicFlag() const;
/** Return if axis is inverted (eg. for WMS 1.3)
* @return bool Whether this is crs axis is inverted
/** Returns whether axis is inverted (eg. for WMS 1.3) for the CRS.
* @returns true if CRS axis is inverted
*/
bool axisInverted() const;
/** Get the units that the projection is in
* @return QGis::UnitType that gives the units for the coordinate system
/** Returns the units for the projection used by the CRS.
*/
QGis::UnitType mapUnits() const;
@ -367,21 +377,21 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
static QString proj4FromSrsId( const int theSrsId );
/** Set the QGIS SrsId
* @param theSrsId The internal sqlite3 srs.db primary key for this srs
* @param theSrsId The internal sqlite3 srs.db primary key for this CRS
*/
void setInternalId( long theSrsId );
/** Set the postgis srid
* @param theSrid The postgis spatial_ref_sys key for this srs
* @param theSrid The postgis spatial_ref_sys key for this CRS
*/
void setSrid( long theSrid );
/** Set the Description
* @param theDescription A textual description of the srs.
* @param theDescription A textual description of the CRS.
*/
void setDescription( const QString& theDescription );
/** Set the Proj Proj4String.
* @param theProj4String Proj4 format specifies
* (excluding proj and ellips) that define this srs.
* (excluding proj and ellips) that define this CRS.
* @note some content of the PROJ4 string may be stripped off by this
* method due to the parsing of the string by OSRNewSpatialReference .
* For example input:
@ -396,13 +406,13 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
*/
void setGeographicFlag( bool theGeoFlag );
/** Set the EpsgCrsId identifier for this srs
* @param theEpsg the ESPG identifier for this srs (defaults to 0)
/** Set the EpsgCrsId identifier for this CRS
* @param theEpsg the ESPG identifier for this CRS (defaults to 0)
*/
void setEpsg( long theEpsg );
/** Set the authority identifier for this srs
* @param theID the authority identifier for this srs (defaults to 0)
/** Set the authority identifier for this CRS
* @param theID the authority identifier for this CRS (defaults to 0)
*/
void setAuthId( const QString& theID );
/** Set the projection acronym
@ -432,9 +442,9 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
// returns the same code as sqlite3_open
static int openDb( const QString& path, sqlite3 **db, bool readonly = true );
//!The internal sqlite3 srs.db primary key for this srs
//!The internal sqlite3 srs.db primary key for this CRS
long mSrsId;
//!A textual description of the srs.
//!A textual description of the CRS.
QString mDescription;
//!The official proj4 acronym for the projection family
QString mProjectionAcronym;
@ -444,11 +454,11 @@ class CORE_EXPORT QgsCoordinateReferenceSystem
bool mGeoFlag;
//! The map units
QGis::UnitType mMapUnits;
//!If available, the Postgis spatial_ref_sys identifier for this srs (defaults to 0)
//!If available, the Postgis spatial_ref_sys identifier for this CRS (defaults to 0)
long mSRID;
//!If available the authority identifier for this srs
//!If available the authority identifier for this CRS
QString mAuthId;
//! Whether this srs is properly defined and valid
//! Whether this CRS is properly defined and valid
bool mIsValidFlag;
//! Work out the projection units and set the appropriate local variable