diff --git a/python/core/qgscoordinatereferencesystem.sip b/python/core/qgscoordinatereferencesystem.sip index 7b9228bb297..5a4def04e8a 100644 --- a/python/core/qgscoordinatereferencesystem.sip +++ b/python/core/qgscoordinatereferencesystem.sip @@ -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; diff --git a/src/core/qgscoordinatereferencesystem.h b/src/core/qgscoordinatereferencesystem.h index 3133c6a07d6..44587c9d465 100644 --- a/src/core/qgscoordinatereferencesystem.h +++ b/src/core/qgscoordinatereferencesystem.h @@ -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