Main MRPT website > C++ reference
MRPT logo

conversions.h

Go to the documentation of this file.
00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2011  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 #ifndef  conversions_H
00029 #define  conversions_H
00030 
00031 #include <mrpt/utils/utils_defs.h>
00032 #include <mrpt/math/lightweight_geom_data.h>
00033 
00034 #include <mrpt/topography/link_pragmas.h>
00035 
00036 #include <mrpt/topography/data_types.h>
00037 
00038 
00039 namespace mrpt
00040 {
00041         /** This namespace provides topography helper functions, coordinate transformations.
00042          */
00043         namespace topography
00044         {
00045                 using namespace std;
00046                 using namespace mrpt::utils;
00047 
00048         /** =======================================================================
00049                    @name Topography coordinate conversion functions
00050                    @{ */
00051 
00052                 /** Coordinates transformation from longitude/latitude/height to ENU (East-North-Up)  X/Y/Z coordinates
00053                   *  The WGS84 ellipsoid is used for the transformation. The coordinates are in 3D
00054                   *   relative to some user-provided point, with local X axis being east-ward, Y north-ward, Z up-ward.
00055                   *  For an explanation, refer to http://en.wikipedia.org/wiki/Reference_ellipsoid
00056                   * \sa coordinatesTransformation_WGS84_geocentric, ENU_axes_from_WGS84, ENUToGeocentric
00057                   */
00058                 void  TOPO_IMPEXP geodeticToENU_WGS84(
00059                         const TGeodeticCoords           &in_coords,
00060                         mrpt::math::TPoint3D    &out_ENU_point,
00061                         const TGeodeticCoords           &in_coords_origin );
00062 
00063                 /** ENU to geocentric coordinates.
00064                   * \sa geodeticToENU_WGS84
00065                   */
00066                 void  TOPO_IMPEXP ENUToGeocentric(
00067                         const mrpt::math::TPoint3D      &in_ENU_point,
00068                         const TGeodeticCoords           &in_coords_origin,
00069                         TGeocentricCoords                       &out_coords,
00070                         const TEllipsoid                        &ellip );
00071 
00072                 /** Coordinates transformation from longitude/latitude/height to geocentric X/Y/Z coordinates (with a WGS84 geoid).
00073                   *  The WGS84 ellipsoid is used for the transformation. The coordinates are in 3D
00074                   *   where the reference is the center of the Earth.
00075                   *  For an explanation, refer to http://en.wikipedia.org/wiki/Reference_ellipsoid
00076                   * \sa geodeticToENU_WGS84
00077                   */
00078                 void  TOPO_IMPEXP geodeticToGeocentric_WGS84(
00079                         const TGeodeticCoords           &in_coords,
00080                         mrpt::math::TPoint3D  &out_point );
00081 
00082                 /** Coordinates transformation from longitude/latitude/height to geocentric X/Y/Z coordinates (with an specified geoid).
00083                   * \sa geocentricToGeodetic
00084                   */
00085                 void  TOPO_IMPEXP geodeticToGeocentric(
00086                         const TGeodeticCoords   &in_coords,
00087                         TGeocentricCoords               &out_point,
00088                         const TEllipsoid                &ellip );
00089 
00090                 /** Coordinates transformation from geocentric X/Y/Z coordinates to longitude/latitude/height.
00091                   * \sa geodeticToGeocentric
00092                   */
00093                 void  TOPO_IMPEXP geocentricToGeodetic(
00094                         const TGeocentricCoords         &in_point,
00095                         TGeodeticCoords                         &out_coords,
00096                         const TEllipsoid                        &ellip = TEllipsoid::Ellipsoid_WGS84() );
00097 
00098                 /**  7-parameter Bursa-Wolf transformation:
00099                   *   [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 RZ -RY; -RZ 1 RX; RY -RX 1 ] [ X Y Z ]_local
00100                   * \sa transform10params
00101                   */
00102                 void  TOPO_IMPEXP transform7params(
00103                         const mrpt::math::TPoint3D      &in_point,
00104                         const TDatum7Params                     &in_datum,
00105                         mrpt::math::TPoint3D            &out_point);
00106 
00107                 void  TOPO_IMPEXP transform7params_TOPCON(
00108                         const mrpt::math::TPoint3D      &in_point,
00109                         const TDatum7Params_TOPCON      &in_datum,
00110                         mrpt::math::TPoint3D            &out_point);
00111 
00112                 /**  10-parameter Molodensky-Badekas transformation:
00113                   *   [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 RZ -RY; -RZ 1 RX; RY -RX 1 ] [ X-Xp Y-Yp Z-Zp ]_local  + [Xp Yp Zp]
00114                   * \sa transform7params
00115                   */
00116                 void  TOPO_IMPEXP transform10params(
00117                         const mrpt::math::TPoint3D      &in_point,
00118                         const TDatum10Params            &in_datum,
00119                         mrpt::math::TPoint3D            &out_point);
00120 
00121                 /**  Helmert 2D transformation:
00122                   *   [ X Y ]_WGS84 = [ dX dY ] + ( 1 + dS ) [ cos(alpha) -sin(alpha); sin(alpha) cos(alpha) ] [ X-Xp Y-Yp Z-Zp ]_local + [Xp Yp Zp]
00123                   * \sa transformHelmert3D
00124                   */
00125                 void  TOPO_IMPEXP transformHelmert2D(
00126                         const mrpt::math::TPoint2D      &p,
00127                         const TDatumHelmert2D           &d,
00128                         mrpt::math::TPoint2D            &o);
00129 
00130                 void  TOPO_IMPEXP transformHelmert2D_TOPCON(
00131                         const mrpt::math::TPoint2D              &p,
00132                         const TDatumHelmert2D_TOPCON    &d,
00133                         mrpt::math::TPoint2D                    &o);
00134 
00135                 /**  Helmert3D transformation:
00136                   *   [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 -RZ RY; RZ 1 -RX; -RY RX 1 ] [ X Y Z ]_local
00137                   * \sa transformHelmert2D
00138                   */
00139                 void  TOPO_IMPEXP transformHelmert3D(
00140                         const mrpt::math::TPoint3D      &p,
00141                         const TDatumHelmert3D           &d,
00142                         mrpt::math::TPoint3D            &o);
00143 
00144                 void  TOPO_IMPEXP transformHelmert3D_TOPCON(
00145                         const mrpt::math::TPoint3D              &p,
00146                         const TDatumHelmert3D_TOPCON    &d,
00147                         mrpt::math::TPoint3D                    &o);
00148 
00149                 /**  1D transformation:
00150                   *   [ Z ]_WGS84 = (dy * X - dx * Y + Z)*(1+e)+DZ
00151                   */
00152                 void  TOPO_IMPEXP transform1D(
00153                         const mrpt::math::TPoint3D      &p,
00154                         const TDatum1DTransf            &d,
00155                         mrpt::math::TPoint3D            &o);
00156 
00157                 /**  Interpolation:
00158                   *   [ Z ]_WGS84 = (dy * X - dx * Y + Z)*(1+e)+DZ
00159                   */
00160                 void  TOPO_IMPEXP transfInterpolation(
00161                         const mrpt::math::TPoint3D              &p,
00162                         const TDatumTransfInterpolation &d,
00163                         mrpt::math::TPoint3D                    &o);
00164 
00165                 /** Returns the Geodetic coordinates of the UTM input point.
00166                   * \param X: East coordinate of the input point.
00167                   * \param Y: North coordinate of the input point.
00168                   * \param zone: time zone (Spanish: "huso").
00169                   * \param hem: hemisphere ('N'/'n' for North or 'S'/s' for South ). An exception will be raised on any other value.
00170                   * \param ellip: the reference ellipsoid used for the transformation (default: WGS84)
00171                   * \param out_lat  Out latitude, in degrees.
00172                   * \param out_lon  Out longitude, in degrees.
00173                   */
00174                 void TOPO_IMPEXP UTMToGeodetic(
00175                         double          X,
00176                         double          Y,
00177                         int                     zone,
00178                         char            hem,
00179                         double          &out_lon /*degrees*/,
00180                         double          &out_lat /*degrees*/,
00181                         TEllipsoid      ellip = TEllipsoid::Ellipsoid_WGS84() );
00182 
00183                 /** Returns the Geodetic coordinates of the UTM input point.
00184                   * \param UTMCoords: UTM input coordinates.
00185                   * \param zone: time zone (Spanish: "huso").
00186                   * \param hem: hemisphere ('N'/'n' for North or 'S'/s' for South ). An exception will be raised on any other value.
00187                   * \param GeodeticCoords: Out geodetic coordinates.
00188                   * \param ellip: the reference ellipsoid used for the transformation (default: WGS84)
00189                   */
00190                 inline void TOPO_IMPEXP UTMToGeodetic(
00191                         const TUTMCoords        &UTMCoords,
00192                         const int                       &zone,
00193                         const char                      &hem,
00194                         TGeodeticCoords         &GeodeticCoords,
00195                         TEllipsoid      ellip = TEllipsoid::Ellipsoid_WGS84() )
00196                 {
00197                         UTMToGeodetic( UTMCoords.x, UTMCoords.y, zone, hem, GeodeticCoords.lon.decimal_value, GeodeticCoords.lat.decimal_value, ellip );
00198                         GeodeticCoords.height = UTMCoords.z;
00199                 }
00200 
00201                 /** Convert latitude and longitude coordinates into UTM coordinates, computing the corresponding UTM zone and latitude band.
00202                   *   This method is based on public code by Gabriel Ruiz Martinez and Rafael Palacios.
00203                   *   Example:
00204                   *   \code
00205                   *   Input:
00206                   *    Lat=40.3154333    Lon=-3.4857166
00207                   *   Output:
00208                   *    x = 458731
00209                   *    y = 4462881
00210                   *    utm_zone = 30
00211                   *    utm_band = T
00212                   *   \endcode
00213                   *   \sa http://www.mathworks.com/matlabcentral/fileexchange/10915
00214                  */
00215                 void  TOPO_IMPEXP GeodeticToUTM(
00216                         double          in_latitude_degrees,
00217                         double          in_longitude_degrees,
00218                         double          &out_UTM_x,
00219                         double          &out_UTM_y,
00220                         int             &out_UTM_zone,
00221                         char            &out_UTM_latitude_band,
00222                         TEllipsoid      ellip = TEllipsoid::Ellipsoid_WGS84());
00223 
00224                 void  TOPO_IMPEXP geodeticToUTM(
00225                         const TGeodeticCoords   &GeodeticCoords,
00226                         TUTMCoords                              &UTMCoords,
00227                         int                                     &UTMZone,
00228                         char                                    &UTMLatitudeBand,
00229                         TEllipsoid                              ellip = TEllipsoid::Ellipsoid_WGS84());
00230 
00231 
00232                 /** Convert latitude and longitude coordinates into UTM coordinates, computing the corresponding UTM zone and latitude band.
00233                   *   This method is based on public code by Gabriel Ruiz Martinez and Rafael Palacios.
00234                   *   Example:
00235                   *   \code
00236                   *   Input:
00237                   *    Lat=40.3154333    Lon=-3.4857166
00238                   *   Output:
00239                   *    x = 458731
00240                   *    y = 4462881
00241                   *    utm_zone = 30
00242                   *    utm_band = T
00243                   *   \endcode
00244                   *   \sa http://www.mathworks.com/matlabcentral/fileexchange/10915
00245                  */
00246                 inline void  TOPO_IMPEXP GeodeticToUTM(
00247                         const TGeodeticCoords   &GeodeticCoords,
00248                         TUTMCoords                              &UTMCoords,
00249                         int                                     &UTMZone,
00250                         char                                    &UTMLatitudeBand,
00251                         TEllipsoid                              ellip = TEllipsoid::Ellipsoid_WGS84())
00252                 {
00253                         GeodeticToUTM( GeodeticCoords.lat, GeodeticCoords.lon, UTMCoords.x, UTMCoords.y, UTMZone, UTMLatitudeBand, ellip );
00254                         UTMCoords.z = GeodeticCoords.height;
00255                 }
00256 
00257 
00258         /** @}
00259             ======================================================================= */
00260 
00261 
00262         /** =======================================================================
00263            @name DEPRECATED topography coordinate conversion functions
00264            @{ */
00265 
00266                 /** Coordinates transformation from longitude/latitude/height to ENU (East-North-Up)  X/Y/Z coordinates
00267                   *  The WGS84 ellipsoid is used for the transformation. The coordinates are in 3D
00268                   *   relative to some user-provided point, with local X axis being east-ward, Y north-ward, Z up-ward.
00269                   *  For an explanation, refer to http://en.wikipedia.org/wiki/Reference_ellipsoid
00270                   * \sa coordinatesTransformation_WGS84_geocentric, ENU_axes_from_WGS84
00271                   */
00272                 MRPT_DECLARE_DEPRECATED_FUNCTION("*DEPRECATED* Use geodeticToENU_WGS84 instead",
00273                 void TOPO_IMPEXP coordinatesTransformation_WGS84(
00274                         double          in_longitude_degrees,
00275                         double          in_latitude_degrees,
00276                         double          in_height_meters,
00277                         double          &out_x_meters,
00278                         double          &out_y_meters,
00279                         double          &out_z_meters,
00280                         double          in_longitude_reference_degrees,
00281                         double          in_latitude_reference_degrees,
00282                         double          in_height_reference_meters
00283                         ));
00284 
00285                 /** Coordinates transformation from longitude/latitude/height to geocentric X/Y/Z coordinates (with a WGS84 geoid).
00286                   *  The WGS84 ellipsoid is used for the transformation. The coordinates are in 3D
00287                   *   where the reference is the center of the Earth.
00288                   *  For an explanation, refer to http://en.wikipedia.org/wiki/Reference_ellipsoid
00289                   * \sa geodeticToENU_WGS84
00290                   */
00291                 MRPT_DECLARE_DEPRECATED_FUNCTION("*DEPRECATED* Use geodeticToENU_WGS84 instead",
00292                 void TOPO_IMPEXP coordinatesTransformation_WGS84_geocentric(
00293                         double          in_longitude_degrees,
00294                         double          in_latitude_degrees,
00295                         double          in_height_meters,
00296                         double          &out_x_meters,
00297                         double          &out_y_meters,
00298                         double          &out_z_meters
00299                         ) );
00300 
00301 
00302         /** @}
00303             ======================================================================= */
00304 
00305 
00306         /** =======================================================================
00307            @name Miscellaneous
00308            @{ */
00309 
00310                 /** Returns the East-North-Up (ENU) coordinate system associated to the given point.
00311                   * This is the reference employed in geodeticToENU_WGS84
00312                   * \param only_angles If set to true, the (x,y,z) fields will be left zeroed.
00313                   * \sa geodeticToENU_WGS84
00314                   */
00315                 void TOPO_IMPEXP ENU_axes_from_WGS84(
00316                         double          in_longitude_reference_degrees,
00317                         double          in_latitude_reference_degrees,
00318                         double          in_height_reference_meters,
00319                         mrpt::math::TPose3D &out_ENU,
00320                         bool            only_angles = false
00321                         );
00322 
00323                 /** Returns the East-North-Up (ENU) coordinate system associated to the given point.
00324                   * This is the reference employed in coordinatesTransformation_WGS84
00325                   * \param only_angles If set to true, the (x,y,z) fields will be left zeroed.
00326                   * \sa geodeticToENU_WGS84
00327                   */
00328                 inline void ENU_axes_from_WGS84(
00329                         const TGeodeticCoords           &in_coords,
00330                         mrpt::math::TPose3D &out_ENU,
00331                         bool            only_angles = false
00332                         )
00333                 {
00334                         ENU_axes_from_WGS84(in_coords.lon,in_coords.lat,in_coords.height, out_ENU,only_angles);
00335                 }
00336 
00337         /** @}
00338             ======================================================================= */
00339 
00340 
00341         } // End of namespace
00342 
00343 } // End of namespace
00344 
00345 #endif



Page generated by Doxygen 1.7.3 for MRPT 0.9.4 SVN:exported at Tue Jan 25 21:56:31 UTC 2011