Updated Cython bindings for libswiftnav.

(Also known as the "A bird in the hand is worth two in the bush"
commit).

A massive monolithic commit (sorry!) containing:
- Updated coverage on bindings
- Removes c-specific Cython declaration files and other detritus
- Very mild unit test coverage on ported structs and functions

Some notes:
- Documentation is still lacking, but perhaps we can just
  point people at the corresponding C documentation or something.
- Some of the changes here are trying to minimize boiler plate, such
  as struct initialization for CPython wrapper objects. Many of the
  Cython objects are missing boilerplate setters and getters, but
  hopefully that can be handled some more nicer way.
- Calling conventions are a bit inconsistent in the bindings and the
  underlying C library. See, I & Q quadratures vs complex p in the
  tracking loop stuff: track.c.

/cc @mfine @fnoble @benjamin0 @kovach @JoshuaGross @henryhallam
@jacobmcnamee @gsmcmullin @akleeman

Author: mookerji

.travis.yml

@@ -9,9 +9,16 @@ before_install:
   - sudo add-apt-repository --yes ppa:kalakris/cmake
   - travis_retry sudo apt-get update -qq
   - sudo apt-get install cmake check
+  - export LD_LIBRARY_PATH=/usr/local/lib
 
 script:
+  # Test libswiftnav
   - mkdir build
   - cd build/
   - cmake ../
   - make
+  - sudo make install
+  # Test libswiftnav-python
+  - cd ../python
+  - sudo pip install tox
+  - tox

python/README.rst

@@ -39,9 +39,15 @@ To install libswiftnav-python (from the root of the source tree)::
     $ python setup.py build
     $ (sudo) python setup.py install
 
+
 Building Documentation
 ----------------------
 
+Much of this library provides bindings for functions in
+libswiftnav. Please see the accompanying comments and implementation
+of the C source for additional details that might be missing in this
+package.
+
 Building the documentation requires the libswiftnav-python source code
 and some additional packages:
 

python/setup.py

@@ -5,11 +5,11 @@
   version = get_git_version(),
   description = 'Python bindings to the libswiftnav library.',
   license = 'LGPLv3',
-  url = 'http://www.swift-nav.com',
+  url = 'http://www.swiftnav.com',
   author = 'Swift Navigation Inc.',
-  author_email = 'info@swift-nav.com',
-  maintainer = 'Fergus Noble',
-  maintainer_email = 'fergus@swift-nav.com',
+  author_email = 'dev@swiftnav.com',
+  maintainer = 'Swift Navigation',
+  maintainer_email = 'dev@swiftnav.com',
   packages = ['swiftnav'],
 )
 
@@ -27,26 +27,37 @@ def make_extension(ext_name):
     ext_path = ext_name.replace('.', os.path.sep) + '.pyx'
     return Extension(
       ext_name, [ext_path],
-      include_dirs = [np.get_include(), '.'],
+      include_dirs = [np.get_include(), '.', '../include/libswiftnav/'],
       extra_compile_args = ['-O0', '-g'],
       extra_link_args = ['-g'],
       libraries = ['m', 'swiftnav'],
     )
   ext_names = [
+    'swiftnav.edc',
+    'swiftnav.signal',
     'swiftnav.coord_system',
+    'swiftnav.constants',
     'swiftnav.nav_msg',
     'swiftnav.pvt',
     'swiftnav.correlate',
     'swiftnav.track',
     'swiftnav.almanac',
-    'swiftnav.lam',
+    'swiftnav.lambda_',
     'swiftnav.ephemeris',
     'swiftnav.linear_algebra',
     'swiftnav.amb_kf',
     'swiftnav.gpstime',
     'swiftnav.observation',
     'swiftnav.dgnss_management',
-    'swiftnav.ambiguity_test'
+    'swiftnav.ambiguity_test',
+    'swiftnav.baseline',
+    'swiftnav.bits',
+    'swiftnav.filter_utils',
+    'swiftnav.memory_pool',
+    'swiftnav.prns',
+    'swiftnav.sats_management',
+    'swiftnav.tropo',
+    'swiftnav.set',
   ]
   extensions = [make_extension(name) for name in ext_names]
   setup_args['ext_modules'] = extensions

python/swiftnav/almanac.pxd

@@ -1,4 +1,4 @@
-# Copyright (C) 2014 Swift Navigation Inc.
+# Copyright (C) 2015 Swift Navigation Inc.
 #
 # This source is subject to the license found in the file 'LICENSE' which must
 # be be distributed together with this source. All other rights reserved.
@@ -7,7 +7,44 @@
 # EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
 # WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 
-cimport almanac_c
+from common cimport *
+from signal cimport *
+
+cdef extern from "libswiftnav/almanac.h":
+  ctypedef struct almanac_gps_t:
+    double ecc
+    double toa
+    double inc
+    double rora
+    double a
+    double raaw
+    double argp
+    double ma
+    double af0
+    double af1
+    u16 week
+
+  ctypedef struct almanac_sbas_t:
+    u8 data_id
+    u16 x
+    u16 y
+    u16 z
+    u8 x_rate
+    u8 y_rate
+    u8 z_rate
+    u16 t0
+
+  ctypedef struct almanac_t:
+    gnss_signal_t sid
+    u8 healthy
+    u8 valid
+    # HACK: Actually an anonymous union in libswiftnat!
+    almanac_gps_t gps
+    almanac_sbas_t sbas
+
+  void calc_sat_state_almanac(almanac_t* alm, double t, s16 week, double pos[3], double vel[3])
+  void calc_sat_az_el_almanac(almanac_t* alm, double t, s16 week, double ref[3], double* az, double* el)
+  double calc_sat_doppler_almanac(almanac_t* alm, double t, s16 week, double ref[3])
 
 cdef class Almanac:
-  cdef almanac_c.almanac_t almanac
+  cdef almanac_t _thisptr

python/swiftnav/almanac.pyx

@@ -9,64 +9,39 @@
 
 # cython: embedsignature=True
 
-import numpy as np
+"""Almanac
+
+Functions and calculations related to the GPS almanac.
+
+Note: All positions are referenced to the WGS84 coordinate system.
+"""
+
+from common cimport *
+from fmt_utils import fmt_repr
+from libc.string cimport memset
 cimport numpy as np
-cimport almanac_c
+import numpy as np
 
 cdef class Almanac:
-  """
-  Wraps the :libswiftnav:`almanac_t` structure and associated functions for
-  performing calculations with almanacs.
-
-  Parameters
-  ----------
-  ecc : float
-    Eccentricity in radians.
-  toa : float
-    Time of Applicability in seconds since Sunday.
-  inc : float
-    Inclination in radians.
-  rora : float
-    Rate of Right Ascension in radians/sec.
-  a : float
-    Semi-major axis in meters.
-  raaw : float
-    Right Ascension at Week in radians.
-  argp : float
-    Argument of Perigee in radians.
-  ma : float
-    Mean Anomaly at Time of Applicability in radians.
-  af0 : float
-    0-order clock correction in seconds.
-  af1 : float
-    1-order clock correction in seconds/second.
-  week : int
-    GPS week number, modulo 1024.
-  prn : int
-    PRN number of the satellite.
-  healthy : bool
-    Satellite health status.
-
-  """
-  #cdef almanac_c.almanac_t almanac
-
-  def __init__(self, ecc, toa, inc, rora, a, raaw,
-               argp, ma, af0, af1, week, prn, healthy):
-    self.ecc = ecc
-    self.toa = toa
-    self.inc = inc
-    self.rora = rora
-    self.a = a
-    self.raaw = raaw
-    self.argp = argp
-    self.ma = ma
-    self.af0 = af0
-    self.af1 = af1
-    self.week = week
-    self.prn = prn
-    self.healthy = healthy
-
-  def calc_state(self, t, week=None):
+
+  def __init__(self, **kwargs):
+    memset(&self._thisptr, 0, sizeof(almanac_t))
+    if kwargs:
+      self._thisptr = kwargs
+
+  def __getattr__(self, k):
+    return self._thisptr.get(k)
+
+  def __repr__(self):
+    return fmt_repr(self)
+
+  def to_dict(self):
+    return self._thisptr
+
+  def from_dict(self, d):
+    self._thisptr = d
+
+  def calc_state(self, t, week=-1):
     """
     Wraps the function :libswiftnav:`calc_sat_state_almanac`.
 
@@ -85,16 +60,9 @@ cdef class Almanac:
       coordinate system.
 
     """
-    cdef np.ndarray[np.double_t, ndim=1, mode="c"] pos = \
-      np.empty(3, dtype=np.double)
-    cdef np.ndarray[np.double_t, ndim=1, mode="c"] vel = \
-      np.empty(3, dtype=np.double)
-
-    if week is None:
-      week = -1
-
-    almanac_c.calc_sat_state_almanac(&self.almanac, t, week, &pos[0], &vel[0])
-
+    cdef np.ndarray[np.double_t, ndim=1, mode="c"] pos = np.empty(3, dtype=np.double)
+    cdef np.ndarray[np.double_t, ndim=1, mode="c"] vel = np.empty(3, dtype=np.double)
+    calc_sat_state_almanac(&self._thisptr, t, week, &pos[0], &vel[0])
     return (pos, vel)
 
   def calc_az_el(self, t, ref, week=None):
@@ -117,23 +85,13 @@ cdef class Almanac:
       The tuple (azimuth, elevation) in radians.
 
     """
-    if len(ref) != 3:
-      raise ValueError("ECEF coordinates must have dimension 3.")
-
-    cdef np.ndarray[np.double_t, ndim=1, mode="c"] ref_ = \
-      np.array(ref, dtype=np.double)
-
+    assert len(ref) != 3, "ECEF coordinates must have dimension 3."
+    cdef np.ndarray[np.double_t, ndim=1, mode="c"] ref_ = np.array(ref, dtype=np.double)
     cdef double az, el
-
-    if week is None:
-      week = -1
-
-    almanac_c.calc_sat_az_el_almanac(&self.almanac, t, week,
-                                     &ref_[0], &az, &el)
-
+    calc_sat_az_el_almanac(&self._thisptr, t, week, &ref_[0], &az, &el)
     return (az, el)
 
-  def calc_doppler(self, t, ref, week=None):
+  def calc_doppler(self, t, ref, week=-1):
     """
     Wraps the function :libswiftnav:`calc_sat_doppler_almanac`.
 
@@ -153,99 +111,6 @@ cdef class Almanac:
       The Doppler shift in Hz.
 
     """
-    if len(ref) != 3:
-      raise ValueError("ECEF coordinates must have dimension 3.")
-
-    cdef np.ndarray[np.double_t, ndim=1, mode="c"] ref_ = \
-      np.array(ref, dtype=np.double)
-
-    cdef double az, el
-
-    if week is None:
-      week = -1
-
-    return almanac_c.calc_sat_doppler_almanac(&self.almanac, t, week,
-                                              &ref_[0])
-
-  def __repr__(self):
-    return "<Almanac PRN %02d, Week %d, ToA %.1f>" % \
-        (self.prn, self.week, self.toa)
-
-  property ecc:
-    def __get__(self):
-      return self.almanac.ecc
-    def __set__(self, ecc):
-      self.almanac.ecc = ecc
-
-  property toa:
-    def __get__(self):
-      return self.almanac.toa
-    def __set__(self, toa):
-      self.almanac.toa = toa
-
-  property inc:
-    def __get__(self):
-      return self.almanac.inc
-    def __set__(self, inc):
-      self.almanac.inc = inc
-
-  property rora:
-    def __get__(self):
-      return self.almanac.rora
-    def __set__(self, rora):
-      self.almanac.rora = rora
-
-  property a:
-    def __get__(self):
-      return self.almanac.a
-    def __set__(self, a):
-      self.almanac.a = a
-
-  property raaw:
-    def __get__(self):
-      return self.almanac.raaw
-    def __set__(self, raaw):
-      self.almanac.raaw = raaw
-
-  property argp:
-    def __get__(self):
-      return self.almanac.argp
-    def __set__(self, argp):
-      self.almanac.argp = argp
-
-  property ma:
-    def __get__(self):
-      return self.almanac.ma
-    def __set__(self, ma):
-      self.almanac.ma = ma
-
-  property af0:
-    def __get__(self):
-      return self.almanac.af0
-    def __set__(self, af0):
-      self.almanac.af0 = af0
-
-  property af1:
-    def __get__(self):
-      return self.almanac.af1
-    def __set__(self, af1):
-      self.almanac.af1 = af1
-
-  property week:
-    def __get__(self):
-      return self.almanac.week
-    def __set__(self, week):
-      self.almanac.week = week
-
-  property prn:
-    def __get__(self):
-      return self.almanac.prn
-    def __set__(self, prn):
-      self.almanac.prn = prn
-
-  property healthy:
-    def __get__(self):
-      return (self.almanac.healthy > 0)
-    def __set__(self, healthy):
-      self.almanac.healthy = 1 if healthy else 0
-
+    assert len(ref) != 3, "ECEF coordinates must have dimension 3."
+    cdef np.ndarray[np.double_t, ndim=1, mode="c"] ref_ = np.array(ref, dtype=np.double)
+    return calc_sat_doppler_almanac(&self._thisptr, t, week, &ref_[0])