gnsswire-antex 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,13 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ build/
6
+ dist/
7
+ *.egg-info/
8
+ # Specs are staged locally for reading; several are copyrighted and none are committed.
9
+ refs/*
10
+ !refs/README.md
11
+ .claude/settings.local.json
12
+ /AGENTS.md
13
+ /STATUS.md
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Trace Navigation LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,276 @@
1
+ Metadata-Version: 2.5
2
+ Name: gnsswire-antex
3
+ Version: 0.1.0
4
+ Summary: ANTEX 1.4 antenna calibration files (phase centre offsets and variations), read and written losslessly as fixed-column text fields.
5
+ Project-URL: Homepage, https://github.com/tracenav/gnsswire
6
+ Project-URL: Source, https://github.com/tracenav/gnsswire/tree/main/packages/antex
7
+ Project-URL: Changelog, https://github.com/tracenav/gnsswire/blob/main/RELEASES.md
8
+ Project-URL: Issues, https://github.com/tracenav/gnsswire/issues
9
+ Author: Trace Navigation
10
+ Maintainer-email: Jacob Armstrong <hi@jacobarm.com>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Scientific/Engineering :: GIS
24
+ Requires-Python: >=3.11
25
+ Description-Content-Type: text/markdown
26
+
27
+ # gnsswire-antex
28
+
29
+ ANTEX antenna calibration files for Python
30
+
31
+ [![tests](https://github.com/tracenav/gnsswire/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/tracenav/gnsswire/actions/workflows/test.yml)
32
+ [![PyPI](https://img.shields.io/pypi/v/gnsswire-antex)](https://pypi.org/project/gnsswire-antex/)
33
+
34
+ gnsswire-antex reads and writes ANTEX 1.4 files, the text format in which
35
+ the phase centre offsets and phase centre variations of GNSS receiver and
36
+ satellite antennas are exchanged (the IGS models `igs14.atx` and
37
+ `igs20.atx`, for example). It gives you:
38
+
39
+ - the header and every antenna: its type and serial number, its grid, its
40
+ validity, and per frequency the offsets and the pattern rows, with the
41
+ optional rms sections;
42
+ - a lossless round trip: `write(read(text)) == text` for every file `read`
43
+ accepts;
44
+ - every field as the text in its columns, and numeric fields as exact
45
+ integers on request, without floating point;
46
+ - one antenna looked up by type, radome and serial number, or by satellite
47
+ and epoch, without decoding the rest of the file.
48
+
49
+ It is part of [gnsswire](https://pypi.org/project/gnsswire/), codecs for
50
+ GNSS wire formats.
51
+
52
+ ## Installation
53
+
54
+ ```sh
55
+ $ pip install gnsswire-antex
56
+ ```
57
+
58
+ gnsswire-antex requires Python 3.11+ and has no dependencies. `pip install
59
+ gnsswire` installs it with every other format.
60
+
61
+ ## Usage
62
+
63
+ ### Read a file
64
+
65
+ `read(text)` gives an `AntexFile`: the header records, then each antenna.
66
+ The text is the file's, decoded (ANTEX files are ASCII; `encoding="latin-1"`
67
+ reads any of them):
68
+
69
+ ```python
70
+ from gnsswire import antex
71
+
72
+ text = (
73
+ " 1.4 M ANTEX VERSION / SYST\n"
74
+ "A PCV TYPE / REFANT\n"
75
+ " END OF HEADER\n"
76
+ " START OF ANTENNA\n"
77
+ "EXAMPLE_ANT NONE TYPE / SERIAL NO\n"
78
+ "ROBOT Example Agency 2 17-NOV-26 METH / BY / # / DATE\n"
79
+ " 120.0 DAZI\n"
80
+ " 0.0 90.0 45.0 ZEN1 / ZEN2 / DZEN\n"
81
+ " 1 # OF FREQUENCIES\n"
82
+ " G01 START OF FREQUENCY\n"
83
+ " 0.58 -0.37 91.25 NORTH / EAST / UP\n"
84
+ " NOAZI 0.00 -1.52 3.10\n"
85
+ " 0.0 0.00 -1.40 3.31\n"
86
+ " 120.0 0.00 -1.66 2.87\n"
87
+ " 240.0 0.00 -1.49 3.12\n"
88
+ " 360.0 0.00 -1.40 3.31\n"
89
+ " G01 END OF FREQUENCY\n"
90
+ " END OF ANTENNA\n"
91
+ )
92
+ file = antex.read(text) # for a file: antex.read(open(path, encoding="latin-1", newline="").read())
93
+ print(file.version, file.system, file.pcv_type.pcv_type.strip()) # 1.4 M A
94
+
95
+ antenna = file.antennas[0]
96
+ print(repr(antenna.type), repr(antenna.serial.strip())) # 'EXAMPLE_ANT NONE' ''
97
+ print(antenna.grid.zen1, antenna.grid.zen2, antenna.grid.dzen, antenna.dazi)
98
+ # 0.0 90.0 45.0 120.0
99
+ print(antenna.zeniths, antenna.azimuths) # (0, 450, 900) (0, 1200, 2400, 3600), in 0.1 degree
100
+ ```
101
+
102
+ A blank serial number means every antenna of the type. A satellite
103
+ antenna has the same records: its `serial` is the satellite code (`G05`),
104
+ and `antenna.type_serial` also holds its `svn` and `cospar` fields;
105
+ `antenna.valid_from` and `antenna.valid_until` give its validity period,
106
+ `antenna.sinex_code` and `antenna.comments` the rest.
107
+
108
+ ### Offsets and pattern of a frequency
109
+
110
+ `antenna.frequencies` holds the frequency sections by code. Each has the
111
+ NORTH / EAST / UP fields (`offset`), the non-azimuth-dependent row
112
+ (`noazi`) and one row per azimuth (`rows`; none when DAZI is 0.0), whose
113
+ values run from ZEN1 to ZEN2:
114
+
115
+ ```python
116
+ g01 = antenna.frequencies["G01"]
117
+ print(g01.offset.north, g01.offset.east, g01.offset.up) # 0.58 -0.37 91.25
118
+ print(g01.noazi.values) # (' 0.00', ' -1.52', ' 3.10')
119
+ for row in g01.rows:
120
+ print(row.azimuth, row.values) # 120.0 (' 0.00', ' -1.66', ' 2.87'), ...
121
+ print(antenna.rms) # {}: this antenna has no rms sections
122
+ ```
123
+
124
+ For a satellite antenna the three offset fields are X, Y and Z, and the
125
+ grid is in nadir angle. rms sections (START OF FREQ RMS), where a file has
126
+ them, are in `antenna.rms`, by the same codes and with the same layout.
127
+
128
+ ### Exact numbers
129
+
130
+ Every field is the text in the record's columns, blanks included, so
131
+ nothing is lost. `number(field, decimals)` gives a numeric field as the
132
+ integer of its digits, without floating point. Offsets and pattern values
133
+ are millimetres with two decimals, so in units of 0.01 mm:
134
+
135
+ ```python
136
+ print(antex.number(g01.offset.up, 2)) # 9125
137
+ print([antex.number(v, 2) for v in g01.rows[1].values]) # [0, -166, 287]
138
+ print(antex.number(antenna.method.count)) # 2 antennas calibrated
139
+ ```
140
+
141
+ Nothing is scaled or given a sign here; how the values are applied is
142
+ section 3 of the ANTEX document.
143
+
144
+ ### Write it back
145
+
146
+ `write(file)` gives the text back, exactly as read:
147
+
148
+ ```python
149
+ print(antex.write(file) == text) # True
150
+ ```
151
+
152
+ Every labelled line is a `Record` (its 60 columns of content and its
153
+ label); `fields(record)` gives the content as the dataclass of its columns
154
+ and `record(label, fields)` builds a record from one, for a file made or
155
+ changed in Python:
156
+
157
+ ```python
158
+ from dataclasses import replace
159
+
160
+ dazi = antenna.records[3]
161
+ print(antex.fields(dazi)) # Dazi(dazi=' 120.0', blank=' ... ')
162
+ print(antex.record("DAZI", antex.Dazi(" 120.0")) == dazi) # True
163
+
164
+ # Records are frozen: change one with replace(). write() checks the result as read() does.
165
+ renamed = replace(antenna, records=(
166
+ *antenna.records[:1],
167
+ antex.record("TYPE / SERIAL NO", antex.TypeSerial(
168
+ "EXAMPLE_ANT NONE", "SN 0042".ljust(20), " " * 10, " " * 10)),
169
+ *antenna.records[2:]))
170
+ print(antex.read(antex.write(replace(file, antennas=(renamed,)))).antennas[0].serial.strip())
171
+ # SN 0042
172
+ ```
173
+
174
+ A file of another format version raises `Unsupported`; text that does not
175
+ follow the format (records out of order, a row that disagrees with the
176
+ grid) raises `Invalid`. Both, and the error `number` raises for a field
177
+ that is not a number of its format, derive from `antex.Error`, a
178
+ `ValueError`.
179
+
180
+ ### Large files
181
+
182
+ Reading is one pass over the lines. The IGS model `igs20.atx` (62 MB,
183
+ 934 antennas, 350,000 pattern rows) reads in a little over a second and
184
+ writes in about three (CPython 3.14, a 2020s laptop); `write` takes longer
185
+ because it reads its own output back to check it.
186
+
187
+ ### Look up one antenna
188
+
189
+ `open_index(source)` takes a path, a binary stream or the file's bytes
190
+ (gzip, bzip2 or zip compressed or not). It reads the header at once; on
191
+ first use it finds every antenna section by its labels, and decodes only
192
+ the one asked for, by the same rules as `read`, which gives the same
193
+ `Antenna`. `antenna(type, radome, serial)` finds a receiver antenna, a
194
+ serial number without its own calibration giving the type's;
195
+ `satellite(code, epoch)` the antenna of a satellite valid at an epoch (GPS
196
+ time, VALID FROM and VALID UNTIL included):
197
+
198
+ ```python
199
+ import datetime as dt
200
+
201
+ satellite = (
202
+ " START OF ANTENNA\n"
203
+ "BLOCK IIF G01 G063 2011-036A TYPE / SERIAL NO\n"
204
+ "EXAMPLE Example Agency 0 17-NOV-26 METH / BY / # / DATE\n"
205
+ " 0.0 DAZI\n"
206
+ " 0.0 14.0 7.0 ZEN1 / ZEN2 / DZEN\n"
207
+ " 1 # OF FREQUENCIES\n"
208
+ " 2011 7 16 0 0 0.0000000 VALID FROM\n"
209
+ " G01 START OF FREQUENCY\n"
210
+ " 394.00 0.00 1500.00 NORTH / EAST / UP\n"
211
+ " NOAZI -0.80 -0.40 0.20\n"
212
+ " G01 END OF FREQUENCY\n"
213
+ " END OF ANTENNA\n"
214
+ )
215
+ data = (text + satellite).encode() # or a path: antex.open_index("igs20.atx")
216
+ with antex.open_index(data) as index:
217
+ print([(e.type, e.serial.strip()) for e in index.entries])
218
+ # [('EXAMPLE_ANT NONE', ''), ('BLOCK IIF ', 'G01')]
219
+ ant = index.antenna("EXAMPLE_ANT", "NONE")
220
+ print(ant == file.antennas[0]) # True
221
+ print(index.antenna("EXAMPLE_ANT", "NONE", "SN 0042") == ant) # True: the type's mean
222
+ sat = index.satellite("G01", dt.datetime(2026, 11, 18))
223
+ print(sat.frequencies["G01"].offset.up) # 1500.00
224
+ print(index.satellite("G01", dt.datetime(2010, 1, 1))) # None
225
+ ```
226
+
227
+ `entries` lists every section with its TYPE / SERIAL NO, VALID FROM and
228
+ VALID UNTIL and its line in the file. A section that breaks the format is
229
+ refused when it is asked for (`Invalid`), not before. On a synthetic file
230
+ of 30 MB (432 antennas), opening the index and two lookups take about 40
231
+ ms, a further lookup about 1 ms; `read` takes about 0.5 s.
232
+
233
+ ## Records
234
+
235
+ Every record of section 4 of "ANTEX: The Antenna Exchange Format, Version
236
+ 1.4" (Rothacher and Schmid, 15 September 2010):
237
+
238
+ | Record | Class | Where |
239
+ |---|---|---|
240
+ | ANTEX VERSION / SYST | `Version` | `AntexFile.header`, `.version`, `.system` |
241
+ | PCV TYPE / REFANT | `PcvType` | `AntexFile.pcv_type` |
242
+ | COMMENT | `Comment` | `AntexFile.comments`, `Antenna.comments` |
243
+ | END OF HEADER, START OF ANTENNA, END OF ANTENNA | `Blank` | `AntexFile.header`, `Antenna.records`, `Antenna.end` |
244
+ | TYPE / SERIAL NO | `TypeSerial` | `Antenna.type_serial`, `.type`, `.serial` |
245
+ | METH / BY / # / DATE | `Method` | `Antenna.method` |
246
+ | DAZI | `Dazi` | `Antenna.dazi`, `.azimuths` |
247
+ | ZEN1 / ZEN2 / DZEN | `Grid` | `Antenna.grid`, `.zeniths` |
248
+ | # OF FREQUENCIES | `Frequencies` | `Antenna.records` |
249
+ | VALID FROM, VALID UNTIL | `Epoch` | `Antenna.valid_from`, `.valid_until` |
250
+ | SINEX CODE | `SinexCode` | `Antenna.sinex_code` |
251
+ | START OF FREQUENCY, END OF FREQUENCY | `FrequencyCode` | `Pattern.start`, `.end`, `.code`; `Antenna.frequencies` |
252
+ | NORTH / EAST / UP | `Offset` | `Pattern.neu`, `.offset` |
253
+ | NOAZI row, azimuth rows | `Row` | `Pattern.noazi`, `.rows` |
254
+ | START OF FREQ RMS, END OF FREQ RMS | `FrequencyCode` | `Pattern.rms`; `Antenna.rms` |
255
+
256
+ `TABLE` maps each label to its class, and `FREQUENCIES` lists the
257
+ frequency codes the document names (`G01` is L1, `E05` is E5a, and so on);
258
+ other codes, which later RINEX versions define, are read the same way.
259
+
260
+ ## Documentation
261
+
262
+ What gnsswire-antex checks and does not check, what its tests rest on and
263
+ the readings it takes where its specification is ambiguous are under
264
+ [Limitations](https://github.com/tracenav/gnsswire#gnsswire-antex) in the
265
+ [repository README](https://github.com/tracenav/gnsswire#readme), with the
266
+ interface every gnsswire format shares and the version policy. Release
267
+ notes are in [RELEASES.md](https://github.com/tracenav/gnsswire/blob/main/RELEASES.md).
268
+
269
+ ## Contribute
270
+
271
+ Report bugs and request formats in the
272
+ [issue tracker](https://github.com/tracenav/gnsswire/issues).
273
+
274
+ ## Licence
275
+
276
+ MIT.
@@ -0,0 +1,250 @@
1
+ # gnsswire-antex
2
+
3
+ ANTEX antenna calibration files for Python
4
+
5
+ [![tests](https://github.com/tracenav/gnsswire/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/tracenav/gnsswire/actions/workflows/test.yml)
6
+ [![PyPI](https://img.shields.io/pypi/v/gnsswire-antex)](https://pypi.org/project/gnsswire-antex/)
7
+
8
+ gnsswire-antex reads and writes ANTEX 1.4 files, the text format in which
9
+ the phase centre offsets and phase centre variations of GNSS receiver and
10
+ satellite antennas are exchanged (the IGS models `igs14.atx` and
11
+ `igs20.atx`, for example). It gives you:
12
+
13
+ - the header and every antenna: its type and serial number, its grid, its
14
+ validity, and per frequency the offsets and the pattern rows, with the
15
+ optional rms sections;
16
+ - a lossless round trip: `write(read(text)) == text` for every file `read`
17
+ accepts;
18
+ - every field as the text in its columns, and numeric fields as exact
19
+ integers on request, without floating point;
20
+ - one antenna looked up by type, radome and serial number, or by satellite
21
+ and epoch, without decoding the rest of the file.
22
+
23
+ It is part of [gnsswire](https://pypi.org/project/gnsswire/), codecs for
24
+ GNSS wire formats.
25
+
26
+ ## Installation
27
+
28
+ ```sh
29
+ $ pip install gnsswire-antex
30
+ ```
31
+
32
+ gnsswire-antex requires Python 3.11+ and has no dependencies. `pip install
33
+ gnsswire` installs it with every other format.
34
+
35
+ ## Usage
36
+
37
+ ### Read a file
38
+
39
+ `read(text)` gives an `AntexFile`: the header records, then each antenna.
40
+ The text is the file's, decoded (ANTEX files are ASCII; `encoding="latin-1"`
41
+ reads any of them):
42
+
43
+ ```python
44
+ from gnsswire import antex
45
+
46
+ text = (
47
+ " 1.4 M ANTEX VERSION / SYST\n"
48
+ "A PCV TYPE / REFANT\n"
49
+ " END OF HEADER\n"
50
+ " START OF ANTENNA\n"
51
+ "EXAMPLE_ANT NONE TYPE / SERIAL NO\n"
52
+ "ROBOT Example Agency 2 17-NOV-26 METH / BY / # / DATE\n"
53
+ " 120.0 DAZI\n"
54
+ " 0.0 90.0 45.0 ZEN1 / ZEN2 / DZEN\n"
55
+ " 1 # OF FREQUENCIES\n"
56
+ " G01 START OF FREQUENCY\n"
57
+ " 0.58 -0.37 91.25 NORTH / EAST / UP\n"
58
+ " NOAZI 0.00 -1.52 3.10\n"
59
+ " 0.0 0.00 -1.40 3.31\n"
60
+ " 120.0 0.00 -1.66 2.87\n"
61
+ " 240.0 0.00 -1.49 3.12\n"
62
+ " 360.0 0.00 -1.40 3.31\n"
63
+ " G01 END OF FREQUENCY\n"
64
+ " END OF ANTENNA\n"
65
+ )
66
+ file = antex.read(text) # for a file: antex.read(open(path, encoding="latin-1", newline="").read())
67
+ print(file.version, file.system, file.pcv_type.pcv_type.strip()) # 1.4 M A
68
+
69
+ antenna = file.antennas[0]
70
+ print(repr(antenna.type), repr(antenna.serial.strip())) # 'EXAMPLE_ANT NONE' ''
71
+ print(antenna.grid.zen1, antenna.grid.zen2, antenna.grid.dzen, antenna.dazi)
72
+ # 0.0 90.0 45.0 120.0
73
+ print(antenna.zeniths, antenna.azimuths) # (0, 450, 900) (0, 1200, 2400, 3600), in 0.1 degree
74
+ ```
75
+
76
+ A blank serial number means every antenna of the type. A satellite
77
+ antenna has the same records: its `serial` is the satellite code (`G05`),
78
+ and `antenna.type_serial` also holds its `svn` and `cospar` fields;
79
+ `antenna.valid_from` and `antenna.valid_until` give its validity period,
80
+ `antenna.sinex_code` and `antenna.comments` the rest.
81
+
82
+ ### Offsets and pattern of a frequency
83
+
84
+ `antenna.frequencies` holds the frequency sections by code. Each has the
85
+ NORTH / EAST / UP fields (`offset`), the non-azimuth-dependent row
86
+ (`noazi`) and one row per azimuth (`rows`; none when DAZI is 0.0), whose
87
+ values run from ZEN1 to ZEN2:
88
+
89
+ ```python
90
+ g01 = antenna.frequencies["G01"]
91
+ print(g01.offset.north, g01.offset.east, g01.offset.up) # 0.58 -0.37 91.25
92
+ print(g01.noazi.values) # (' 0.00', ' -1.52', ' 3.10')
93
+ for row in g01.rows:
94
+ print(row.azimuth, row.values) # 120.0 (' 0.00', ' -1.66', ' 2.87'), ...
95
+ print(antenna.rms) # {}: this antenna has no rms sections
96
+ ```
97
+
98
+ For a satellite antenna the three offset fields are X, Y and Z, and the
99
+ grid is in nadir angle. rms sections (START OF FREQ RMS), where a file has
100
+ them, are in `antenna.rms`, by the same codes and with the same layout.
101
+
102
+ ### Exact numbers
103
+
104
+ Every field is the text in the record's columns, blanks included, so
105
+ nothing is lost. `number(field, decimals)` gives a numeric field as the
106
+ integer of its digits, without floating point. Offsets and pattern values
107
+ are millimetres with two decimals, so in units of 0.01 mm:
108
+
109
+ ```python
110
+ print(antex.number(g01.offset.up, 2)) # 9125
111
+ print([antex.number(v, 2) for v in g01.rows[1].values]) # [0, -166, 287]
112
+ print(antex.number(antenna.method.count)) # 2 antennas calibrated
113
+ ```
114
+
115
+ Nothing is scaled or given a sign here; how the values are applied is
116
+ section 3 of the ANTEX document.
117
+
118
+ ### Write it back
119
+
120
+ `write(file)` gives the text back, exactly as read:
121
+
122
+ ```python
123
+ print(antex.write(file) == text) # True
124
+ ```
125
+
126
+ Every labelled line is a `Record` (its 60 columns of content and its
127
+ label); `fields(record)` gives the content as the dataclass of its columns
128
+ and `record(label, fields)` builds a record from one, for a file made or
129
+ changed in Python:
130
+
131
+ ```python
132
+ from dataclasses import replace
133
+
134
+ dazi = antenna.records[3]
135
+ print(antex.fields(dazi)) # Dazi(dazi=' 120.0', blank=' ... ')
136
+ print(antex.record("DAZI", antex.Dazi(" 120.0")) == dazi) # True
137
+
138
+ # Records are frozen: change one with replace(). write() checks the result as read() does.
139
+ renamed = replace(antenna, records=(
140
+ *antenna.records[:1],
141
+ antex.record("TYPE / SERIAL NO", antex.TypeSerial(
142
+ "EXAMPLE_ANT NONE", "SN 0042".ljust(20), " " * 10, " " * 10)),
143
+ *antenna.records[2:]))
144
+ print(antex.read(antex.write(replace(file, antennas=(renamed,)))).antennas[0].serial.strip())
145
+ # SN 0042
146
+ ```
147
+
148
+ A file of another format version raises `Unsupported`; text that does not
149
+ follow the format (records out of order, a row that disagrees with the
150
+ grid) raises `Invalid`. Both, and the error `number` raises for a field
151
+ that is not a number of its format, derive from `antex.Error`, a
152
+ `ValueError`.
153
+
154
+ ### Large files
155
+
156
+ Reading is one pass over the lines. The IGS model `igs20.atx` (62 MB,
157
+ 934 antennas, 350,000 pattern rows) reads in a little over a second and
158
+ writes in about three (CPython 3.14, a 2020s laptop); `write` takes longer
159
+ because it reads its own output back to check it.
160
+
161
+ ### Look up one antenna
162
+
163
+ `open_index(source)` takes a path, a binary stream or the file's bytes
164
+ (gzip, bzip2 or zip compressed or not). It reads the header at once; on
165
+ first use it finds every antenna section by its labels, and decodes only
166
+ the one asked for, by the same rules as `read`, which gives the same
167
+ `Antenna`. `antenna(type, radome, serial)` finds a receiver antenna, a
168
+ serial number without its own calibration giving the type's;
169
+ `satellite(code, epoch)` the antenna of a satellite valid at an epoch (GPS
170
+ time, VALID FROM and VALID UNTIL included):
171
+
172
+ ```python
173
+ import datetime as dt
174
+
175
+ satellite = (
176
+ " START OF ANTENNA\n"
177
+ "BLOCK IIF G01 G063 2011-036A TYPE / SERIAL NO\n"
178
+ "EXAMPLE Example Agency 0 17-NOV-26 METH / BY / # / DATE\n"
179
+ " 0.0 DAZI\n"
180
+ " 0.0 14.0 7.0 ZEN1 / ZEN2 / DZEN\n"
181
+ " 1 # OF FREQUENCIES\n"
182
+ " 2011 7 16 0 0 0.0000000 VALID FROM\n"
183
+ " G01 START OF FREQUENCY\n"
184
+ " 394.00 0.00 1500.00 NORTH / EAST / UP\n"
185
+ " NOAZI -0.80 -0.40 0.20\n"
186
+ " G01 END OF FREQUENCY\n"
187
+ " END OF ANTENNA\n"
188
+ )
189
+ data = (text + satellite).encode() # or a path: antex.open_index("igs20.atx")
190
+ with antex.open_index(data) as index:
191
+ print([(e.type, e.serial.strip()) for e in index.entries])
192
+ # [('EXAMPLE_ANT NONE', ''), ('BLOCK IIF ', 'G01')]
193
+ ant = index.antenna("EXAMPLE_ANT", "NONE")
194
+ print(ant == file.antennas[0]) # True
195
+ print(index.antenna("EXAMPLE_ANT", "NONE", "SN 0042") == ant) # True: the type's mean
196
+ sat = index.satellite("G01", dt.datetime(2026, 11, 18))
197
+ print(sat.frequencies["G01"].offset.up) # 1500.00
198
+ print(index.satellite("G01", dt.datetime(2010, 1, 1))) # None
199
+ ```
200
+
201
+ `entries` lists every section with its TYPE / SERIAL NO, VALID FROM and
202
+ VALID UNTIL and its line in the file. A section that breaks the format is
203
+ refused when it is asked for (`Invalid`), not before. On a synthetic file
204
+ of 30 MB (432 antennas), opening the index and two lookups take about 40
205
+ ms, a further lookup about 1 ms; `read` takes about 0.5 s.
206
+
207
+ ## Records
208
+
209
+ Every record of section 4 of "ANTEX: The Antenna Exchange Format, Version
210
+ 1.4" (Rothacher and Schmid, 15 September 2010):
211
+
212
+ | Record | Class | Where |
213
+ |---|---|---|
214
+ | ANTEX VERSION / SYST | `Version` | `AntexFile.header`, `.version`, `.system` |
215
+ | PCV TYPE / REFANT | `PcvType` | `AntexFile.pcv_type` |
216
+ | COMMENT | `Comment` | `AntexFile.comments`, `Antenna.comments` |
217
+ | END OF HEADER, START OF ANTENNA, END OF ANTENNA | `Blank` | `AntexFile.header`, `Antenna.records`, `Antenna.end` |
218
+ | TYPE / SERIAL NO | `TypeSerial` | `Antenna.type_serial`, `.type`, `.serial` |
219
+ | METH / BY / # / DATE | `Method` | `Antenna.method` |
220
+ | DAZI | `Dazi` | `Antenna.dazi`, `.azimuths` |
221
+ | ZEN1 / ZEN2 / DZEN | `Grid` | `Antenna.grid`, `.zeniths` |
222
+ | # OF FREQUENCIES | `Frequencies` | `Antenna.records` |
223
+ | VALID FROM, VALID UNTIL | `Epoch` | `Antenna.valid_from`, `.valid_until` |
224
+ | SINEX CODE | `SinexCode` | `Antenna.sinex_code` |
225
+ | START OF FREQUENCY, END OF FREQUENCY | `FrequencyCode` | `Pattern.start`, `.end`, `.code`; `Antenna.frequencies` |
226
+ | NORTH / EAST / UP | `Offset` | `Pattern.neu`, `.offset` |
227
+ | NOAZI row, azimuth rows | `Row` | `Pattern.noazi`, `.rows` |
228
+ | START OF FREQ RMS, END OF FREQ RMS | `FrequencyCode` | `Pattern.rms`; `Antenna.rms` |
229
+
230
+ `TABLE` maps each label to its class, and `FREQUENCIES` lists the
231
+ frequency codes the document names (`G01` is L1, `E05` is E5a, and so on);
232
+ other codes, which later RINEX versions define, are read the same way.
233
+
234
+ ## Documentation
235
+
236
+ What gnsswire-antex checks and does not check, what its tests rest on and
237
+ the readings it takes where its specification is ambiguous are under
238
+ [Limitations](https://github.com/tracenav/gnsswire#gnsswire-antex) in the
239
+ [repository README](https://github.com/tracenav/gnsswire#readme), with the
240
+ interface every gnsswire format shares and the version policy. Release
241
+ notes are in [RELEASES.md](https://github.com/tracenav/gnsswire/blob/main/RELEASES.md).
242
+
243
+ ## Contribute
244
+
245
+ Report bugs and request formats in the
246
+ [issue tracker](https://github.com/tracenav/gnsswire/issues).
247
+
248
+ ## Licence
249
+
250
+ MIT.
@@ -0,0 +1,38 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"] # 1.27: PEP 639 licence metadata
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "gnsswire-antex"
7
+ version = "0.1.0"
8
+ description = "ANTEX 1.4 antenna calibration files (phase centre offsets and variations), read and written losslessly as fixed-column text fields."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.11"
13
+ authors = [{ name = "Trace Navigation" }]
14
+ maintainers = [{ name = "Jacob Armstrong", email = "hi@jacobarm.com" }]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Intended Audience :: Developers",
18
+ "Intended Audience :: Science/Research",
19
+ "Operating System :: OS Independent",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3 :: Only",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Topic :: Scientific/Engineering :: GIS",
27
+ ]
28
+ dependencies = []
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/tracenav/gnsswire"
32
+ Source = "https://github.com/tracenav/gnsswire/tree/main/packages/antex"
33
+ Changelog = "https://github.com/tracenav/gnsswire/blob/main/RELEASES.md"
34
+ Issues = "https://github.com/tracenav/gnsswire/issues"
35
+
36
+ # gnsswire is a namespace shared by several distributions: no __init__.py at that level.
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["src/gnsswire"]
@@ -0,0 +1,71 @@
1
+ """ANTEX 1.4 antenna calibration files: text to records of text fields and back.
2
+
3
+ An ANTEX file holds, per receiver or satellite antenna and per frequency,
4
+ the phase centre offset and the phase centre variations on a grid of zenith
5
+ (or nadir) and azimuth angles. It is read whole with :func:`read` and
6
+ written with :func:`write`, and ``write(read(text)) == text`` for every file
7
+ this module accepts. Every labelled line is a :class:`Record` (content and
8
+ label), every line of pattern values a :class:`Row`, as the text of their
9
+ columns; :func:`fields` gives a record's content as the frozen dataclass of
10
+ its columns, and :func:`number` a numeric field as the integer of its
11
+ digits. Nothing is scaled: offsets and pattern values are the file's
12
+ millimetres with two decimals, angles its degrees with one.
13
+
14
+ One antenna is looked up without decoding the others with
15
+ :func:`open_index`: by antenna type, radome and serial number, or by
16
+ satellite and epoch (:class:`AntexIndex`, ``_index``).
17
+
18
+ Source: "ANTEX: The Antenna Exchange Format, Version 1.4" (M. Rothacher,
19
+ R. Schmid, 15 September 2010), section 4; the readings taken are in
20
+ ``_file`` and ``_records``.
21
+
22
+ Errors: every exception this codec raises for a file it cannot read or
23
+ records it cannot write is an :class:`Error` (a ``ValueError``):
24
+ :class:`Invalid`, :class:`Unsupported` (another format version), and the
25
+ error :func:`number` raises for a field that is not a number of its format.
26
+ """
27
+
28
+ from ._file import (
29
+ FREQUENCIES,
30
+ SYSTEMS,
31
+ Antenna,
32
+ AntexFile,
33
+ Pattern,
34
+ read,
35
+ write,
36
+ )
37
+ from ._index import AntexIndex, IndexEntry, open_index
38
+ from ._records import (
39
+ NOAZI,
40
+ TABLE,
41
+ Blank,
42
+ Col,
43
+ Comment,
44
+ Dazi,
45
+ Epoch,
46
+ Error,
47
+ Frequencies,
48
+ FrequencyCode,
49
+ Grid,
50
+ Invalid,
51
+ Method,
52
+ Offset,
53
+ PcvType,
54
+ Record,
55
+ Row,
56
+ SinexCode,
57
+ TypeSerial,
58
+ Unsupported,
59
+ Version,
60
+ columns,
61
+ fields,
62
+ number,
63
+ record,
64
+ )
65
+
66
+ __all__ = ["FREQUENCIES", "NOAZI", "SYSTEMS", "TABLE", "Antenna", "AntexFile", "Blank", "Col",
67
+ "Comment", "Dazi", "Epoch", "Error", "Frequencies", "FrequencyCode", "Grid",
68
+ "Invalid", "Method", "Offset", "Pattern", "PcvType", "Record", "Row", "SinexCode",
69
+ "TypeSerial", "Unsupported", "Version", "columns", "fields", "number", "record",
70
+ "read", "write"]
71
+ __all__ += ["AntexIndex", "IndexEntry", "open_index"]