/** \ingroup core * Class for storing a coordinate reference system (CRS) */ class QgsCoordinateReferenceSystem { %TypeHeaderCode #include %End public: // typedef void (*CUSTOM_CRS_VALIDATION)(QgsCoordinateReferenceSystem*); enum CrsType { InternalCrsId, PostgisCrsId, EpsgCrsId // deprecated }; //! Default constructor QgsCoordinateReferenceSystem(); ~QgsCoordinateReferenceSystem(); /*! * Constructs a CRS object from a string definition as defined in the createFromString * member function (by default a WKT definition). * @param theDefinition A String containing a coordinate reference system definition. */ explicit QgsCoordinateReferenceSystem( const QString& theDefinition ); /** 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 * wherever possible. QGIS 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 */ QgsCoordinateReferenceSystem( const long theId, CrsType theType = PostgisCrsId ); // Misc helper functions ----------------------- bool createFromId( const long theId, CrsType theType = PostgisCrsId ); /** * Sets this CRS to the given OGC WMS-format Coordinate Reference Systems. * @returns false if not given an valid label * @note this method is expensive. Consider using QgsCRSCache::crsByOgcWmsCrs() instead. */ bool createFromOgcWmsCrs( QString theCrs ); /** 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 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. * @return bool TRUE if success else false */ bool createFromWkt( const QString &theWkt ); /** 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 * @note Any members will be overwritten during this process. * @param theSrsId The QGIS SrsId for the desired spatial reference system. * @return bool TRUE if success else false */ bool createFromSrsId( const long theSrsId ); /** 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 * can easily present the user with 'natural language' representation * of the projection and ellipsoid by looking them up in the srs.bs sqlite * database. Also having the ellipse and proj elements stripped out * is helpful to speed up globbing queries (see below). * * We try to match the proj string to and srsid using the following logic: * * - 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 * then check if its a geocs or a proj cs (using ogr isGeographic) * then sequentially walk through the database (first users qgis.db srs tbl then * system srs.db tbl), converting each entry into an ogr srs and using isSame * or isSameGeocs (essentially calling the == overloaded operator). We'll try to * be smart about this and first parse out the proj and ellpse strings and only * check for a match in entities that have the same ellps and proj entries so * that it doesn't munch yer cpu so much. * * @param theProjString A proj4 format string * @return bool TRUE if success else false * @note this method is expensive. Consider using QgsCRSCache::crsByProj4() instead. */ bool createFromProj4( const QString &theProjString ); /** 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 * uses the corresponding createFrom... function. * @param theDefinition A String containing a coordinate reference system definition. */ bool createFromString( const QString &theDefinition ); /** 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), * well known name (such as NAD27, NAD83, WGS84 or WGS72), * ESRI::[WKT string] (directly or in a file), "IGNF:xxx" * * For more details on supported formats see OGRSpatialReference::SetFromUserInput() * ( http://www.gdal.org/ogr/classOGRSpatialReference.html#aec3c6a49533fe457ddc763d699ff8796 ) * @note this function generates a WKT string using OSRSetFromUserInput() and * passes it to createFromWkt() function. * @param theDefinition A String containing a coordinate reference system definition. */ bool createFromUserInput( const QString &theDefinition ); /** Make sure that ESRI WKT import is done properly. * This is required for proper shapefile CRS import when using gdal>= 1.9. * @note This function is called by createFromUserInput() and QgsOgrProvider::crs(), there is usually * no need to call it from elsewhere. * @note This function sets CPL config option GDAL_FIX_ESRI_WKT to a proper value, * unless it has been set by the user through the commandline or an environment variable. * For more details refer to OGRSpatialReference::morphFromESRI() . */ static void setupESRIWktFix(); /** Returns whether this CRS is correctly initialized and usable */ bool isValid() const; /** Perform some validation on this CRS. If the sts doesn't validate the * default behaviour settings for layers with unknown CRS will be * consulted and acted on accordingly. By hell or high water this * method will do its best to make sure that this CRS is valid - even * 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 CRS to be valid. */ void validate(); /** This is a globbing function to try to find a record in the database * that matches a CRS defined only by a proj4string. The goal is to * learn what the tbl_srs.srs_id value is for the CRS. Internally * the source CRS is converted to an OGR srs object using the proj4string call * and then every record in the database that matches projection and ellipsoid * will be converted to an OGR srs in turn and compared to the source CRS. * There are some gotchas with using ogr isSame() srs comparison, but * its more effective than using straight string comparison of proj4params. * @note The ellipsoid and projection acronyms must be set as well as the proj4string! * @return long the SrsId of the matched CRS */ long findMatchingProj(); /** Overloaded == operator used to compare to CRS's. * Internally it will delegate to the equals method described below */ bool operator==( const QgsCoordinateReferenceSystem &theSrs ) const; /** Overloaded != operator used to compare to CRS's. * Returns opposite bool value to operator == */ bool operator!=( const QgsCoordinateReferenceSystem &theSrs ) const; /** Restores state from the given Dom node. * @param theNode The node from which state will be restored * @return bool True on success, False on failure */ bool readXML( const QDomNode & theNode ); /** Stores state to the given Dom node in the given document. * Below is an example of the generated tag. \code{.xml} +proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs 2585 4326 4326 WGS 84 longlat WGS84 \endcode * @param theNode The node in which state will be restored * @param theDoc The document in which state will be stored * @return bool True on success, False on failure */ bool writeXML( QDomNode & theNode, QDomDocument & theDoc ) const; /** Sets custom function to force valid CRS * QGIS uses implementation in QgisGui::customSrsValidation * @note not available in python bindings */ // static void setCustomSrsValidation( CUSTOM_CRS_VALIDATION f ); /** Gets custom function * @note not available in python bindings */ // static CUSTOM_CRS_VALIDATION customSrsValidation(); // Accessors ----------------------------------- /** Returns the SrsId, if available. * @return the internal sqlite3 srs.db primary key for this srs * @see postgisSrid() */ long srsid() const; /** Returns PostGIS SRID for the CRS. * @return the PostGIS spatial_ref_sys identifier for this CRS (defaults to 0) */ long postgisSrid() const; /** 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; /** 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; /** 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; /** 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; /** Returns a WKT representation of this CRS. * @return string containing WKT of the CRS * @see toProj4() */ QString toWkt() const; /** 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 * overridden with these. * @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; /** 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; /** Returns whether axis is inverted (eg. for WMS 1.3) for the CRS. * @returns true if CRS axis is inverted */ bool axisInverted() const; /** Returns the units for the projection used by the CRS. */ QGis::UnitType mapUnits() const; // Mutators ----------------------------------- /** Set user hint for validation */ void setValidationHint( const QString& html ); /** Get user hint for validation */ QString validationHint(); /** Update proj.4 parameters in our database from proj.4 * @returns number of updated CRS on success and * negative number of failed updates in case of errors. */ static int syncDb(); /** Save the proj4-string as a custom CRS * @returns bool true if success else false */ bool saveAsUserCRS( const QString& name ); /** Returns auth id of related geographic CRS*/ QString geographicCRSAuthId() const; /** Returns a list of recently used projections * @returns list of srsid for recently used projections * @note added in QGIS 2.7 */ static QStringList recentProjections(); };