Package ais :: Module binary
[hide private]
[frames] | no frames]

Module binary

source code

AIS binary helper functions.

Code to convert AIS messages between binary BitVectors and strings. They are usually encoded an ASCII 6-bit packing within NMEA !AIVDM/!AIVDO messages.


See Also:
NMEA strings at http://gpsd.berlios.de/NMEA.txt, Wikipedia at http://en.wikipedia.org/wiki/Automatic_Identification_System

Author: Kurt Schwehr

Version: 2075

Copyright: 2006

To Do:

Bugs:

Functions [hide private]
BitVector float2bitvec(floatval)
Get the IEEE floating point bits for a python float
float bitvec2float(bv)
Convert a 32 bit bitvector representing an IEEE float into a python float
  joinBV(bvSeq)
Combined a sequence of bit vectors into one large BitVector
BitVector setBitVectorSize(bv, size=8)
Pad a BitVector with 0's on the left until it is at least the size specified
BitVector addone(bv)
Add one bit to a bit vector.
BitVector subone(bv)
Subtract one bit from a bit vector
BitVector bvFromSignedInt(intVal, bitSize=None)
Create a twos complement BitVector from a signed integer.
int signedIntFromBV(bv)
Interpret a bit vector as an signed integer.
BitVector(6) ais6chartobitvec(char6)
Create a 6 bit BitVector for a single character
BitVector ais6tobitvec(str6)
Convert an ITU AIS 6 bit string into a bit vector.
  getPadding(bv)
Return the number of bits that need to be padded for a bit vector
str, pad bitvectoais6(bv, doPadding=True)
Convert bit vector int an ITU AIS 6 bit string.

Variables [hide private]
  __date__ = '2006-05-03'
Date of last svn commit
  parser = OptionParser(usage= "%prog [options]", version= "%pr...
  success = False
  decode = {'1': <ais.BitVector.BitVector object at 0x17ee890>,...
cache of character to BitVector lookup
  encode = {0: '0', 1: '1', 2: '2', 3: '3', 4: '4', 5: '5', 6: ...
cache of ais int value to charcter

Function Details [hide private]

float2bitvec(floatval)

source code 
Get the IEEE floating point bits for a python float
>>> print float2bitvec(1.)
00111111100000000000000000000000
>>> print float2bitvec (-1.)
10111111100000000000000000000000
>>> print float2bitvec (-999999.)
11001001011101000010001111110000
Parameters:
  • floatval (number) - number to convert to bits
Returns: BitVector
32 bits

Bug: May have bite order backwards

To Do: Is there a faster way to do this?

See Also: struct module

bitvec2float(bv)

source code 
Convert a 32 bit bitvector representing an IEEE float into a python float
Parameters:
  • bv (BitVector) - 32 bits representing an IEEE float
Returns: float
the corresponing number

Bug: May have bite order backwards

See Also: struct module

joinBV(bvSeq)

source code 
Combined a sequence of bit vectors into one large BitVector
Parameters:
  • bvSeq - sequence of bitvectors
Returns:
aggregated BitVector

Bug: replace with a faster algorithm!

setBitVectorSize(bv, size=8)

source code 
Pad a BitVector with 0's on the left until it is at least the size specified
Parameters:
  • bv (BitVector) - BitVector that needs to meet a minimim size
  • size (int) - Minimum number of bits to make the new BitVector
Returns: BitVector
BitVector that is size bits or larger

To Do: What to do if the vector is larger than size?

addone(bv)

source code 
Add one bit to a bit vector. Overflows are silently dropped.
>>> print addone(BitVector(bitstring='1100'))
1101
>>> print addone(BitVector(bitstring='1111'))
0000
Parameters:
  • bv (BitVector) - Add one to these bits
Returns: BitVector
Bits with one added

subone(bv)

source code 
Subtract one bit from a bit vector
>>> print subone(BitVector(bitstring='1111'))
1110
>>> print subone(BitVector(bitstring='0010'))
0001
>>> print subone(BitVector(bitstring='0000'))
1111
Parameters:
  • bv (BitVector) - Bits to add one bit to the right side
Returns: BitVector

bvFromSignedInt(intVal, bitSize=None)

source code 

Create a twos complement BitVector from a signed integer.

Positives must have a '0' in the left hand position.
>>> print bvFromSignedInt(0,bitSize=4)
0000
>>> print bvFromSignedInt(1,bitSize=4)
0001
>>> print bvFromSignedInt(7,bitSize=4)
0111
Negative numbers must have a '1' in the left hand position.
>>> print bvFromSignedInt(-1,bitSize=4)
1111
>>> print bvFromSignedInt(-2,bitSize=4)
1110
>>> print bvFromSignedInt(-7,bitSize=4)
1001
Parameters:
  • bv (BitVector) - Bits to subtract one bit from the right side
Returns: BitVector

signedIntFromBV(bv)

source code 

Interpret a bit vector as an signed integer. int(BitVector) defaults to treating the bits as an unsigned int. Assumes twos complement representation.

http://en.wikipedia.org/wiki/Twos_complement

Positive values decode like so:
>>> signedIntFromBV(BitVector(bitstring='0000'))
0
>>> signedIntFromBV(BitVector(bitstring='0101'))
5
Here are some negative integer examples:
>>> signedIntFromBV(BitVector(bitstring='1111'))
-1
>>> signedIntFromBV(BitVector(bitstring='1110'))
-2
>>> signedIntFromBV(BitVector(bitstring='1010'))
-6
>>> signedIntFromBV(BitVector(bitstring='1001'))
-7
>>> signedIntFromBV(BitVector(bitstring='1000'))
-8
Parameters:
  • bv (BitVector) - Bits to treat as an signed int
Returns: int
Signed integer

Note: Does not know the difference between byte orders.

ais6chartobitvec(char6)

source code 
Create a 6 bit BitVector for a single character
>>> print int(ais6chartobitvec('0'))
0
>>> print int(ais6chartobitvec('1'))
1
>>> print int(ais6chartobitvec('9'))
9
>>> print int(ais6chartobitvec('<'))
12
>>> print int(ais6chartobitvec('='))
13
>>> print int(ais6chartobitvec('@'))
16
>>> print int(ais6chartobitvec('A'))
17
>>> print int(ais6chartobitvec('O'))
31
>>> print int(ais6chartobitvec('P'))
32
>>> print int(ais6chartobitvec('Q'))
33
>>> print int(ais6chartobitvec('R'))
34
>>> print int(ais6chartobitvec('Z'))
34
>>> print int(ais6chartobitvec('a'))
41
>>> print int(ais6chartobitvec('w'))
63
>>> print ais6chartobitvec('w')
111111
x, y, and z will not appear.
Parameters:
  • char6 (str(1)) - character of an AIS message where each character represents 6 bits
Returns: BitVector(6)
Decoded bits for one character (does not know about padding)

Bug: need to cut down the doctest here and copy all of the current one to tests/test_binary.py

ais6tobitvec(str6)

source code 
Convert an ITU AIS 6 bit string into a bit vector. Each character represents 6 bits. This is the NMEA !AIVD[MO] message payload.
Parameters:
  • str6 (string) - ASCII that as it appears in the NMEA string
Returns: BitVector
decoded bits (not unstuffed... what do I mean by unstuffed?). There may be pad bits at the tail to make this 6 bit aligned.

Note: If the original BitVector had ((len(bitvector) % 6 > 0), then there will be pad bits in the str6. This function has no way to know how many pad bits there are.

>>> print ais6tobitvec('6')
000110
>>> print ais6tobitvec('6b')
000110101010
>>> print ais6tobitvec('6bF:Z')
000110101010010110001010100010

Bug: Need to add pad bit handling

getPadding(bv)

source code 
Return the number of bits that need to be padded for a bit vector
>>> getPadding(BitVector(bitstring='0'))
5
>>> getPadding(BitVector(bitstring='01'))
4
>>> getPadding(BitVector(bitstring='010'))
3
>>> getPadding(BitVector(bitstring='0101'))
2
>>> getPadding(BitVector(bitstring='01010'))
1
>>> getPadding(BitVector(bitstring='010101'))
0
>>> getPadding(BitVector(bitstring='0101010'))
5
@rtype: int
@return: number of pad bits required for this bitvector to make it bit aligned to the ais nmea string

bitvectoais6(bv, doPadding=True)

source code 
Convert bit vector int an ITU AIS 6 bit string. Each character represents 6 bits
>>> print bitvectoais6(BitVector(bitstring='000110101010010110001010100010'))
('6bF:Z', 0)
Parameters:
  • bv (BitVector) - message bits (must be already stuffed)
Returns: str, pad
str6 ASCII that as it appears in the NMEA string

To Do: make a test base for needing padding

Bug: handle case when padding needed


Variables Details [hide private]

__date__

Date of last svn commit
Value:
'2006-05-03'                                                           
      

parser

None
Value:
OptionParser(usage= "%prog [options]", version= "%prog "+ __version__) 
      

success

None
Value:
False                                                                  
      

decode

cache of character to BitVector lookup
Value:
{'0': <ais.BitVector.BitVector object at 0x17ee910>,
 '1': <ais.BitVector.BitVector object at 0x17ee890>,
 '2': <ais.BitVector.BitVector object at 0x17ee3f0>,
 '3': <ais.BitVector.BitVector object at 0x17ee9b0>,
 '4': <ais.BitVector.BitVector object at 0x17eea30>,
 '5': <ais.BitVector.BitVector object at 0x17eea70>,
 '6': <ais.BitVector.BitVector object at 0x17ee9f0>,
 '7': <ais.BitVector.BitVector object at 0x17eeab0>,
...                                                                    
      

encode

cache of ais int value to charcter
Value:
{0: '0', 1: '1', 2: '2', 3: '3', 4: '4', 5: '5', 6: '6', 7: '7', 8: '8
'}