User Guide > Mapping with PV-WAVE > Accessing Other Map Datasets
  

Accessing Other Map Datasets
Two map datasets are included with PV‑WAVE: the World Databank II dataset and the USGS Digital Line Graph Dataset. These built-in map datasets are subsets of the actual datasets, and are included to provide relatively fast and efficient access to map data while still maintaining adequate resolution when a small area is plotted.
Two procedures are provided to read these datasets: usgs_db.pro and world_db.pro. These procedures are called by the MAP procedure.
A procedure called ascii_db.pro is also provided in the mapping library to help you read your own map datasets that are in ASCII format. You can use the ascii_db procedure as a template for reading a user-defined dataset.
If you use the MAP procedure with the Data keyword set to ascii_db, use the Select keyword to specify the name of the file containing the ASCII data. The ASCII file containing the data must conform to the following format:
*Two columns of numbers, either comma or space separated.
*The beginning of each polyline or polygon indicated by a record with “999” in the first column and the color in the second column.
*This record is followed by any number of records containing pairs of coordinates for the X and Y or longitude and latitude.
Writing a Procedure to Read a Map Dataset
To use any map dataset, PV‑WAVE must be given specific information about the dataset. This information is placed in a procedure file that is executed when the MAP procedure is called with the Data keyword.
A procedure for reading a map dataset reads and subsets the map dataset using attribute selections of the data. A map dataset procedure must contain the following four positional parameters:
*data—A 2-by-n floating point array of longitude/latitude points (in degrees) returned from the dataset.
*index—A 2-by-m long array containing the starting and ending indices of each polyline or polygon in the map dataset.
*select—A variable passed from the MAP procedure via its Select keyword. This passed variable can be an unnamed structure containing as tag fields the names of section criteria recognized by the map dataset (such as cities, countries, rivers). The use of this variable is entirely defined within the map dataset procedure.
*resolution—A variable containing the number of points to skip in a large dataset. A higher resolution value improves performance at the expense of map detail. This variable must be present in the user defined procedure, but its use is optional and can be ignored if it is not needed.
Another way to control the size of the dataset returned by the dataset-reading procedure is to use the !Map.X.Range and !Map.Y.Range system variables. These system variables contain minimum and maximum longitude and latitude values for the current plot, and can be used to subset the dataset and reduce the size of the data array returned.
When the MAP procedure is called, a new system variable !Map is created to contain parameters used by the mapping routines. These parameters are also used in user defined projections and user-defined map dataset procedures. For information on the fields of this system variable, refer to the file map.pro in:
(UNIX) $RW_DIR/mapping-2_0/lib/map.pro
(WIN) %RW_DIR%\mapping-2_0\lib\map.pro
The dataset-reading procedure returns the data to be projected and plotted based on the selection criteria, area being plotted, and optionally the resolution desired. The procedure can read the entire map into a variable the first time it is called and then subset the data directly from memory, as is done for the World Databank II and USGS Digital Line Graph Dataset procedures. Or, the procedure can read the dataset from disk each time the procedure is called, which would be appropriate for very large datasets.
Example Programs Are Provided
For more information on how to create a procedure to read a map dataset, look at the following procedures that are provided with PV‑WAVE:
(UNIX) $RW_DIR/mapping-2_0/lib/world_db.pro
$RW_DIR/mapping-2_0/lib/usgs_db.pro
$RW_DIR/mapping-2_0/lib/ascii_db.pro
(WIN) %RW_DIR%\mapping-2_0\lib\world_db.pro
%RW_DIR%\mapping-2_0\lib\usgs_db.pro
%RW_DIR%\mapping-2_0\lib\ascii_db.pro
Use these programs to guide you in writing your own procedure to read a dataset.
 
note
To convert data stored as degrees, minutes, and seconds to a single floating point value for use in the mapping routines, the formula is:
value = degrees + minutes / 60.0 + seconds / 3600.0

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.