# Rikard & Henrik Bjorkman's ChartPlotter 0.16

- Features
- System requirements
- Downloading
- Installation
- Reference points
- Starting
- NMEA
- Trouble shooting
- Known bugs
- Links
- Feedback
- Copyright
- Disclaimer

## Features

If you have a computer that can run Java and a GPS then this chart plotter program can show a map with a mark at your position.

It should work with all NMEA compatible GPS receivers that sends the GPGLL sentence.

The maps can be in JPEG format.

Translation between position and map co-ordinates is done with the help of 2-4 reference points that are read from a chart data file.

## System requirements

Java 1.1
Preferably with the Java Communications API.

If you have only 16MByte of memory loading image files will be very slow.

## Downloading

Here is the program including source code:
ChartPlotter.zip

If you have no Java installed we recommend SUN's JDK. It can be downloaded from Sun’s www site:
java.sun.com/products/OV_jdkProduct.html

The Java Communications API is found here:
java.sun.com/products/javacomm/index.html

## Installation

Install Java and the Java Communications API according to their respective instructions. On NT and Linux it is possible to run the ChartPlotter without the Communications API but then you will have to set baud rate yourself each time you start it.

Add the ChartPlotter.zip file to your CLASSPATH environment variable. If you use Windows you can put something like this in your autoexec.bat file:
set CLASSPATH=.;c:\java\ChartPlotter.zip;

Or perhaps if you have a CLASSPATH variable already (which you do if you have installed the API):
set CLASSPATH=%CLASSPATH%;c:\java\ChartPlotter.zip;

In the examples above the zip file with the ChartPlotter code was stored in the folder "c:\java". Reboot or something.

## Reference points

You will also need maps. You can use a scanner and scan your own maps and then supply the program with 4 reference points per map so that it can translate GPS positions to pixels on the map.

There is a program called CalibrateChart to be used for creating the data files with chart reference points. Do cd to where the image files are and try:
java CalibrateChart

The CalibrateChart program can not create the top file used to do include on the other data files.

The reference point data is stored in ascii text files. The format shall be like in these example charts.dat files:

First a top file preferably called charts.dat that tells ChartPlotter which files it shall read.

------------cut here------------
// charts.dat
include chart1.dat
include chart2.dat
------------cut here------------

Then one data file for each image (usually .gif or .jpg) file. These files can be created with the CalibrateChart program or written manually.

------------cut here------------
// chart1.dat
begin ChartData
name chart1.jpg
ref 342 71 59N20.0 018E04.0
ref 1239 948 59N18.0 018E08.0
ref 350 950 59N18.0 018E04.0
ref 1240 70 59N20.0 018E08.0
lim 59N18 59N20 18E04 18E08
datum WGS-84
rem "Stockholm chart from 1998"
end
------------cut here------------

------------cut here------------
// chart1.dat
//
begin ChartData
name chart2.jpg
ref 312 61 59N20.0 018E08.0
ref 1219 958 59N18.0 018E12.0
datum RT
comp 0.02 0.21
end
------------cut here------------

See also this example chart and charts.dat file:
charts.zip

### Commands in the charts.dat file

Lines beginning with "//" are ignored.

#### name <n>

The name of the image file is <n> for the data that follows. It must be followed by at least two reference points.

#### ref <x> <y> <lat> <lng>

Reference points. First in a reference point is the XY co-ordinates <x> and <y> in the image file. Then the corresponding latitude <lat> and longitude <lng> on the map.

Three reference points give get better precision than two. The first three reference points must not be placed near each other. Place them so they form a triangle. The forth point is used to verify the other three. Later when the program is running you will see a number after the map name. This number tells how far away the forth reference point is from a position calculated using the first three.

We recommend that you put your GPS in simulator mode and test the calibration on each map by going to some random positions.

#### lim <south-lat> <north-lat> <west-lng> <east-lng>

The coverage of the chart.

The area covered by the chart is given with south, north, west and east borders. Set the chart coverage a little smaller than the actual size so that the program will try to find another chart before reaching the edge.

The program will show the first chart in the list that fits. We recommend some overview maps last in the chart data file.

<south-lat> is the south border of the map and so on.

#### datum <n>

The chart datum of the image file is <n>. New charts are usually in WGS-84 which is the same as a GPS usually uses.

#### comp <lat_offset> <lng_offset>

If the charts are old they are probably not WGS-84. some GPS receivers can send positions translated to these old datums. Or you can use a "comp" line to tell the ChartPlotter to add an offset to the position data received from the GPS.

#### include <n>

Include charts data file <n>. This is useful if you have many charts. Then you can put then in different folders and include one charts.dat file in each of those folders. It is recomended to have one charts.dat file with only includes and then have one data file for each image file. You can have recursive includes. The program supports up to 1000 maps and if you have all in one folder it will be hard keep them in good order.

#### rem <t>

A free text message <t> to be shown in the title when this chart is used.

## Starting

To start the program you can use a shortcut or you can start from the command line in a command tool such as MS-DOS prompt if you use windows.

### Windows Example

If you have your charts and charts.dat file in a folder called c:\charts
In the MS-DOS prompt window do:
cd c:\charts
java ChartPlotter

### Usage

Usage: java ChartPlotter [switches] [<file name>]

<file name>
The name of the file with reference points (charts.dat is default).

switches:

-p<n>
The name of the com port to use is <n> (On Windows COM1 is default).

-h
List more switches.

### Shortcut

In Windows it is convinient to have a shortcut.
Left-click on desktop
Choose new -> shortcut.
In command line type "javaw ChartPlotter"
Click next.
Choose the name "ChartPlotter"
Left-click on the new shortcut and choose properties.
In the field "start in" replace "C:\PROGRAM\JDK1.1.6\BIN" with the folder where you have your charts for example "c:\charts".
Chose change icon and select one that looks nice. Perhaps one with a globe.

## NMEA

The GPS receiver needs to have an NMEA compatible serial port interface. NMEA is a one way protocol so the PC can not tell the GPS to start sending NMEA. Check your GPS receiver’s documentation on how to start sending data in NMEA format from your GPS. For Garmin receivers this is done under communication

NOTE!
NMEA is a one way protocol. It is not possible for the PC to order the GPS to start sending positions in NMEA format. This must be done manualy. A common problem.

## Trouble shooting

### Java version

Check if correct java is installed? If you use JDK (or JRE) you need 1.1.8 or later.
In a command window type:
java -version

It should say something like:
java version "1.1.8"

### Communication extension

If you don't have the Java Communications API installed the program will try to use the serial ports without it. On Windows this will probably not Work.

If you see the ChartPlotter program write the following lines then the Java Communications API is not installed.

------------cut here------------
Windows COM1
Remember to set baudrate before starting this program.
It is done like this:
MODE.COM COM1 4800,N,8,1
If it still don't work try to install the Java Communications API.
loading data
------------cut here------------

### Incorrect path

Java will use the environment variable CLASSPATH to find the java classes. If java say:
Can't find class ChartPlotter

Then check the CLASSPATH variable like this (windows):
echo %CLASSPATH%

You should get something like this:
.;c:\java\CharPlotter.zip;c:\Program\jdk\bin\comm.jar

Note the paths in the line above can be different depending on installation.

Now check if the files above exist (use the path you got above not the one shown here):
dir c:\java\CharPlotter.zip
dir c:\Program\jdk\bin\comm.jar

### No data from GPS

If it don't work use a terminal emulator (such as HyperTerminal in Windows) to see if the GPS is sending anything. If it is check if it sends lines beginning with "$GPGLL" etc and if there is position data in that line.

Set the com port to 4800 baud, 8 data, 1 stop, no parity.

If its sends nothing check the cable and the documentation for your GPS on how to make it send NMEA.

If you have a cable with a 9 pin DSUB contact: The PC will expect to receive data on pin 2. This can be verifyed with a voltage meter. There should be 5-12 V AC between this pin and pin 5 (GND).

### File not found

If a file is not found the program prints something like the following line:
ChartThread: java.io.FileNotFoundException: charts.dat
You need to be in the same folder as the charts.dat when you start the program. If not try cd to that folder.

If an image file (usually a .jpg file) is missing you might get just a blank window.

## Known bugs

It probably won't work to have reference points on both sides of the datum line. A workaround is to use two sets of reference points for the same chart image file.

On Windows 95 and 98 it only works if you have the communications API installed.

If you have installed the communications api but the program does not find it. Then the program will try without and you will see the text about setting the baudrate manually. On windows 9x this will not work. This problem seems to occure if you have installed jdk in the "program files" folder. The space character in that name seems to cause a lot of trouble not just with java. Install jdk in a folder with no spaces and it should work better. An advice is to never use that folder unless the program you install suggest it itself.

On NT and Linux the ChartPlotter program can work also without the Java communications API but it can't set baud rate without the API so you will have to set the baudrate manually before starting the ChartPlotter. (4800 baud, 8 data, 1 stop, no parity).

Counting line numbers in data files do not work correctly anymore. (The line numbers are only used to tell where a syntax error in a charts.dat file is located if such an error is found.)

We have tested with jdk 1.3.1 on Windows ME and it did not work so well. With jdk 1.1.8 it works fine on Windows ME.

## Links

Here is our list of GPS related sites.
GpsLinks.html

## Feedback

If you like this software please let us know. Send comments or questions to:

Put the word ChartPlotter in the subject line. Otherwise my anti spam email filter will probably throw your email away.

## Copyright

Copyright 1998 and 1999 Henrik Björkman www.stacken.kth.se/~bjorkman. Version 0.15 of this software may be distributed as under the GNU public license.

## Disclaimer

You may not use this software as your only means of navigation. In no way shall the creators of this software be responsible for any damage caused directly or indirectly by the use of this software.

You use this software completely at your own risk.

home