PathAway Map Conversion Tools 3.0

TABLE OF CONTENTS

Installing

PWMapConvert.zip

The Map conversion tools are provided in the zip file PWMapConvert.zip. Unzip this file into a folder on your hard drive. All the tools, executables, Windows Header, Library, and DLL files are contained in this zip file. Before starting, please check the Readme.txt in the zip file.

Command Line Batch Conversion Utility

PWMapConvert.exe

Command Line:

PWMapConvert MapFileName,[ImageDepth],[PathAwayMapName],[x],[y],[wd],[ht],[GridCount],[GridGenerate],
[LatTL],[LongTL],[LatBR],[LongBR],[Compression],[ScaleMul],[ScaleDiv]

Parameters:

MapFileName: full path to map filename. Supports jpeg and bmp formats.

[PathAwayMapName]: full path to destination PathAway File name. If blank will use the same name as the MapFileName.

[ImageDepth]: 4,8, or 16. Each number represents bit depth.

[x],[y],[wd],[ht]: Crop value for the map in pixels.

[GridCount]: number of sections to divide the map into. Values 2, 3, 4, divide the map into 2x2, 3x3, 4x4 respectively. Each file gets name postfix added to it A1, A2, B1, B2 etc. Letter value is longitude, numberic is latitude. Same as in a spreadsheet app.

[GridGenerate]: specify grid ID if only generating a section of the map. ie. If you just want the top left section, specify A1.

[LatTL],[LongTL],[LatBR],[LongBR]: Top-left bottom right coordinates. Can be in NSWE format, or decimal. negative values are West, and South.

[Compression] None = No Compression. Default = Compressed

[ScaleMul], [ScaleDiv]: Scale fraction. ScaleMul/ScaleDiv. No scaling up.

Map Converter - Windows DLL

PWMapLib.DLL

The plugin DLL is a C language interface DLL.

Release Notes:

(3.10.02 - Oct 26 2004)
- Changed Functions to avoid conflict with DBConverter.
--PWSetSessionPtr changed to PWMapSetSessionPtr
--PWSetProgressCallback changed to PWMapSetProgressCallback

(3.10b1 - June 10 2004)
- Added Documentation for PWQVWinMobileMapConvert

(3.00b7 - Oct 15 2003)
- Added Documentation for PWQVMapConvert
- Added PWSetProgressCallback

(3.00b8 - Nov 26 2003) *** FUNCTION CHANGE
- Added PWSetSessionPtr
- Added session ptr to ProgressCallback
This version requires the Progress Callback to include the Session Ptr.

(3.00b9 - Dec 1 2003) *** FUNCTION CHANGE
- Fixed 32 bit BMP conversion color error (no red)

PathAway Map API Calls.

(See PWMapLib.h)

PWMAPLIB_API PWInt32
PWMapConvert(char *fileName, char *PathAwayMapName, PWInt16 maxImageDepth, PWInt16 compression, PWInt16 leftMargin, PWInt16 topMargin, PWInt16 rightMargin, PWInt16 bottomMargin, char *pLocLatTL, char *pLocLongTL, char *pLocLatBR, char *pLocLongBR, PWInt32 GridCount, PWInt32 GridGenX, PWInt32 GridGenY, PWUInt16 scaleMul, PWUInt16 scaleDiv);

PWMAPLIB_API PWInt32
PWQVMapConvert(char *fileName, char *PathAwayMapName, PWInt16 maxImageDepth, PWInt16 compression, char *pMapDefinition);

PWMAPLIB_API PWInt32
PWSetProgressCallback(PWProgressCallbackPtr pProgressFunc);

PWMapConvert

Convert to PathAway format using a Map Definition.

PWMAPLIB_API PWInt32
PWMapConvert(char *fileName, char *PathAwayMapName, PWInt16 maxImageDepth, PWInt16 compression, PWInt16 leftMargin, PWInt16 topMargin, PWInt16 rightMargin, PWInt16 bottomMargin, char *pLocLatTL, char *pLocLongTL, char *pLocLatBR, char *pLocLongBR, PWInt32 GridCount, PWInt32 GridGenX, PWInt32 GridGenY, PWUInt16 scaleMul, PWUInt16 scaleDiv);

This function allows the application to convert a map into PathAway format. The images may be scaled or sliced into separate files. Image depth and compression are required parameters.

Parameters:

FileName: full path to map filename. Supports jpeg and bmp formats. Will look for calibration files of the same name with different extensions to supplement parameters. Calibration files always override these settings. Supported calibration formats are .pwm, .jpr, .pca, and .cal. If using a calibration file only, enter the data as follows: PWMapConvert("name.bmp", NULL, 8, 1,0,0,0,0,0,0,0,0,0,0,0,1,1); name, image depth and compression are required.
PathAwayMapName: full path to destination PathAway File name. If NULL will use the same name as the MapFileName
ImageDepth: 4,8, or 16. Each number represents bit depth. ImageDepth is the highest depth to convert to. Image depth will only be decreased if its greater than the depth specified here.
compressed: 1=compressed, 0=uncompressed. Note: Palm OS supports compression in OS version 3.3 or higher. All Windows Mobile versions support compression.
startX, startY, startWd, startHt: Crop value for the map in pixels. Specify 0 for all 4 values if no cropping.
pLocLatTL,pLocLongTL,pLocLatBR,pLocLongBR: Top-left bottom right coordinates. Can be in NSWE format, or decimal. Negative values are West, and South. Optional, can be NULL
GridCount: number of sections to divide the map into. Values 0, 2, 3, 4, divide the map into 2x2, 3x3, 4x4 respectively. Each file gets name postfix added to it A1, A2, B1, B2 etc. Letter value is longitude, numberic is latitude. Same as in a spreadsheet app. Enter 0 for no grid division.
GridGenX, GridGenY: specify grid ID if only generating a section of the map. ie. If you just want the top left section, specify GridGenX=0, GridGenY=0. Only used if grid count is greater than 1
ScaleMul, ScaleDiv: Scale fraction. ScaleMul/ScaleDiv. Scaling up (ScaleMul > ScaleDiv) is not currently supported. Specify 1,1 for no scaling.

Returns:
0 if successful.
non-zero if unsuccessful

PWQVMapConvert

Convert to PathAway for Palm OS using a Map Definition.

PWMAPLIB_API PWInt32
PWQVMapConvert(char *fileName, char *PalmMapName, PWInt16 maxImageDepth, PWInt16 compression, char *pMapDefinition);

This function allows the application to specify advanced mapping parameters such as datum, projection, and multi-point calibration coordinates. The pMapDefinition string is a null terminated string containing the map calibration parameters. Each parameter is separated by a line feed.

Parameters:

FileName: full path to map filename. Supports jpeg and bmp formats.
PalmMapName: full path to destination Palm File name. If NULL will use the same name as the MapFileName.
ImageDepth: 4,8, or 16. Each number represents bit depth. ImageDepth is the highest depth to convert to. Image depth will only be decreased if its greater than the depth specified here.
compression: 1=compressed, 0=uncompressed. Palm OS supports compression in OS version 3.3 or higher.
pMapDefinition: NULL terminated Map Definition string. See API Map Definition Format below.

Returns:
0 if successful.
non-zero if unsuccessful

PWQVWinMobileMapConvert

Convert to PathAway for Windows Mobile Format using a Map Definition.

PWMAPLIB_API PWInt32
PWQVWinMobileMapConvert(char *fileName, char *WMMapName, PWInt16 maxImageDepth, PWInt16 compression, char *pMapDefinition);

This function allows the application to specify advanced mapping parameters such as datum, projection, and multi-point calibration coordinates. The pMapDefinition string is a null terminated string containing the map calibration parameters. Each parameter is separated by a line feed.

Parameters:

FileName: full path to map filename. Supports jpeg and bmp formats.
PalmMapName: full path to destination File name. If NULL will use the same name as the Map FileName.
ImageDepth: (UNIMPLEMENTED) 4,8, or 16. Each number represents bit depth. ImageDepth is the highest depth to convert to. Image depth will only be decreased if its greater than the depth specified here.
compression: (UNIMPLEMENTED) 1=compressed, 0=uncompressed. Palm OS supports compression in OS version 3.3 or higher.
pMapDefinition: NULL terminated Map Definition string. See API Map Definition Format below.

Returns:
0 if successful.
non-zero if unsuccessful

PWMapSetProgressCallback (formerly PWSetProgressCallback)

This function allows the application to receive progress notification and to allow the aborting of the processing.

PWMAPLIB_API PWInt32
PWMapSetProgressCallback( PWProgressCallbackPtr pCallBackProc);

Parameters:
PWProgressCallbackPtr: Pointer to PWProgressCallback Progress Callback function

Returns:
0 if successful.
non-zero if unsuccessful

PWProgressCallback ***

This is the function provided to the PWSetProgressCallback function. The Progress callback function must be in the form as described below:

PWMAPLIB_API PWInt32
PWProgressCallback(PWInt32 strID, PWInt32 num, PWInt32 total, void *pvSession);
typedef PWProgressCallback *PWProgressCallbackPtr;

Parameters:
strID: ID of Progress Message String. Default is 1 which is General processing. See PWMapLib.h for current string IDs.
num: current progress position
total: total number of items to process.
pvSession: void pointer set by the call to PWMapSetSessionPtr

Returns:
0 to continue processing.
non-zero to abort processing

Notes:
*** This call has changed as of 3.0b8. Existing calls to the Progress Callback must be updated to match these new parameters..

PWMapSetSessionPtr (formerly PWSetSessionPtr)

Set a session ptr to be returned with each progress callback.

PWInt32
PWMapSetSessionPtr(void *pvSession);

Parameters:
pvSession: VOID pointer. May be NULL

Returns:
0 to continue processing.
non-zero to abort processing

API Map Definition Format

The following describes the format of the pMapDefinition string used in the PWQVMapConvert call. Each parameter is separated by a CR/LF. The pMapDefinition string is NULL terminated:

pw_north = 7 = <latitude>
pw_west = 7 = <longitude>
pw_south = 7 = <latitude>
pw_east = 7 = <longitude>
proj_mode = 10 = [none|proj|gcp]
projparams = 10 = [proj=<projection id>] [lon_0=<longitude>] [lat_0=<latitude>] [lat_1=<latitude>]                            [lat_2=<latitude>] [x_0=<number>] [y_0=<number>]
datum1 = 10 = <datum id>
c1_x = 7 = <x mapcoord>
c1_y = 7 = <y mapcoord>
c2_x = 7 = <x mapcoord>
c2_y = 7 = <y mapcoord>
c3_x = 7 = <x mapcoord>
c3_y = 7 = <y mapcoord>
c4_x = 7 = <x mapcoord>
c4_y = 7 = <y mapcoord>
c5_x = 7 = <x mapcoord>
c5_y = 7 = <y mapcoord>
c6_x = 7 = <x mapcoord>
c6_y = 7 = <y mapcoord>
c7_x = 7 = <x mapcoord>
c7_y = 7 = <y mapcoord>
c8_x = 7 = <x mapcoord>
c8_y = 7 = <y mapcoord>
c9_x = 7 = <x mapcoord>
c9_y = 7 = <y mapcoord>
c1_lat = 7 = <latitude>
c1_lon = 7 = <longitude>
c2_lat = 7 = <latitude>
c2_lon = 7 = <longitude>
c3_lat = 7 = <latitude>
c3_lon = 7 = <longitude>
c4_lat = 7 = <latitude>
c4_lon = 7 = <longitude>
c5_lat = 7 = <latitude>
c5_lon = 7 = <longitude>
c6_lat = 7 = <latitude>
c6_lon = 7 = <longitude>
c7_lat = 7 = <latitude>
c7_lon = 7 = <longitude>
c8_lat = 7 = <latitude>
c8_lon = 7 = <longitude>
c9_lat = 7 = <latitude>
c9_lon = 7 = <longitude>

Parameter Definitions

proj_mode: type of calibration none is default. Optionsa re as follows:
- none: top-left and bottom-right . requires pw_north, pw_west,pw_south, pw_east.
- proj: Projection type calibration. Requires projparams and c1_* parameters.
- gcp: Known points (skewed) calibration type. Also known as Ground Control Point (gcp). Requires at least 3 known points specified in the c1_* to c9_* parameters.

projparams: required only for proj_mode=proj. defines parameters of projection. See Advanced Mapping manual for each projections required parameters.

pw_north, pw_west,pw_south, pw_east: absolute longitude and latitude points of the map.

datum1: datum that the points are specified in. See Advanced Mapping manual for details on the ID names for each datum.

c1_lat, c1_lon, c1_x, c1_y to c9_lat, c9_lon, c1_x, c1_y : known longitude/latitude points on map. Only required for proj and gcp calibration types.

Parameter Types

<latitude>: latitude in decimal format. In Datum of map. Positive Latitudes are North. Negatives are South
<longitude>: longitude in decimal format. In Datum of map. Positive Longitudes are East Negatives are West
<x mapcoord>: x Pixel coordinate of map. 0 position is the Top of the map.
<y mapcoord>: y Pixel coordinate of map. 0 position is the Left of the map.
<datum id>: See advanced Mapping manual for list of ids
<projection id>: See advanced Mapping manual for list of ids.

PWM Map Definition Format

Map calibration files can be creating by creating a file name with the identical name as the image file with a .pwm extension. This file can be opened directly in PathAway Map Manager, or used as the input parameter to the PWMapConvert program. You currently supported tags are as follows:

Parameters for Top-Left Bottom-Right Calibrated maps:
latitudeTL=44.324234
longitudeTL=-80.32566
latitudeBR=43.324234
longitudeBR=-79.32566
imageType=jpg
name=Map Name

Parameters for Projection or Known Points Calibrated maps:

Identical to API Map Definititon. See above.

Note: If you open the .jpr file, or .pwm file it will look for the image file of the same name with the image type extension. Make sure there is a <cr> after the last tag.

JPR Map Definition Format

Map calibration files can be creating by creating a file name with the identical name as the image file with a .jpr extension. This file can be opened directly in PathAway Map Manager, or used as the input parameter to the PWMapConvert program. The currently supported tags are as follows:

//image file type extension
it=jpg
//title of map
nm=Map Name
dm = horizontal datum (for reference point information)
Permitted values: See Map Projection and Datum List
Example: dm=WGS84

//For a top-left to bottom -right calibrated map:
// Top Left lat,long,x,y
//Note, the X,Ys are currently ignored
rp2=44.99322,-80.32421,0,0
// Bottom Right lat,long,x,y
//Note, the X,Ys are currently ignored. These settings should represent the bottom right
//corner of the image
rp4=43.2354,-78.32421,400,400

//For a Projected map:
// For up to 9 calibration points. rp1...rp9
rp1=44.99322,-80.32421,0,0
rp2=43.2354,-78.32421,400,400
...
rp9=43.5454,-79.33421,200,200

pr = projection
Supported values: See Map Projection and Datum List
Example: pr=Lambert Conformal Conic
pp=Central Meridian (Lambert, Polyconic, Cassini and Transverse Mercator.)
Example: pp=-106.5
p1=Latitude of origin (Lambert, Transverse Mercator and Cassini, mid- latitude if Mercator)
Example: p1=0
p3= false northing (Transverse Mercator)
Example: p3=0
p4=false easting (Transverse Mercator)
Example: p4=500000
p5=Standard Parallel 1 (Lambert)
Example: p5=34.00
p6=Standard Parallel 2 (Lambert)
Example: p6=40.00

The full jpr spec can be found at at jprdoc.pdf.