1New Functions
2==================
3
4Time Functions
5**********************************
6
7These are largely helper functions that make some functionality a little easier or more succinct.
8
9.. py:function:: gpstk.now([timeSystem=TimeSystem('UTC')])
10    :noindex:
11
12Returns the current time in the given TimeSystem. The default is in the UTC time system since the time is
13derived from calling SystemTime(). ::
14
15    >>> print gpstk.now()
16    2456490 72040524 0.000665000000000 UTC
17
18
19.. py:function:: gpstk.times(starttime, endtime[, seconds=0.0, days=0])
20    :noindex:
21
22This returns a generator of CommonTime objects that starts at starttime and advances
23by the seconds and days parameter each time. Special cases (no timestep parameters,
24negative parameters) are documented in the function's docstring and the quick reference section. ::
25
26    >>> start = gpstk.now()
27    >>> # wait a few seconds...
28    >>> end = gpstk.now()
29    >>> times = list(gpstk.times(start, end, seconds=1.0))
30    >>> for t in times:
31    ...     print t
32
33    2456527 60045625 0.000057000000000 UTC
34    2456527 60046625 0.000057000000000 UTC
35    2456527 60047625 0.000057000000000 UTC
36    2456527 60048625 0.000057000000000 UTC
37    2456527 60049625 0.000057000000000 UTC
38    2456527 60050625 0.000057000000000 UTC
39    2456527 60051625 0.000057000000000 UTC
40    2456527 60052625 0.000057000000000 UTC
41    2456527 60053625 0.000057000000000 UTC
42
43
44
45Position Functions
46**********************************
47Some helpful functions for creating Position objects more easily (with keyword arguments) were also added:
48
49.. py:function:: gpstk.cartesian([x=0.0, y=0.0, z=0.0, model=None, frame=ReferenceFrame('Unknown)'])
50    :noindex:
51
52    >>> print gpstk.spherical(radius=5, theta=45, phi=45)
53    45.00000000 deg 45.00000000 deg 5.0000 m
54
55.. autofunction:: gpstk.spherical([theta=0.0, phi=0.0, radius=0.0, model=None, frame=ReferenceFrame('Unknown')])
56    :noindex:
57
58.. autofunction:: gpstk.geodetic([latitude=0.0, longitude=0.0, height=0.0, model=None, frame=ReferenceFrame('Unknown')])
59    :noindex:
60
61.. autofunction:: gpstk.geocentric([latitude=0.0, longitude=0.0, radius=0.0, model=None, frame=ReferenceFrame('Unknown')])
62    :noindex:
63
64The next four functions are simply light wrappers over some relatively simple classes.
65The use of a entire class objects was warranted in C++, but they are not neccessary
66for typical python usage.
67
68.. autofunction:: gpstk.moonPosition
69    :noindex:
70
71    >>> print gpstk.moonPosition(gpstk.now())
72    (62424169.398472935, -365987646.51255625, -83100797.60563189)
73
74
75.. autofunction:: gpstk.sunPosition
76    :noindex:
77
78.. autofunction:: gpstk.poleTides
79    :noindex:
80
81.. autofunction:: gpstk.solidTides
82    :noindex:
83
84    >>> print gpstk.solidTides(gpstk.now(), gpstk.geodetic(latitude=29, longitude=95, height=0))
85    (0.1601640329929359, -0.0031534542100034955, -0.03016846270875466)
86
87
88
89.. _fileio_label:
90
91File I/O Functions
92*******************
93
94To replace the stream-oriented paradigm for file i/o used in the C++
95implementation, some thin wrapping was placed over the Stream objects.
96
97Because the i/o strategy was uniform across all file types in C++, the
98strategy is similarly uniform for the python bindings.
99
100As an example, to read a SP3 file: ::
101
102    >>> header, data = gpstk.readSP3('sp3_data.txt')
103
104
105And to write an SP3 file... ::
106
107    >>> gpstk.writeSP3('sp3_data.txt.new', header, data)
108
109
110In this case, header is a SP3Header. Data is a list of SP3Data objects.
111
112By default, the data returned is a generator expression - which means
113it closely mimics the C++ stream in that it only returns an object when it is
114needed. If you want a strictly evaluated list (all of the objects sit in memory)
115you can use the strict=True keyword argument or just translate the generator to
116a list yourself using the list() initializer with the generator as the argument.
117
118A common paradigm is to loop over all elements in the data and process them.
119As an example, to print all the data sets in a RINEX 3 Nav file: ::
120
121    header, data = gpstk.readRinex3Nav('rinex3nav_data.txt')
122    for d in data:
123        print d
124
125
126
127You can also add a filter to the read on the data objects using the filterfunction keyword argument.
128By default, it simply returns True, which includes all data objects in the output.
129
130For example, to get a generator of Rinex3NavData objects with only the PRNID of 3, you could use: ::
131
132    >>> isPRN3 = (lambda x: x.PRNID == 3)
133
134    >>> header, data = gpstk.readRinex3Nav('rinex3nav_data.txt', filterfunction=isPRN3)
135
136    >>> print data.next()
137    Sat: G03 TOE: 1274 367200.000 TOC: 1274 367200.000 codeflags:   1 L2Pflag:   0 IODC:  902 IODE:  134 HOWtime: 362376 FitInt:  4.000
138
139    >>> print data.next()
140    Sat: G03 TOE: 1274 374400.000 TOC: 1274 374400.000 codeflags:   1 L2Pflag:   0 IODC:  903 IODE:  135 HOWtime: 367206 FitInt:  4.000
141
142    >>> print data.next()
143    Sat: G03 TOE: 1274 381600.000 TOC: 1274 381600.000 codeflags:   1 L2Pflag:   0 IODC:  904 IODE:  136 HOWtime: 374406 FitInt:  4.000
144
145
146The following formats use this pattern (all read/write semantics are identical):
147
148* Rinex3Clock
149* Rinex3Nav
150* Rinex3Obs
151* RinexClock
152* RinexMet
153* RinexNav
154* RinexObs
155* SEM
156* SP3
157* Yuma
158
159Miscellaneous
160****************************
161
162Several of the constants in GPS_URA.hpp were C-style arrays. These could not be converted
163directly to Python lists (without code duplication), so functions were added that gave
164access to the underlying array.
165
166A C++ call to gpstk::SV_ACCURACY_GPS_MIN_INDEX[3] would become a Python statement of gpstk.constants.sv_accuracy_gps_min_index(3)
167
168