README.md 8.63 KB
Newer Older
1
README
2
------
3

4 5 6
Github - 
[![Build Status](https://travis-ci.org/SGL-UT/GPSTk.svg?branch=master)](https://travis-ci.org/SGL-UT/GPSTk)

Andrew Kuck's avatar
Andrew Kuck committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
NOTICE:
-------

On November 30, 2020 there was a push of many pending changes to the GPSTk 
repository.  We apologize for the long period without updates, the year 2020
has been a trying time in many respects.

The most obvious change has been a transition to a semantic versioning scheme
(semver.org).  This is intended to be an informal contract regarding the API
that is presented by our tools.  It should always be safe to update to the next 
version, so long as the major version number doesn't change.  
 
Releases containing API changes, however small, will result in a major version 
number increment. Releases containing new features will result in a minor 
version number increment. Releases containing only bug fixes will have a patch
number increment. 


25 26
Contents:
---------
27

28 29 30 31 32
* Introduction
* Description: GPSTk C++ Library
* Description: GPSTk C++ Applications
* Description: GPSTk Python Bindings
* Installation
33
* Testing
34 35 36 37
* Help & Docs
* Contribution guidelines
* Contributor list
* Credits & Lineage
38
* License
39 40 41 42 43 44 45 46 47 48


Introduction:
-------------

The GPS Toolkit (GPSTk) is an open-source (LGPL) project sponsored by
the Space and Geophysics Laboratory (SGL), part of the Applied Research 
Laboratories (ARL) at The University of Texas at Austin.

The primary goals of the GPSTk project are to:
49

50 51 52 53 54 55 56 57 58 59 60 61
* provide applications for use by the GNSS and satellite navigation community.
* provide a core library to facilitate the development of GNSS applications.


Description: GPSTk C++ Library:
-------------------------------

The GPSTk core library provides a number of models and algorithms found in GNSS
textbooks and classic papers, such as solving for the user position or estimating
atmospheric refraction. Common data formats such as RINEX are supported as well. 

There are several categories of functions in the GPSTk library:
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87

   1. GPS time. Conversion among time representations such as MJD, GPS week 
      and seconds of week, and many others.

   2. Ephemeris calculations. Position and clock interpolation for both
      broadcast and precise ephemerides.

   3. Atmospheric delay models. Includes ionosphere and troposphere models.

   4. Position solution. Includes an implementation of a Receiver Autonomous 
      Integrity Monitoring algorithm.

   5. Mathematics. Includes Matrix and Vector implementations, as well as
      interpolation and numerical integration.

   6. GNSS data structures. Data structures that contain observations mapped
      according to epochs, satellites, sources and types of observations.
      Appropriate processing classes are also provided, including a complete
      'Precise Point Positioning' (PPP) processing chain.

   7. Application framework. Includes processing command lines options,
      providing interactive help and working with file systems.

A more detailed description of the functionality provided by the GPSTk library 
can be found in the Doxygen documentation on the GPSTk website.

88 89
    http://www.gpstk.org/bin/view/Documentation/WebHome

90 91 92 93 94 95 96
The GPSTk Core Library and its associated test programs can be built 
independently of building the GPSTk Applications or Auxiliary Libraries.
The GPSTk Core Library source code contains no dependencies outside of the
GPSTk Core Library and Standard C++ and will build cleanly on all 
supported platforms.


97 98
Description: GPSTk C++ Applications:
------------------------------------
99

100
The GPSTk libraries are the foundation for the GPSTk applications suite.
101 102 103
The applications support greater depth of functionality to support research 
and development. The applications are almost entirely console based (i.e., 
without a graphical user interface). They can be grouped functionally into 
104
the following categories:
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141

   1. RINEX utilities - The RINEX utilities provide a set of applications 
      that can be used to examine, manipulate, and plot RINEX observation 
      files.

   2. Positioning - The positioning applications include two different 
      applications that perform standard pseudorange-based positioning and 
      two that implement differential phase-based solutions. 

   3. Residual analysis - A residual analysis application computes two types 
      of measurement residuals using a single receiver or two receivers in 
      a zero baseline configuration. 

   4. Ionospheric modeling - The ionospheric modeling applications utilize 
      the two frequency TEC estimate from the RINEX utilities and compute 
      a model of the ionosphere. 

   5. Signal Tracking Simulation - These utilities simulate the tracking 
      of GPS C/A and P-code.

   6. Basic transformations -  Conversions of time and coordinate systems.

   7. Observation data collection and conversion -  Translating receiver 
      specific data formats to RINEX.

   8. File comparison and validation - Differing observations files against 
     a truth source.

   9. Data editing - Simple editing like systematic removal of observations 
      by satellite, type or time and more advanced editing like cycle slip 
      detection and correction.

   10.Autonomous and relative positioning - Navigation and surveying 
      applications.


The GPSTk applications are dependent on the GPSTk libraries.  However, the 
142 143 144
GPSTk applications may also contain external dependencies.  Some applications 
may not build or run successfully on all platforms. 

145

146 147
Description: GPSTk Python Bindings:
-----------------------------------
148

149 150 151
The GPSTk python extension package provides access to the GPSTk C++ library 
from within python. It is built using SWIG and CMake, and installed with a 
standard setup.py script using the python distutils module.
152

153
For more details, see $GPSTK/python/bindings/swig/install_package/README.txt
154

155

156 157
Installation:
-------------
158

159
See the INSTALL.txt for details.
160

161
The most recent version of the GPSTk source code can be found here:
162

163
* http://www.gpstk.org
164 165
* https://github.com/SGL-UT/GPSTk
* http://sourceforge.net/projects/gpstk/
166

167 168
The tools used for the build and install frameworks are cross-platform.
These include CMake, SWIG, and python (distutils).
169

170
Automated build and install is supported on POSIX platforms with the 
171
supplied Bash script called build.sh. For help on script usage, 
172
run the script with the help flag:
173

174
    $ build.sh -h
175 176 177 178 179 180 181

For other platforms, such as Windows, please refer to comments and commands
in the same script, which document how we are using CMake, SWIG, and 
distutils for various steps in the build and install process.

To build and install the C++ library and applications on POSIX platforms:

182
* automated: run build.sh.
183
* manual: see the contents of build.sh for command examples on how you might run cmake and make to build and install the library.
184 185 186

To build and install the python bindings, you have two options:

187
* automated: python bindings automatically build with the build.sh. Use -P for install.
188
* manual build: see build.sh for examples on calling cmake and swig
189
* manual install: 
190

191 192 193 194 195 196

Testing:
--------

See the TESTING.txt for details.

197 198
	
Help & Docs:
199
------------
200

201 202
See the DOCUMENTATION.txt for details.

203 204
Additional documentation and resources can be found at http://www.gpstk.org/, 
including:
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230

* Source code and compiled binaries
* Coding examples
* Doxygen documentation
* System requirements and build instructions
* A users guide
* Publications
* Email lists
* Support question/answer
* Development process (including feature suggestions, bug tracking, schedule, testing, and developer documentation)
* Source code repository information
* GPSTk IRC channel
* Success stories

Credits & Lineage:
------------------

GPSTk is the by-product of GPS research conducted at ARL:UT since before the first 
satellite launched in 1978; it is the combined effort of many software 
engineers and scientists. In 2003 the research staff at ARL:UT decided to 
open source much of their basic GPS processing software as the GPSTk.

The development history is documented by a series of related publications: 

	http://www.gpstk.org/bin/view/Documentation/GPSTkPublications

231 232
See the AUTHORS.txt file for additional detail.

233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
License
-------

The source code provided by the GPSTk is distributed under the GNU LGPL, Version 3.

* This license gives all users the right to use and redistribute the code.
* Users of the GPSTk are not required to open their source, according to the LGPL.
* This makes the GPSTk a practical choice for commercial projects.
* Full text copies of the GPL (COPYING.txt) and the LGPL (COPYING.LESSER.txt) are included with the GPSTk distribution package. 

For more information about the GPL or LGP, please refer to the following:

* http://www.gnu.org/copyleft/lesser.html
* http://www.gnu.org/licenses/gpl-howto.html