Making Newton GPS Maps

Getting Started

If you are reading this page, I'm going to presume it's because you are interested in making maps for use with GPS Map or GPS Map Lite for the Newton.

I started doing this when my wife got me a Haicom Hi-303e CF GPS card which happens to work in both my Newton 2000U and my TiBook. With the TiBook, Route 66 2004 does just fine, but for the Newton you have to roll your own maps - which I will try to describe here. Keep in mind I am no expert on Newton programming (I'm an old Fortran hack), so if I can do it, you probably can too. Mind you, what follows is far from comprehensive - it's just what I did to get a usable map for my town.

First, the bits you need:

• A Newton with GPS - I have an MP 2000U, and these instructions will be a bit biased towards it (i.e., 16-shade gray maps)
• The GPS Map or GPS Map Lite software from www.phys.uwosh.edu/mike/gps/ (note: GPS Map is no longer available, but GPS Map Lite can still be downloaded as freeware - many thanks to Gerd Staudenmaier, the author, for doing this! His original site, http://www.segelflug.de/gps/, is mirrored at both una and www.phys.uwosh.edu/mike/gps with his permission.)
• The Newton Toolkit, either version 1.6.4 for the Mac, or 1.6.1 for Windows (download them from unna). For those using Mac OS X, consider also installing TCPSerial in classic if you want NTK to run.
• Some image processing/manipulation software that can export files as pict resources in either 1, 2, or 4-bits. I ended up using an older version of Adobe Photoshop (Photoshop CS only seems to do 16 or 32 bits/pixel), but GraphicConverter is also probably up to the job.
  For those with PCs, Victor Rehorst also suggests "a good program to use in lieu
  of Photoshop for the image manipulation would be JASC Inc's Paint Shop Pro.
  Personally I've been using their ancient version 4.12 version and it should
  let you do what you need to do for making these maps - namely, saving as
  4-bit greyscale Windows bitmaps. If you GoogleSearch for 'psp412.exe' you
  should be able to find this old version (which won't expire)."
• The map making package that can be downloaded from the GPS Map site:
  version 1.5 for Macs
  version 1.5 for PCs
  This also includes "How to create Map Container Packages for use with GPS Map" as a PDF file. You should really really read this before continuing (and I will assume you have).

Maps

Gerd Staudenmaier offers some very good advice on maps:

"All rights for maps belong to their publishers. Normally you may not copy or scan maps without the written permission of the publisher. Please comply with the copyright notice on your map.

You may scan and convert purchased paper maps to Map Container Packages without permission of the publisher ONLY FOR YOUR OWN AND PRIVATE USAGE!"

That having been said, I will presume you have gotten hold of a map, either by scanning one (a difficult and cumbersome process, even for a flat map) or by some other method. What I've found works very well for small cities (like my home town of Oshkosh Wisconsin) is to just copy & paste map bits from Route 66 2004 USA right into photoshop carefully lining them up into one large mosaic. This has the advantage of a) being already set-up N/S and E/W and b) making it easy to find the lat/lon which correspond to different x/y pixels. The map I ended up with was 2588x3266 pixels - which the Newton can deal with (albeit slowly). At some point (soon), I'll try breaking this up into smaller tiles to speed things up.

There are of course other types of maps - or more appropriately, other coordinate systems to use in mapping, particularly over large distance where curvature is important. These are "cone type" maps as well as those from map vendors. The map I'm using here is a "rectangular type" (N/S and E/W lines are straight and perpendicular), but the extension to cone and other types (which the software can deal with) should be straight forward. The map making software can also deal with vector-based maps as opposed to bitmaps, but I haven't tried that yet (and won't talk about it any more).

Use Photoshop, Paint Shop Pro (or whatever you wish) to get your map into a size, resolution, and depth of (gray) colors that will look good on the Newton. Again, I've got a 2000 series, so I went with a 4-bit gray map at 72 dpi resolution (it'll look a little smaller on the MP at its slightly higher screen resolution).

Here's what you need to know about your map (for rectangular maps):

• You will need the latitude and longitude of x/y pixel locations on the map. There are two ways to do this.
  • If your map is nicely lined up with N/S and E/W up-down and right-left respectively, you need the lat/long values of a point in the lower left, in the lower right, and in the upper left of your map - and the two points at the bottom must have the same latitude, the two points on the left must have the same longitude. If you go this route, you'll be using the RectMap1 program below.
  • An easier alternative is simply to find the lat/long values of three different location on your map and their corresponding x/y pixel values. These don't have to be on the same lines of lat/long. If you're using Route 66 (like I did) you can use that to look up the values. Another way is to drive/walk to three different locations and use your GPS to directly measure the lat/lon. For these three unrelated points, you'll use the RectMap2 program.
• You will also need to know the scale of the map (why, I'm not sure - it should be possible to calculate it directly from the info above). You likely remember scale, for example: 1 inch = 1 mile on your map. In this case, you'll need to know the physical distance between two points on your map (if the map you scanned has a scale printed on it, you can use that, or Route 66 simply displays the value for you and you can move on to the next step). You'll also need to know the separation in pixels of those two points on your map, and the resolution (in dots (pixels) per inch). The scale is then the physical distance divided by the distance in pixels - but be sure to use consistent units! For example, say you have two points, 840 feet apart which are separated by 419 pixels on your 72 dpi map. Those 419 pixels = 419/72 = 5.82 inches = 419/72/12 = 0.485 feet on your screen. Thus, the scale is 840 feet / 0.485 feet = 1730 (or more properly 1:1730).

For all of this, keep in mind the farther apart the points you use (for the coordinates and the scale calculations), the more accurate your positions will be. Write all these numbers down too, you'll need them in a couple of minutes.

For Macs, the map must be saved as a Pict resource. They're saved as .BMP files on Windows, but I know nothing about that platform and I want to keep it that way :). I did this using Photoshop 6 (after converting the map to grayscale), and just about all earlier versions should handle this too. I believe GraphicConverter should work too, but I haven't tried it. During this save process you'll also specify the bit depth and the resource name:

Here's a screen grab of the "Save As" dialog box. Specify "Pict Resource" as the file type and give the file a name to save to.

During the second part of the save process, you will specify an ID number for the resource (use 0) and a name for the resource (here I've used "Map" - you'll need this name later). This is also where you specify the bit-depth (4 bits here = 16 shades of gray). At 4 bits, there is no choice for compression, which you don't want anyway. Save the file and you're done.

Building the Map Container

When you unpacked the map making package, you should have ended up with several files and folders.

First, make a copy of the Map Template 1.5 folder and rename it to something else - you'll be modifying the files in this folder and it's good to have an original lying around. Also place the map itself that you made earlier in this folder.

There is really only one part of one file which you need to modify to make the map. Click on the "map" NTK project file to start NTK and open the project. You'll end up with a window that looks like the one to the right.

The bit you want is •Map_Main.t at the bottom. Double click on it, or select it and pick "New Browser" from the window menu. It will open up a browser window like the one to the right.

Click on clView:Map_Main in the upper left. This will open a list of contents in the upper right window (see screen capture). You are interested in the first one: afterScript which contains the parameters for your map.

Clicking clView:Map_Main will show the corresponding code in the lower half of the window - this is what you will be changing.

What follows is the original listing from Map_Main.afterScript. The parts that will have to be messed with an in bold/red:

//////////////////////////////////////////////////////////////////////
// Map Template for Map Preparation Package version 1.5 //
// //
// Copyright ©1995-97 //
// Gerd Staudenmaier, Software Development & Marketing //
// Friedrichshafener Str. 24 b //
// D-88090 Immenstaad, Germany //
// e-mail: gerds@micronet.de //
// all rights reserved ! //
// //
// IMPORTANT !!! //
// You may freely use this map template for use with "GPS Map" and //
// "GPS Map Lite" only. All other applications need the written //
// permission of the author! //
//////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////
// Read in the map by using one of the methods as described within //
// the map preparation manual //
//////////////////////////////////////////////////////////////////////
BMAP_1 := .......;

//////////////////////////////////////////////////////////////////////
// Repeat previous statements for all further maps to be included //
// into your map package if applicable //
//////////////////////////////////////////////////////////////////////
BMAP_2 := .......;

thisView.MapList := [
/////////////////////////////////////////////////
// This frame describes the map loaded into //
// BMAP_1. If you have more maps repeat the //
// frame for each map //
/////////////////////////////////////////////////
{
// map name as displayed in map list
Name : "????",
// comment as displayed in "theTextView"
Comment : "????",
// pointer to map data
theBits : BMAP_1,
// map scale (i.e. 50000)
Scale : ????,
// scanner resolution in dots per inch (p.e. 150)
Resolution : ????,
// calculate ScaleFactor as "ROUND (Scale / Resolution)"
ScaleFactor : ????,
// coordinate style of map, must be 'RECT or 'CONE
Type : ????,
// map structure version (always 1 for this template version)
Version : 1,
// remove slot "Public" if map should not be recognized by GPS Map demo version!
Public : TRUE,
////////////////////////////////////////////////
// replace the question marks below by the //
// coefficients output from one of the //
// calibration applications //
////////////////////////////////////////////////
????,
// geographic limits for map ('CONE type only)
Lat_top : NIL,
Lat_bottom : NIL,
Long_left : NIL,
Long_right : NIL,
// geographic default position for loading map
Def_Lat : ????,
Def_Long : ????
},

/////////////////////////////////////////////////
// Repeat the previous frame for further maps //
// if applicable //
/////////////////////////////////////////////////
];

// end of afterScript

First, we have:

//////////////////////////////////////////////////////////////////////
// Read in the map by using one of the methods as described within //
// the map preparation manual //
//////////////////////////////////////////////////////////////////////
BMAP_1 := .......;

The "BMAP_1" line must be replaced with the code necessary to open the map file you made and to associate the resource with a name that can referred to later. Here's what I used (in bold/blue):

//////////////////////////////////////////////////////////////////////
// Read in the map by using one of the methods as described within //
// the map preparation manual //
//////////////////////////////////////////////////////////////////////
rf := OpenResFileX (HOME & "Oshkosh.rsr");
BMAP_1 := MakePixFamily (NIL, NIL, "Map");
CloseResFileX (rf);

The first line opens the map file saved as a Pict resource from Photoshop (Oshkosh.rsr).
The second line reads the pixel file from the resource named "Map" in Oshkosh.rsr into the variable BMAP_1. Remember during the save dialog when you specified the name of the resource (not the name of the file)? That's where the "Map" came from here. Also, I chose MakePixFamily because I am making a 4-bit map using NTK 1.6.4. The first two entries in MakePixFamily (both "NIL") would be the names of 1 and 2-bit map resources respectively - if that makes sense.
The third line closes the file.

Next to be changed is:

//////////////////////////////////////////////////////////////////////
// Repeat previous statements for all further maps to be included //
// into your map package if applicable //
//////////////////////////////////////////////////////////////////////
BMAP_2 := .......;

I only have one map, so this gets commented out:

//////////////////////////////////////////////////////////////////////
// Repeat previous statements for all further maps to be included //
// into your map package if applicable //
//////////////////////////////////////////////////////////////////////
// BMAP_2 := .......;

These next bits are also fairly straight forward, so I'll cover them all at once:

// map name as displayed in map list
Name : "????",
// comment as displayed in "theTextView"
Comment : "????",
// pointer to map data
theBits : BMAP_1,
// map scale (i.e. 50000)
Scale : ????,
// scanner resolution in dots per inch (p.e. 150)
Resolution : ????,
// calculate ScaleFactor as "ROUND (Scale / Resolution)"
ScaleFactor : ????,
// coordinate style of map, must be 'RECT or 'CONE
Type : ????,

Name is what you want the map to be called in GPS Map or GPS Map Lite.
Comment is, well, any comment you want displayed.
Scale is the map scale you computed earlier (the 1730 in the example above).
Resolution is the number of DPI in your map (72 in the above example).
ScaleFactor is the scale divided by the resolution, rounded to the nearest whole number (1730 / 72 = 34 for the numbers above).
Type is what kind of map coordinates you are using (use 'RECT or 'CONE). In this example, it is 'RECT. Don't forget the leading apostrophe.

Here's what my modifications look like:

// map name as displayed in map list
Name : "Oshkosh",
// comment as displayed in "theTextView"
Comment : "Oshkosh City 2003",
// pointer to map data
theBits : BMAP_1,
// map scale (i.e. 50000)
Scale : 9800,
// scanner resolution in dots per inch (p.e. 150)
Resolution : 72,
// calculate ScaleFactor as "ROUND (Scale / Resolution)"
ScaleFactor : 136,
// coordinate style of map, must be 'RECT or 'CONE
Type : 'RECT,

Now you need to input the transforms necessary to relate a lat/lon position to a pixel on your map. This will be pasted over the four (red/bold) question marks on the line below:

////////////////////////////////////////////////
// replace the question marks below by the //
// coefficients output from one of the //
// calibration applications //
////////////////////////////////////////////////
????,

This is actually not so bad, as Gerd has written some routines to do this for you. Because at least in my example, I'm using a map in a rectangular coordinate system, RectMap1 or RectMap2 will do it, depending on whether or not the three locations I have used to relate lat/lon to x/y positions are related (see above). If I'd had a conic map, I would use ConeMap, and etc. Note that in these programs, you can use either decimal or degree/minutes/seconds for inputs.

Enter your three pairs of coordinates (it will ask for the latitude and longitude, followed by the x and y positions for each - remember, west longitudes are negative!). It will then allow you to enter other lat/lon pairs to convert to x/y values to test the transform and vise versa. Exit these test loops by entering an "E". At the end, a bunch of numbers will be spit out and also copied to the copy/paste buffer - these are the numbers you need to paste into the project (so putting them right in the buffer is quite handy!). Replace the four question marks with this output. Here's what I got for my map:

////////////////////////////////////////////////
// replace the question marks below by the //
// coefficients output from one of the //
// calibration applications //
////////////////////////////////////////////////
C_X : [ 2.7238037919E+06, 3.0745783885E+04, 0.0000000000E+00],
C_Y : [ 1.8841268898E+06, -4.2761453961E+04, 0.0000000000E+00],
C_Long : [-8.8591131783E+01, 3.2524784658E-05, 0.0000000000E+00],
C_Lat : [ 4.4061338315E+01, -2.3385547201E-05, 0.0000000000E+00],
A : 0.0,

At this point, you're almost home. You just need to specify the location that will be the default when the map loads:

// geographic default position for loading map
Def_Lat : ????,
Def_Long : ????
},

Change these two values to something convenient (and found on your map):

// geographic default position for loading map
Def_Lat : 44.0195666,
Def_Long : -88.5209833
},

As I have no more maps to add, that's it. All that's left is to build the map. For reference, I include the whole Map_Main.afterScript that successfully built my lovely map of Oshkosh:

//////////////////////////////////////////////////////////////////////
// Map Template for Map Preparation Package version 1.5 //
// //
// Copyright ©1995-97 //
// Gerd Staudenmaier, Software Development & Marketing //
// Friedrichshafener Str. 24 b //
// D-88090 Immenstaad, Germany //
// e-mail: gerds@micronet.de //
// all rights reserved ! //
// //
// IMPORTANT !!! //
// You may freely use this map template for use with "GPS Map" and //
// "GPS Map Lite" only. All other applications need the written //
// permission of the author! //
//////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////
// Read in the map by using one of the methods as described within //
// the map preparation manual //
//////////////////////////////////////////////////////////////////////
rf := OpenResFileX (HOME & "Oshkosh.rsr");
BMAP_1 := MakePixFamily (NIL, NIL, "Map");
CloseResFileX (rf);

//////////////////////////////////////////////////////////////////////
// Repeat previous statements for all further maps to be included //
// into your map package if applicable //
//////////////////////////////////////////////////////////////////////
// BMAP_2 := .......;

thisView.MapList := [
/////////////////////////////////////////////////
// This frame describes the map loaded into //
// BMAP_1. If you have more maps repeat the //
// frame for each map //
/////////////////////////////////////////////////
{
// map name as displayed in map list
Name : "Oshkosh",
// comment as displayed in "theTextView"
Comment : "Oshkosh City 2003",
// pointer to map data
theBits : BMAP_1,
// map scale (i.e. 50000)
Scale : 9800,
// scanner resolution in dots per inch (p.e. 150)
Resolution : 72,
// calculate ScaleFactor as "ROUND (Scale / Resolution)"
ScaleFactor : 136,
// coordinate style of map, must be 'RECT or 'CONE
Type : 'RECT,
// map structure version (always 1 for this template version)
Version : 1,
// remove slot "Public" if map should not be recognized by GPS Map demo version!
Public : TRUE,
////////////////////////////////////////////////
// replace the question marks below by the //
// coefficients output from one of the //
// calibration applications //
////////////////////////////////////////////////
C_X : [ 2.7238037919E+06, 3.0745783885E+04, 0.0000000000E+00],
C_Y : [ 1.8841268898E+06, -4.2761453961E+04, 0.0000000000E+00],
C_Long : [-8.8591131783E+01, 3.2524784658E-05, 0.0000000000E+00],
C_Lat : [ 4.4061338315E+01, -2.3385547201E-05, 0.0000000000E+00],
A : 0.0,
// geographic limits for map ('CONE type only)
Lat_top : NIL,
Lat_bottom : NIL,
Long_left : NIL,
Long_right : NIL,
// geographic default position for loading map
Def_Lat : 44.0195666,
Def_Long : -88.5209833
},

/////////////////////////////////////////////////
// Repeat the previous frame for further maps //
// if applicable //
/////////////////////////////////////////////////
];

// end of afterScript

Building the Map Project

All you need to do now is to build your map, using the "Build Project" choice in the "Project" menu. Well, OK, maybe one or two more things...

In the Project -> Project Settings Menu, under Project Settings, be sure you have Newton 2.1 selected as the platform. It's needed to use MakePixFamily.

In the same window, under Package Settings, pick a name for your package that will show up on the Newton. The ":GESTAUD" must be left on so the Newton knows who the package belongs to. I used "Oshkosh:GESTAUD".

There's probably one more snag you'll hit - that's problems with the default memory allocations being too small. If you run into trouble, NTK will tell you instead of dying, so it's not that bad. My map built with the following allocations:

Minimum/Preferred Size (in "Get Info"): 12000Kb

And under Edit -> Toolkit Preferences menu:

Main Heap: 9000

Build Heap: 9000

If you change any of these, you will have to quit out of NTK and restart it.

With luck though, this and Gerd's excellent instructions (you did read that PDF file, right?) should get you through. As I learn more about this software (and get more time), I'll be trying to make bigger & more interesting maps. And I'll post the results as I go.

Cheers,
-Mike