RiMap

      This document describes general functionality and configuration settings for RiMap and RiCoord libraries. The main purpose of the scripts is to plot interactive street maps for USA cities. The system consists of several scripts and libraries with datafiles.

Installation

      RiMap is standart Perl script and installation procedure is similar to any other Perl script installation:

• Copy everything to your CGI-BIN directory, preserving subdirectory structure (datafiles should be uploaded to server in binary mode, Perl scripts in ASCII mode).
• Set correct permissions for scripts (usually it is 755, but sometimes you need to set other permissions, check with your admins if you don't know this). This applies only to Unix-like operating systems.
• Check first line of scripts. Usually it should be "#!/usr/bin/perl", but again check with your admins if you are not sure.
• Run "plot.pl" script, check webserver error-log file if something does not work.

      You will need GD module installed on your server for map creation. Any version starting from 1.27 and above should work. Probably script will work with older versions too, but older versions were not tested.

      It is recommended to have libgd library (used by the Perl GD library) compiled with TrueType support. This will allow to plot inclined street labels. Script will work without TrueType support, but all text labels in this case will be horizontal or vertical.

Scripts and libraries:

• ricoord.pm - library for geocoding functions (returns geographical coordinates of given postal address and calculates distance between two points).
• rimap.pm - library for map generation.
• plot.pl - main script, which prints to the browser forms, navigation links etc.
• map.pl - script for map generation (it is just wrapper for RiMap library).

• data_hash/* - files in this directory are used by RiCoord module for geocoding functions (each state in separate file, you may delete unwanted states).
• data_hash2/* - files in this directory are used by RiCoord to find coordinates of intersections (each state in separate file, you may delete unwanted states).
• data_maps_coord/* - main datafiles for mapping function (data is divided into large number of files according to geographical coordinates of segments). This the only data REALLY needed for map creation, all other datafiles are optional.
• data_streets_coord/* - these files store streets names for files in data_maps_coord directory. They should be consistent with previous directory (if you change file in data_maps_coord directory, you should change corresponding file in this directory too).
• data_cities/* - datafiles with cities and villages names, coordinates, population.
• cities_all - information from above combined into one file.
• data_states_bound/* - datafiles with states boundary coordinates (about 140000 segments, used for large scale maps).
• all_states_bound - less acurate data of states boundary coordinates in one file (only 15000 segments, used for small scale maps).
• data_places/* - datafiles for different types of landmark features (mostly schools, hospitals, cemeteries, churches, lakes, etc.) divided into small files according to coordinates.
• data_highways/* - extracts from main datafiles with segments representing interstate highways, railroads, state and county boundaries and other major line features (used for small scale maps).
• data_highways2/* - extracts from main datafiles with segments representing interstate highways, state and county boundaries (used for small scale maps).
• data_other/data_places_bound/* - datafiles for city boundary polygons.
• data_other/data_poly/* - datafiles for polygon features (parks, lakes, water features, etc.).
• data_other/data_zcta_bound/* - datafiles for ZCTA polygons.
• data_other/data_county_bound/* and data_other/data_cs_bound/* - datafiles for county and county subdivisions polygons. These polygons are distorted (many internal points were removed to make them smaller) and used only for the purpose of land area drowing. They can't be used to draw actual boundary of county or county subdivisions (separate datafiles can be created for this purpose).
• zip_info_bin - information for ZIP-codes (state and county).
• ave_out_bin - average coordinates for ZIP-codes (ZIP code centroids).

      Some of the above mentioned datafiles are text files and can be edited by hand.

Format of the text datafiles:

data_cities/* and cities_all

 State|City name|Population|Longitude|Latitude 

Example:
 AL|Bessemer|29672| -86.956569| 33.391343 
 AL|Billingsley|116| -86.711247| 32.660416 
 AL|Birmingham|242820| -86.812740| 33.524755 

data_places/*

 State|State code|County code|Name|Type|Longitude|Latitude 

Example:
 KS|20|151|Hopewell Cemetery|cemetery|-99.00056|37.80639 
 KS|20|083|Jetmore Municipal Airport|airport|-99.89222|37.97472 
 KS|20|097|Kiowa County|civil|-99.28333|37.56667 
 KS|20|097|Kiowa County State Park|park|-99.3|37.6125 
 KS|20|047|Lewis High School|school|-99.88417|37.93639 
 KS|20|047|Lewis Ranch|locale|-99.42556|37.87222 
 KS|20|097|Lost Lake|lake|-99.04444|37.67556 
 KS|20|185|Macksville High School|school|-99.965|37.96111 
 KS|20|033|Methodist Church|church|-99.48278|37.20167 

      The data for mapping function is based on Census Tiger/Line files, which is street block level database. Therefore RiMap is best suited for large scale maps. Small scale maps require more computational power because of large number of small segments, which should be plotted on map. To solve this problem, script plots different amount of data depending on map scale. Below is the list of all possible features:

Data layers

      Map consists of different objects, combined into layers. Three types of objects exists: point, line and polygon objects.

Point objects

      Two type of point objects are exists: cities and landmarks. City name is plotted in white box. Landmarks are point objects of different kind, which identify any specific geographycal feature (like lakes, parks) or buildings (schools, hospitals, churches, etc.). Landmarks are shown as green square with label in yellow box.

Line objects

  1 - Highway unseparated
  2 - Highway separated
  3 - US Highway unseparated
  4 - US Highway separated
  5 - Secondary road unseparated
  6 - Secondary road separated
  7 - Local road unseparated
  8 - Local road separated
  9 - Forest road (not included)
 10 - Access ramp etc.
 11 - Pedestrians road (not included)
 12 - Main railroad
 13 - Industrial railroad
 14 - Railroad yard
 15 - Water unknown (not included)
 16 - Perennial shoreline
 17 - Intermittent shoreline
 18 - Perennial river
 19 - Intermittent river (not included)
 20 - Braided river (not included)
 21 - Perennial ditch (not included)
 22 - Intermittent ditch (not included)
 23 - Lake
 24 - Bay, Sea, Ocean shoreline
 25 - State boundary
 26 - County boundary

$min_code_scale[ 1] = 3;
$min_code_scale[ 2] = 3;
$min_code_scale[ 3] = 1.5;
$min_code_scale[ 4] = 1.5;
$min_code_scale[ 5] = 0.9;
$min_code_scale[ 6] = 0.9;

Polygon (area) objects

  1 - Golf course
  2 - Cemetery
  3 - National Park
  4 - Natinal Forest
  5 - State or Local Park
  6 - Island
  7 - Shoreline
  8 - Lake
  9 - River
 10 - Sea, Ocean
 11 - Unknown water feature

      As with line objects you can define at what scale area objects will be plotted, depending on area feature code:

$poly_scale[ 1] = 0.3;
$poly_scale[ 2] = 0.3;
$poly_scale[ 3] = 0.5;
$poly_scale[ 4] = 0.5;

      There are other area objects, not listed above.

City boundary

      City boundary will not be plotted for small scale maps and for very large scale maps. This is controlled by two variables:

$city_bound_min = 0.01;
$city_bound_max = 0.5;

      Color of the polygones is controled by variable: $city_color = $color{lightbrown};

ZCTA

      ZIP Code Tabulation Areas (ZCTAs) are approximate area representations of postal ZIP codes. ZCTAs were created by Bureau of Census. For more information about ZCTA and correlation between ZCTA and ZIP codes please refer to Census Website. RiMap is able to plot ZCTA polygons on the background of map under streets grid. Colors for ZCTAs are chosen randomly and script does not check if two adjacent ZCTAs have the same color (example: map_1 and map_2). To plot ZCTAs use corresponding checkbox below the map and press "Redraw map" button.

Counties

      County areas filled with different colors can be plotted (similar to above).

Layers

      Different objects on the map are combined info layers. By default all layers are visible. User can turn layers OFF/ON using checkboxes below map (selected layer will not be plotted). Please note, that there is hardcoded scale limits for each layer, which can't be changed via webinterface. If some of the layers are not plotted at specific scale, you can't turn them "ON" unless you change these limits in source code.

Query string parameters

      Only parameters "lat", "long" and "s" are required, all other parameters are optional.

General parameters (for "map.pl" and "plot.pl")

• "lat" and "long" - coordinates of map center (in decimal format).
• "s" - scale of the map (as fraction of degree from top to bottom of the map).
• "img_size" - size of the map in pixels.
• "px1", "py1" and "txt" - plot marker at coordinates "px1" and "py1" and text label with text equal to "txt".
• "pcb=0" - turn OFF city boundary polygons.
• "psb=0" - turn OFF state boundary.
• "pct=0" - turn OFF county boundary.
• "psl=0" - turn OFF street labels.
• "ppl=0" - turn OFF landmark labels.
• "prr=0" - turn OFF railroads.
• "pcm=0" - turn OFF cemetery polygons.
• "ppk=0" - turn OFF park polygons.
• "pwb=0" - turn OFF water bodies polygons.
• "pst=0" - turn OFF streets.
• "phw=0" - turn OFF highways.
• "pcl=0" - turn OFF city labels.
• "prv=0" - turn OFF rivers.
• "psh=0" - turn OFF shoreline.
• "pgr=0" - turn OFF coordinates grid.
• "zcta=0" - turn ON ZCTA polygons.
• "cnt=0" - turn ON county polygons.
• "cs" - color scheme.

Parameters for "plot.pl"

• "lat" and "long" - coordinates of map center (both decimal format and DD MM' SS" can be used). Please note, that when you click on the map to recenter it, coordinates of mouse pointer are sent to script as "point.x", "point.y" and in this situation coordinates of map center are not equal to "lat" and "long", but calculated using all four parameters.
• "addr", "town", "zip", "state" - script tries to find coordinates of given postal address and plot map centered at this location. If both address and "lat" and "long" parameters are specified, script will plot map using geographical coordinates, address parameters are ignored.

Other parameters

      Other parameters are used to define at which scale script will plot different features:

• $min_place_scale - defines when put landmark features on map.
• $min_street_scale - defines when put street labels on map.
• $min_highway_scale - highways markers.
• $min_city_scale_1000 - defines when city markers will be printed on map for cities with population less then 1000 inhabitants (there are several similar parameters for cities with different population).
• $max_scale - at this scale script will plot only highways and states boundaries.
• $max_scale2 - at this scale script will plot only states boundaries.
• $plot_scale_bar - defines if scale bar will be printed at map left bottom corner.
• $img_size = 500; - default image size.
• $max_img_size = 1000; - maximal allowed image size.

Plot user defined data

      There is possibility to plot your own data over maps produced by RiMap. You can put own labels on the map or you can draw own primitives.

Labels

      In order to plot custom label on the map you have to create text file with name "locations" in the directory "locations". Each line of this file represents one specific landmark feature you want to label. Format of the file:


 Name1|address|city|zip|state|long|lat| 
 City Mall|31 Main St.|New York|55555|NY|-78.02|41.01| 

Primitives

      Also you can draw your own lines and polygons on the map. Using this feature you can show exact positions of individual buildings or other landmark features. Primitives should be defined in the file "my_data/all_data". Format of the file:


 line|black|1|-78|41|-78.02|41.01 
 polygon|black|pink|1|-77.95|40.99|-77.96|40.98|-77.94|40.96 
 label|My string|5|black|green|1|black|red|3|black|0|-97.353|47.963 

• Lines - first field defines type of the primitive, second field defines color, third - thickness (currently not used), last four fields are coordinates of line end points.
• Polygons - first field defines type of the primitive, second and third fields - color of contour and inner area respectively, fourth field - thickness of contour (currently not used), rest of the fields - coordinates of points.
• Labels - type of primitive; string; size of marker (can be 0); contour color of marker; fill color of marker; plot or no box around text ("1" or "0"); contour color of box; fill color of box; font size ("1" - small, "5" - big); color of text; orientation ("0" - horizontal, "1" - vertical); longitute; latitude.

      Available corol names can be found in function "create_image" in file "rimap.pm". You can add other colors there.

Show image statistics

      Some statistic information about map generation can be plotted over image.

Map generation time

      Map generation time depends on many factors: scale, number of objects, size of objects. By setting $show_generation_time variable to "1" you can print map generation time in the left upper corner. Then turn OFF one or several layers to see, which layer takes most time.

Number of objects plotted

      Set variable $show_object_stat to "1" to see number of objects processed and plotted. Statistics will be printed in such way: "Lines: 1000/10000; Polygons: 50/200". This means that 10000 line objects and 200 polygon objects were processed, and 1000 lines and 50 polygons were plotted on the map.

Fonts

      RiMap uses GD library to plot maps. GD has several built-in fonts, and string can be plotted either in normal horizontal orientation or rotated 90 degrees. However, if GD library was compiled with support of TrueType fonts, street names can be plotted along streets using any TrueType font installed on your computer. Set path to font in "$font_path" variable.

Map datum and projection

      TIGER database uses North American Datum 83 (NAD 83) for geographic coordinates. Large scale maps are plotted in scaled Lat/Long projection, where meridians and parallels are stright and intersect at right angles, but size of one degree arc along meridian and paralel is not equal, so that distance is preserved at map center point. Let L and F be longitude and latitude of point of interest and L0 and F0 be longitude and latitude of map center respectively. Then

X = (L-L0) * COS(F0)
Y = F

      Small scale maps (over 5 degrees in vertical dimension) are plotted in sinusoidal projection:

X = (L-L0) * COS(F)
Y = F