DIGITISE and PROJECTOR utility programs for digitising and manipulating basemaps, released August 1993, 1997 by Peter Bird Department of Earth and Space Sciences University of California Los Angeles, CA 90095-1567 (310) 825-1126 pbird@ess.ucla.edu Boilerplate ----------- (C) Copyright 1991, 1992, 1993, 1996, 1997 by Peter Bird and the Regents of the University of California. Colleagues are free to use, modify, and distribute this software at no charge, but subject to the following conditions: 1. The programs and/or source code shall not be modified in a way which hides their author or origin. 2. These notices shall be distributed together with any copies of the source code or executable programs. While you may recover your actual costs of blank media and handling, no other fee or price shall be charged for copies you distribute. 3. By using this package, you assume an ethical obligation to help the author improve it, by reporting any bugs or defects together with a complete accounting of relevant circumstances. Purpose ------- To accept the data flowing from any digitiser, display it on-screen, and record it as disk files in a standard format. To simplify coordinate transformations between various projections, with their (x,y) coordinates, and spherical coordinates (lon,lat). Directory PATH listing for Volume DIGITISE Note: On Unix systems, these filenames may be in lower-case! ------------------------------------------------------------ \: (the "root" directory) | READ_ME.6 (this file; different from READ_ME.1, ...) | DIGITISE.EXE (the digitising program, for DOS or Windows) | PROJECTOR.EXE (plots digitised files and transforms coordinates; | compiled for Windows 95, 97, NT, or 2000) | GRATICUL.EXE (creates a grid of lat/lon lines in .DIG format, | for DOS or Windows) | +---SOURCE (a directory of source code) | DIGITISE.BAS (BASIC source code for DIGITISE, part 1) | DIGIT2.BAS (BASIC source code for DIGITISE, part 2) | DIGITISE.MAK (BASIC source code for DIGITISE, part 3) | PROJECTOR.f90 (Fortran 90 source code for PROJECTOR) | GRATICUL.FOR (FORTRAN77 source code for GRATICUL) | \---WORK (a directory of sample working files) POINT_M1.MOD (a sample digitiser-mode settings file) LINE_M2.MOD (a sample digitiser-mode settings file) CALXY.DIG (a sample digitised map, of California) BSCOASTX.DIG (a sample digitised map, of Alaska) AI4FRAME.AI (an Adobe Illustrator plot file, needed by PROJECTOR to create new plot files from your digitised data) Operating Systems (for .EXE files): ----------------------------------- DIGITISE was written for the most basic versions of DOS, and should run on any operating system that emulates DOS, including Windows 95, 98, NT, or 2000. However, it is only common sense that you may have trouble if you try to multitask; generally, I would advise that DIGITISE should be the only program running. Because of its origins, DIGITISE cannot support long file names or directory names. When you specify the names of input and output files from within the program, each directory and file name must follow DOS rules, which are: -no longer than 8 characters (the program will add a period and file-type extension); -no spaces within names (but you can use underscore _); -certain characters are forbidden (*, \, >, <, |, ...); -upper-case and lower-case are considered equivalent. DIGITISE will attach a standard extension of .MOD or .DIG to each file it creates; this is automatic, and you should not try to type these extensions. Only type the 1-8 character name that appears to the left of the period. DOS: DIGITISE was written and debugged in MS-DOS, and works best under DOS. This is because it has complete control of the PC and does not have to share any resources, which might create timing problems. However, I have been told that it does not operate properly with "Japanese DOS". This is probably a trivial problem to fix (if you have the Microsoft Basic 7.0 compiler) involving the different format of the ASCII text data which the program receives from DOS when it uses the SHELL command to find out the current directory, filenames, etc... However, I don't have a copy of "Japanese DOS" so I cannot fix this problem for you. Windows 3.1: I have used DIGITISE frequently under Win3.1. It is somewhat balky due to timing problems. In particular, when digitizing in LINE_M2 mode (continuous stream of points), it emits the "warning scream" (continuous pulsing tone) of imminent buffer overflow for some users but not for others. However, it seems to work properly, and not lose any data. Because Win3.1 uses "cooperative" multitasking, any application can seize control for many seconds at a time, during which time incoming data will be lost at the COM port. Therefore, DIGITISE should be the only application running. Windows 95: Not tested, but should work. As with Windows 3.1, Windows 95 uses "cooperative" multitasking for old 16-bit applications, so these are likely to grab control for long periods, during which time incoming data will be lost at the COM port. Therefore, DIGITISE should be the only application running. Windows NT: I have used DIGITISE frequently under Windows NT 4.0 W/S. Again, it works but may be slightly balky. There may be occasional 8-second "hangups" associated with opening the channel (not in the middle of digitising, fortunately) which I do not understand. One important note is that when setting up the "Properties" of the DIGITISE.EXE file, you should have the "Compatible Timer Hardware Emulation" box UN-checked (clear) in the "Windows NT" sub-menu of the "Program" page of Properties of DIGITISE.EXE. Also be careful that the same box is un-checked in the Properties of any shortcut that you create. P.S. When I switched from a 66 Mhz PC to a 400 MHz PC recently (both running Windows NT 4 W/S), most of the timing problems disappeared.) OS/2: My Microsoft BASIC 7.0 compiler claims that the .EXE file it creates will run under real mode OS/2, but not under protected mode. I have not tried either version. Good luck. Other systems: Any system which emulates DOS gives you a good chance of running DIGITISE. Another requirement is that it supports (and has) at least one RS-232 type serial port. On other systems, it would be necessary to get a Microsoft BASIC compiler (or compatible software) for that system, and recompile the source code after necessary modifications. Frankly, I would advise looking for other digitising utilities, and writing a short format-conversion program in your favorite language to shift the output to my .DIG format. Comments on Data Rates and Buffering: ------------------------------------- There may be some old equipment out there that transmits at 300 baud. Since this is about 30 ASCII characters/second, it takes most of a second to send one digitized point. My program is written with this in mind, and includes a 1-second pause followed by a buffer-clearing operation at several points to increase the chances that the program and hardware are in sync. You can help by waiting for the program to display the whole horizontal bar-graph (and sound the scale on the PC speaker) before beginning a new polyline. At the other end, very high data rates (38k baud and up) are supported by some newer hardware. I am sorry to say that my program only supports up to 9600 baud, because this was the highest supported by the BASIC compiler I used. However, this should not be a problem, as newer hardware can always drop back to old- fashioned "low" rates for backward compatibility. In most cases, my program should set the baud rate for you when it opens the COM channel, and it should NOT be necessary to use your operating system (e.g., Windows Control Panel) to reset these rates. However, this is one thing to try if you cannot establish communication. In Windows NT, I use Start/Settings/Control Panel/Ports/COM2/ Settings/ Baud rate: 9600, Data bits: 7, Parity: Even, Stop Bits: 1, Flow control: none (or Hardware, or Xon/Xoff; it doesn't seem to make any difference), Advanced/ Com Port: 2, Base IO address: 2f8, IRQ: 3, [ ] FIF0 enabled (NOT!). These are fairly standard settings, and might work for you. Just for insurance, use the same settings for baud rate, parity, data bits, and stop bits in all three places: -at your digitiser's controls (setup menu, DIP switches, ???); -in Control Panel/Ports/COMx; -in DIGITISE. There are either 2 or 3 levels of buffering in operation to decrease the chances that you will outrun the recording capacity of your PC. First, some newer serial ports (those based on the faster 16550 UART chip instead of the old 8250 UART chip) have hardware buffering on the adapter card, and support FIFO (First In is First Out) access. If you have one of these, then set your software (device driver) to turn it on. For example, in Windows NT 4.0, the Control Panel has an entry for Ports, and FIFO is an optional check-box under each serial port. (Be careful, as Peter Norton advises that Win NT cannot always tell whether you have the new or the old type of serial port installed!) A second level of software buffering is offered in the BASIC interface to COM1 or COM2; I have set this buffer to 32k bytes during compilation. Finally, my program places the highest priority on getting the data out of this buffer and into its own (larger) software buffer. Only when there is no data waiting will it take the time to update the graphics on the screen. Thus, you will rarely have to limit your tracing speed (unless you have an original 5 MHz PC, or a 300- or 1200-baud digitiser). Suggestions for Use: -------------------- The programs are all self-guiding and internally documented. Connect any type of digitiser to serial port COM1 or COM2, and run DIGITISE, which includes menu-driven utilities for entering communications parameters like baud rate, parity, end-of-record markers, etc. It also allows interactive testing to be sure these are correct. Next, return to the main menu and go to work. The program will require you to enter the coordinates of the corners of a rectangle around the area you intend to digitise. This area will be displayed on-screen as you work. Points outside this frame will be correctly recorded in the .DIG files, but they may not be visible on the screen display. The output files (*.DIG) are in plain-ASCII, and may be edited in any word processor if necessary. For maximum portability (to and from my other programs), try to keep the numbers in the same scientific- notation format and in the same columns of the file as in the sample .DIG files provided. There is an option to delete the most recent line segment if you feel that your hand jerked, or anything else went wrong. For removing a line segment in the middle of a file, you must use a text-editor on the .DIG file. In this case, it is useful to have the optional label (title) line at the beginning of each polyline. Notice that if you want labels (titles) for each line segment in your output, then you will have to return to the keyboard at the end of each segment to terminate it (by pressing any key) and to enter the title of the next. However, if you do not use labels, and if your digitiser has more than one button, then you may be able to set it up to use a special button to terminate one polyline and begin another, without leaving the digitiser. Check whether your digitizer sends an extra character along with the x and y coordinates. If you need to work with maps in different projections, then use utility program PROJECTOR to convert the files to (lon,lat) in degrees, and then use PROJECTOR again to reproject them (if needed). This program will prompt for the necessary parameters defining the projection. Be aware of an important distinction. When you want to convert flat-Earth (x,y) files to round-Earth (lon,lat) files, then you need to enter the correct projection parameters of the map that you digitised!!! (Later, if you run PROJECTOR again to plot (lon,lat) files or to convert (lon,lat) files to (x,y), you are free to choose any map projection you want.) If you are planning to use PROJECTOR to convert digitized (x,y) to (lon,lat), then you have to choose the right units when you digitize. The choice is set when you run [Scaling] and enter the 4 values: XMIN, XMAX, YMIN, YMAX; it cannot be changed afterward. What you need to enter at this point are the dimensions of the bounding rectangle IN THE EARTH-SIZED PROJECTION PLANE, not the meter-sized dimensions that you read from a ruler! The principle is the same as if you were digitising a graph of temperature versus date: you would enter temperatures for YMIN and YMAX, and dates for XMIN and XMAX. (The actual lengths of each axis in mm, cm, or inches would be irrelevant.) Just imagine that the small scale of km (or miles) provided in the map legend has been expanded into a full set of Cartesian axes along the margins of the map, and read the values from these. For example, suppose I have a map of the USA at 1:4,000,000 and I have drawn a rectangle 0.4 m wide and 0.3 m high, extending South and West from my origin (x=0, y=0) which is at the projection point, in the center of the map. (Note: If you choose an x,y origin in some random place, PROJECTOR will be able to accomodate your choice.) I would enter: XMIN: -1.6E6 (meters) XMAX: 0. YMIN: -1.2E6 (meters) YMAX: 0. which are the products of the (x,y) limits in ordinary lab units (meters) with the map scale of 4.0E6, giving the size of the equivalent rectangle on the real Earth (neglecting curvature). (If you don't like meters, PROJECTOR will also accept cm, mm, inches, feet, and miles, but I always recommend SI units.) The point to remember is that regardless of units, XMIN...YMAX have to record HOW BIG THINGS ARE ON THE ACTUAL PLANET, not on the scaled-down map that fits on your table. Do not worry that the scale changes across the map; create your x/y Cartesian axes using the scale of the least-distorted part of the map, usually at its center, and PROJECTOR will take care of the rest. To have a look at the sample files provided (California and Alaska), you have only to designate them as Display files in DIGITISE, and begin working on any area in the vicinity of the origin (0,0). Their units are meters. (The California map is rotated to fit in a "landscape" graphics format.) Another way to look at your output (more elegant) is to load your .DIG files as designated Basemap files in program DRAWGRID, which is in directory .../neotec/drawgrid. If you have converted maps digitised in (x,y) format to spherical (lon.,lat.) coordinates with PROJECTOR, and you want to check them for correctness, then load them as designated Basemap file in program ORBWEAVE, which is in directory .../neotec/shells. (Unfortunately, both of these programs are very fussy about number formats; use exactly the same columns as in output .DIG files from DIGITISE, and precede positive numbers with a redundant +, et cetera.) If you want to make a beautiful map from your .dig files, then use the .ai (Adobe Illustrator) file produced by PROJECTOR. Loading this into Adobe Illustrator 7 (for Windows 95, Windows NT, or MacOS) or into Adobe Illustrator 4 (for Windows 3.1), you can change the line color and weight, fill in areas within lines with color, add text labels, etc..... You now have access (through AI and Windows) to the full range of printers/plotters/slidemakers which graphic artists customarily use. Enjoy! GOOD LUCK! Peter Bird 6 November 1997