$Date: 2006/03/06 10:40:52 $

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:
  1. firstly, set demo = True
  2. set demo_fixes to one of the following, substituting the appropriate filename (relative to the map directory)
  3. if you're only interested in the final image (rather than watching the story unfold), set batch = True

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:
  1. similarly to re-playing logs, first set demo = True
  2. set demo_fixes to one of the following, substituting the appropriate filename (relative to the map directory)
  3. 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.

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

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).

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.)