$Date: 2009-01-02 13:02:40 $

Clew manual

Clew is currently at the "works for me" stage; please be kind to it.

About

Clew is a chart plotting program. Connect a GPS to your laptop, load some maps, and watch the dots crawl across the map as you drive, sail, etc. It currently works with maps scanned/photographed into the computer and any GPS with NMEA output.

Probably not suitable for navigation.

Screenshots

(click on the thumbnail - or on the map snippet on right - to see more)

Download

Download current version (0.2a). (Old versions: 0.1)

Use

Clean out the tracks subdirectory (delete the old track images or move them somewhere else to enjoy).
Run clew in a terminal. ./clew
Open the tracks directory in gqview, switch it to full-screen mode using V and use the space bar and backspace to switch between maps (or hit S to turn on Slideshow).

Replaying logs

(new in version 0.2) Clew can also replay its logs, either in real-time (perhaps speeded up by a factor), or simply as fast as possible (for instance, to plot the log on a newly-acquired map). This is set up in options.py, like this:

firstly, set demo = True
set demo_fixes to one of the following, substituting the appropriate filename (relative to the map directory)
- if you want to re-play a log as fast as possible, set:
  import log demo_fixes = log.read("filename.log")
- if you want to re-play a log at the correct speed, set:
  import log demo_fixes = log.play("filename.log", timefactor=1)
if you're only interested in the final image (rather than watching the story unfold), set batch = True

Format

If you want to construct a log file for playback, each line should be a dictionary in python format, like this:
{'long': 'EDDD MM SS.S', 'lat': 'NDD MM SS.S', 'utc': 1230698225}

One point per line; the latitude and longitude can also be given in the formats 'DD MM.MM N' or 'DD MM SS.S N' if you prefer. The 'utc' field is standard unix time, the number of seconds since 1970 (if you don't want timed replay, you can use 0 instead of actual times).

Replaying GPSManager tracks

(new in version 0.2) Clew can also replay tracks downloaded from the GPS using GPSManager. This is set up in options.py, like this:

similarly to re-playing logs, first set demo = True
set demo_fixes to one of the following, substituting the appropriate filename (relative to the map directory)
- if you want to re-play a track as fast as possible, set:
  import gpsmgr_track demo_fixes = gpsmgr_track.read("filename.track")
- if you want to re-play a track at the correct speed, set:
  import gpsmgr_track, log demo_fixes = log.play("filename.track", timefactor=1, parser=gpsmgr_track.read)
again, if you're only interested in the final image (rather than watching the story unfold), set batch = True

(new in version 0.2a) Version 0.2 couldn't handle negative heights - fixed.

Format

If you want to construct a GPSManager track for playback, each line should have this format:
00--2000 HH:MM:SS NDD MM SS.S EDDD MM SS.S 0.0

One point per line; HH=hours, MM=minutes, SS=seconds; N means North (use S for South); DD=degrees, MM=minutes, SS.S=seconds (one decimal place); E means East (use W for West), DDD=degrees, MM=minutes, SS.S=seconds (one decimal place). The 0.0 at the end is altitude, which is ignored.

Replaying eXplorist tracks

(new) The CVS version can now also play back eXplorist tracks. Let me know if you want it, I'll make a release.

Map setup

Maps are in directories, grouped by area. Each of these directories must also contain a subdirectory called tracks.

Two different map formats are supported: native clew and (new in version 0.2) GPSy.

Native clew maps

Maps are in .png or (new in version 0.2) .jpg image files. While cleaning up the file in gimp, check the x and y coordinates of three points with known lat and long. Write these into a file of the same name as the image but the extension .clew, in the following format:

# Image data for clew
{
  'points': (
    {'x': 252, 'y': 871, 'lat': "38 19 S", 'long': "145 12 E"},
    {'x': 1229, 'y': 866, 'lat': "38 19 S", 'long': "145 13 E"},
    {'x': 1235, 'y': 2092, 'lat': "38 20 S", 'long': "145 12.5 E"}
  )
}

(new in version 0.2) There is an optional 'adj' field; any values listed in the adj field are added to the corresponding values in each of the points. Thus, they can be used to fine-tune georeferencing (for instance, for a different datum).

# Image data for clew
{
  'points': (
    {'x': 252, 'y': 871, 'lat': "38 19 S", 'long': "145 12 E"},
    {'x': 1229, 'y': 866, 'lat': "38 19 S", 'long': "145 13 E"},
    {'x': 1235, 'y': 2092, 'lat': "38 20 S", 'long': "145 12.5 E"}
  ),
  'adj': {'x':7, 'y':-3}
}

If the position offset is known, one can instead use

'adj':
{'lat': "0 01 N", 'long': "0 02 E"}

GPSy maps

(new in version 0.2) This is the format used by some commercial maps, for instance some of the CD maps from Meridian. Of the files on the CD, clew needs the .JPG and .JPG Calibrations_ files.

Other new features in version 0.2

Dots are now joined with a thin line of a different colour.
When clew is finished, it writes out the whole maps. When re-playing logs or tracks, this happens when the file ends; when connected to the GPS, this happens when Ctrl-C is pressed.

Known issues

The joining line doesn't work very well when one leaves the map and comes back. Fixed in CVS (though perhaps a little refactoring would be nice).
It would be useful to have the time displayed in one of the corners of the map, both for playback and real-time.

Requirements

Clew is written in Python. It requires the PIL, Numarray and Twisted packages.

Config

Config is in the file options.py in the clew directory. Lines starting with # are comments (or commented-out variations). Sample:

""" User config - sets various options """

# the directory which contains the map files (relative to current directory)
mapdir = "Hastings"

# 0=tiny (1 pixel), 1=small (3x3), 2=medium (5x5), 3=large (7x7), 4=XL (9x9)
marksize = 3

# RGB colour
markcolour = (255, 0, 0) # bright red
#markcolour = (229, 22, 84) # a kind of red, not as garish as (255, 0, 0)
#markcolour = (0x33, 0x33, 0x99) # dark blue
#markcolour = (0x66, 0xdd, 0xdd) # aqua

# should marks be joined with thin lines?
join = True
# RGB colour
#joincolour = (229, 22, 84) # a kind of red, not as garish as (255, 0, 0)
#joincolour = (0x33, 0x33, 0x99) # dark blue
#joincolour = (0x66, 0xdd, 0xdd) # aqua
joincolour = (255, 255, 255) # white

# size of the output images
tracksize = (1024, 768)

# batch mode - only save the full images at the end, not the partial ones
# during run. This is handy to plot logs and tracks on maps.
batch = False

# demo/testing mode
demo = False

# should the file be saved even if we didn't move? (for testing only)
demo_alwayssave = False

# use one particular location
#demo_fixes = [("38 19.8 S", "145 13 E")] # near Hastings

# re-play a log (at the correct speed)
#import log
#demo_fixes = log.play("demo-log", timefactor=10, maxdelay=2)

# re-play a track (as quickly as possible)
#import gpsmgr_track
#demo_fixes = gpsmgr_track.read("Rarotonga_2004_track")

# the port to which the GPS is connected (eg '/dev/ttyS0')
port = '/dev/ttyUSB0'

Troubleshooting

USB-to-serial converter not recognised (detected as mouse): This sometimes happens when the GPS is already connected to the converter. Disconnect the converter from the PC and from the GPS, plug it into the PC first and connect the GPS second.
NameError exception in .../twisted/protocols/gps/nmea.py: There's a bug in twisted with the combination of options clew uses. The line on which the exception occurs and the next line need an extra level of indentation. (The bug has been fixed in the newest versions of twisted.)