Skip to content
Permalink
Browse files

Improve QgsCoordinateReferenceSystem documentation

  • Loading branch information
nyalldawson committed Feb 2, 2016
1 parent 9e292d0 commit d4ea95ea4930fe9de34ffe7c664dd2261b95bc97
Showing with 116 additions and 96 deletions.
  1. +52 −42 python/core/qgscoordinatereferencesystem.sip
  2. +64 −54 src/core/qgscoordinatereferencesystem.h
@@ -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,27 +53,27 @@ 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.
* @param theSrid The postgis SRID for the desired spatial reference system.
*/
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;

0 comments on commit d4ea95e

Please sign in to comment.
You can’t perform that action at this time.