Package ais :: Module binary

Module binary

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:

Flush out stuffBits and unstuffBits
bitvectorais6
test cases for ais6tobitvec

Bugs:

code up stuffBits and unstuffBits
find an example needing bitstuffing

Date: 2006-05-03

Functions

[hide private]

BitVector

float2bitvec(floatval)
Get the IEEE floating point bits for a python float

source code

float

bitvec2float(bv)
Convert a 32 bit bitvector representing an IEEE float into a python float

source code

joinBV(bvSeq)
Combined a sequence of bit vectors into one large BitVector

source code

BitVector

setBitVectorSize(bv, size=8)
Pad a BitVector with 0's on the left until it is at least the size specified

source code

BitVector

addone(bv)
Add one bit to a bit vector.

source code

BitVector

subone(bv)
Subtract one bit from a bit vector

source code

BitVector

bvFromSignedInt(intVal, bitSize=None)
Create a twos complement BitVector from a signed integer.

source code

int

signedIntFromBV(bv)
Interpret a bit vector as an signed integer.

source code

BitVector(6)

ais6chartobitvec(char6)
Create a 6 bit BitVector for a single character

source code

BitVector

ais6tobitvec(str6)
Convert an ITU AIS 6 bit string into a bit vector.

source code

getPadding(bv)
Return the number of bits that need to be padded for a bit vector

source code

str, pad

bitvectoais6(bv, doPadding=True)
Convert bit vector int an ITU AIS 6 bit string.

source code

Variables

[hide private]

decode = {'0': <ais.BitVector.BitVector object at 0x1470f10>, ...
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:

intVal (int) - integer value to turn into a bit vector
bitSize (int) - optional size to flush out the number of bits

Returns: BitVector

A Bit Vector flushed out to the right size

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]

decode

cache of character to BitVector lookup

Value:

{'0': <ais.BitVector.BitVector object at 0x1470f10>,
 '1': <ais.BitVector.BitVector object at 0x1470e50>,
 '2': <ais.BitVector.BitVector object at 0x1470ed0>,
 '3': <ais.BitVector.BitVector object at 0x1470f70>,
 '4': <ais.BitVector.BitVector object at 0x1470ff0>,
 '5': <ais.BitVector.BitVector object at 0x147e070>,
 '6': <ais.BitVector.BitVector object at 0x147e0d0>,
 '7': <ais.BitVector.BitVector object at 0x147e110>,
...

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',
...