/*!
* \class QgsSpatialRefSys
* \brief Class for storing a spatial reference system (SRS)
*/
class QgsSpatialRefSys
{
%TypeHeaderCode
#include <qgsspatialrefsys.h>
%End
public:
// typedef void (*CUSTOM_SRS_VALIDATION)(QgsSpatialRefSys*);
enum SRS_TYPE {
QGIS_SRSID,
POSTGIS_SRID,
EPSG
};
//! Default constructor
QgsSpatialRefSys();
/*!
* Constructs a SRS object from a WKT string
* @param theWkt A String containing a valid Wkt def
*/
explicit QgsSpatialRefSys(QString theWkt);
/*! Use this constructor when you want to create a SRS object using
* a postgis SRID, an EPSG id or a QGIS SRS_ID.
* @param theId The ID no valid for the chosen coordinate system id type
* @param theType One of the types described in QgsSpatialRefSys::SRS_TYPE
*/
QgsSpatialRefSys(const long theId, SRS_TYPE theType=POSTGIS_SRID);
// Misc helper functions -----------------------
void createFromId(const long theId, SRS_TYPE theType=POSTGIS_SRID);
/**
* \brief Set up this SRS from the given OGC CRS
*
* Sets this SRS to the given OGC WMS-format Coordinate Reference Systems.
*
* \note This function only deals with EPSG labels only at this time.
*
* \retval FALSE if not given an EPSG label
*/
bool createFromOgcWmsCrs(QString theCrs);
/*! Set up this srs 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.
* 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 EPSG 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 sucess else false
*/
bool createFromWkt(const QString theWkt);
/*! Set up this srs 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 theEpsg The EPSG for the desired spatial reference system.
* @return bool TRUE if sucess else false
*/
bool createFromEpsg(const long theEpsg);
/*! Set up this srs 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 sucess else false
*/
bool createFromSrsId (const long theSrsId);
/*! Set up this srs 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 ellpse and proj elements stripped out
* is hepful 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 srs name (if not null). The srs 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 SRS
* 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 doesnt munch yer cpu so much.
*
* @note If the srs was not matched, we will create a new entry on the users tbl_srs
* for this srs.
*
* @param theProjString A proj4 format string
* @return bool TRUE if sucess else false
*/
bool createFromProj4 (const QString theProjString);
/*! Find out whether this SRS is correctly initialised and useable */
bool isValid() const;
/*! Perform some validation on this SRS. If the sts doesnt validate the
* default behaviour settings for layers with unknown SRS will be
* consulted and acted on accordingly. By hell or high water this
* method will do its best to make sure that this SRS is valid - even
* if that involves resorting to a hard coded default of geocs:wgs84.
*
* @note It is not usually neccessary to use this function, unless you
* are trying to force theis srs to be valid.
*/
void validate();
/*! This is a globbing function to try to find a record in the database
* that matches a SRS defined only by a proj4string. The goal is to
* learn what the tbl_srs.srs_id value is for the SRS. Internally
* the source SRS is converted to and OGR srs object using the proj4string
* 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 SRS.
* 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 lomg the SrsId of the matched SRS
*/
long findMatchingProj();
/*! A string based associative array used for passing records around */
typedef QMap<QString, QString> RecordMap;
/*! Get a record from the srs.db or qgis.db backends, given an sql statment.
* @note only handles queries that return a single record.
* @note it will first try the system srs.db then the users qgis.db!
* @param QString The sql query to execute
* @return QMap An associative array of field name <-> value pairs
*/
RecordMap getRecord(QString theSql);
/*! Overloaded == operator used to compare to SRS's.
* Internally it will delegate to the equals method described below
*/
bool operator==(const QgsSpatialRefSys &theSrs);
/*! Overloaded != operator used to compare to SRS's.
* Returns opposite bool value to operator ==
*/
bool operator!=(const QgsSpatialRefSys &theSrs);
/*! Overloaded == operator used to compare to SRS's.
* Internally it will use OGR isSameSRS() or isSameGeoSRS() methods as appropriate.
* Additionally logic may also be applied if the result from the OGR methods
* is inconclusive.
*/
bool equals(QString theProj4String);
/*! A helper to get an wkt representation of this srs
* @return string containing Wkt of the srs
*/
QString toWkt() 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( QDomNode & theNode );
/*! Stores state to the given DOM node in the given document.
* Below is an example of the generated tag.
* <spatialrefsys>
* <proj4>+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs </proj4>
* <srsid>2585</srsid>
* <srid>4326</srid>
* <epsg>4326</epsg>
* <description>WGS 84</description>
* <projectionacronym>longlat</projectionacronym>
* <ellipsoidacronym>WGS84</ellipsoidacronym>
* </spatialrefsys>
* @param theNode The node in which state will be restored
* @param theDom The document in which state will be stored
* @return bool True on success, False on failure
*/
bool writeXML( QDomNode & theNode, QDomDocument & theDoc );
/** A static helper function to find out the proj4 string for a srsid
* @param int theSrsId The srsid used for the lookup
* @return QString The proj4 string
*/
static QString getProj4FromSrsId(const int theSrsId);
/** Sets custom function to force valid SRS
* QGIS uses implementation in QgisGui::customSrsValidation
*/
// TODO: disabled for now, needs usage of %Method directive to pass the function
//static void setCustomSrsValidation(CUSTOM_SRS_VALIDATION f);
// Accessors -----------------------------------
/*! Get the SrsId - if possible
* @return long theSrsId The internal sqlite3 srs.db primary key for this srs
*/
long srsid() const;
/*! Get the Postgis SRID - if possible.
* @return long theSRID The internal postgis SRID for this SRS
*/
long srid() 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
*/
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
*/
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
*/
QString ellipsoidAcronym () const;
/** Get the Proj Proj4String. 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 QString theProj4String Proj4 format specifies that define this srs.
* @note A zero length string will be returned if the proj4String is uninitialised
*/
QString proj4String() const;
/*! Get this Geographic? flag
* @return bool theGeoFlag Whether this is a geographic or projected coordinate system
*/
bool geographicFlag () const;
/*! Get the units that the projection is in
* @return QGis::units that gives the units for the coordinate system
*/
QGis::units mapUnits() const;
/*! Set the postgis srid for this srs
* @return long theSRID the Postgis spatial_ref_sys identifier for this srs (defaults to 0)
*/
long postgisSrid () const;
/*! Set the EPSG identifier for this srs
* @return long theEpsg the ESPG identifier for this srs (defaults to 0)
*/
long epsg () const;
// Mutators -----------------------------------
/*! Set the QGIS SrsId
* @param long theSrsId The internal sqlite3 srs.db primary key for this srs
*/
void setSrsId(long theSrsId);
/*! Set the postgis srid
* @param long theSrsId The postgis spatial_ref_sys key for this srs
*/
void setSrid(long theSrid);
/*! Set the Description
* @param QString the Description A textual description of the srs.
*/
void setDescription (QString theDescription);
/* Set the Proj Proj4String.
* @param QString theProj4String Proj4 format specifies (excluding proj and ellips) that define this srs.
*/
void setProj4String (QString theProj4String);
/*! Set this Geographic? flag
* @param bool theGeoFlag Whether this is a geographic or projected coordinate system
*/
void setGeographicFlag (bool theGeoFlag);
/*! Set the EPSG identifier for this srs
* @param long theEpsg the ESPG identifier for this srs (defaults to 0)
*/
void setEpsg (long theEpsg);
/*! Set the projection acronym
* @param QString the acronym (must be a valid proj4 projection acronym)
*/
void setProjectionAcronym(QString theProjectionAcronym);
/*! Set the ellipsoid acronym
* @param QString the acronym (must be a valid proj4 ellipsoid acronym)
*/
void setEllipsoidAcronym(QString theEllipsoidAcronym);
};