localMaps.py - Map Background Configuration Override File

January 18, 2006

Organization

Overview
localMaps.py Format
    Header
    Adding a New Map Background
    Removing a map defined in Maps.py
    Modifying the characteristics of an existing map
Placement of the localMaps.py file
Updating Map Shapefiles

Overview

The localMaps.py file provides a mechansism for a site to override entries in the supplied Maps.py file. New map backgrounds may be added, maps may be removed from the list, and existing map attributes may be changed. Refer to the Maps.py for the definition of the map background attributes and how they are used. This document will explain how to add, remove, and modify maps.

The MapFiles and localMapFiles are used to define the actual shapefile names to be used. These should NOT be hard-coded into your localMaps file.

See the server configuration overview for information on how to make changes that are supported to the map backgrounds.

localMaps.py Format

Example localMaps.py configuration file

Header

The localMaps.py file must begin with the following line. This line instructs the software to import all symbols from the primary Maps.py. Failure to include this line will result in your modifications not being recognized by the software:

from Maps import *

Adding a New Map Background

A new map background can be added through localMaps.py. Refer to the syntax requirements of defining a map in the Maps.py document. There is one additional line that is very important to add (i.e., the append line) in order for the system to recognize the new map. It is also important NOT to duplicate the Python variable name (i.e., the name left of the equals ("=") sign) of any Python variable in the Maps.py file. For example, if a map is defined as "CWAzones = ..." in Maps.py, do not create a variable that says "CWAzones = ..." in the localMaps.py file. Note that this restriction is for adding a map background. If you are overriding the characteristics of a map background that is already defined in Maps.py, then you will need to use the same Python variable name.

Here is an example of including a county map for the state of Wyoming, and having it create a set of automatic edit areas in group WYCounties):

WYcounties = ShapeFile(MAPDIR)
WYcounties.filename(CountyMapName)
WYcounties.filter(lambda x : x['STATE'] == "WY")
WYcounties.name = 'WYCounties'
WYcounties.editAreaName = ['STATE','COUNTYNAME']
WYcounties.groupName = 'WYCounties'
WYcounties.expandDomain = (2, 2, 0, 0)
maps.append(WYcounties)

In the above example, the map name of "WYCounties" is created, consisting of all counties with attribute STATE that equals "WY". In addition, edit areas will be automatically generated in the form of STATE_COUNTYNAME and will be part of the WYCounties edit area group. The very last line appends this new map definition to the list of maps to be generated. The map clip region will be expanded by 2 degrees to the north and east.

Note that if your new map background is using a new shapefile, you will also need to install the shapefile and create/modify the localMapFiles.py file to indicate the location/name of the shapefile. In all cases, the "filename" definition should use an existing mnemonic (defined in MapFiles.py or redefined in localMapFiles.py) or a new mnemonic (defined in localMapFiles.py). By using mnemonics, it is easy to keep your maps up-to-date as you install new shapefiles.

Example localMaps.py configuration file

Removing a Map that is defined in Maps.py

Removing a map that is defined in Maps.py, but not desired is easy. Find the Python variable name of the map you wish to remove by examining Maps.py. The python variable name is the name to the left of the "equals" ('=') sign.

For example, if you did not want ifpServer to generate the marine zones, find the marine zones definition in Maps.py. There are actually two maps generated. The identifiers are CWAmzones and Mzones. The following text would be included within localMaps.py:

maps.remove(CWAmzones)
maps.remove(Mzones)

Example localMaps.py configuration file

Modifying the characteristics of an existing map

You can modify the following characterstics of the map:

filename of the map shapefile - but ONLY if it is to change the mnemonic, e.g., CountyMapName, and not to specify and explicit shapefile name, e.g., c_02se05. Explicit filenames are to be specified in localMapFiles.py.
name of the map background (.name line)
filtering (.filter line)
generation of edit areas (.editAreaName line)
group name of generated edit areas (.groupName)
change (or add) the map domain expansion
Adjust the precision used when filtering out points to reduce data size

You cannot modify the following characteristic:

ShapeFile line

Filename of the Map Background

The explicit shapefile filename of the map may be changed easily, but it is not changed through localMaps.py. Instead you should use the localMapFiles.py entry to indicate the filename. Only mnemonics should be changed in localMaps.py. You should refer to an existing mnemonic, such as CountyMapName, that is already defined in Maps.py, or you can use a new mnemonic which you must define in your localMapFiles.py file.

Name of the Map Background

The format of the line is identical to that found in Maps.py. Simply repeat the line you want to change and then put the new map name. For example, if you want to change the CWAzones map name to MyCWAZones, you would add the following line to localMaps.py:

CWAzones.name = "MyCWAZones"

Filter Changes

The format of the line is identical to that found in Maps.py. Simply repeat the line you want to change and then put in the new filter string. For example, if you want to change the CWAzones filter from all zones for the CWA to all zones for the state of Ohio, you would add the following line to localMaps.py:

CWAzones.filter(lambda x : x['STATE'] == "OH")

You can also use any of the alternate methods of specifying the filter as described in Maps.py. This shows much more complex types of filters than this file.

If you want to turn filtering off completely for a map, you will need to add a completely new map definition.

Attributes in the shapefile are all treated as strings. If you create a filter that needs to do number comparisons, such as a population filter, you need to promote the string representation to a number representation using the float() function.

Generation of Edit Area Changes

Name Changes

The format of the line is identical to that found in Maps.py. Simply repeat the line you want to change and then put in the new edit area name definition. If you don't want any edit areas to be generated use this format:

CWAzones.editAreaName = []

If you want to specify the edit areas are to be based on the CWA, then use this form:

CWAzones.editAreaName = 'CWA'

Refer to Maps.py for alternate forms of the editAreaName.

Group Name for the Edit Areas

The format of the line is identical to that found in Maps.py. Simply repeat the line you want to change and then put in the new group name definition. If you don't want the edit areas to be in any group use this format:

CWAzones.groupName = ''

If you want to specify the group name, then use this form:

CWAzones.groupName = 'MyZones'

Domain Expansion

The format of this line is identical to that found in Maps.py. Simply repeat the line you want to change (or add a new line):

CWAzones.expandDomain = (0, 2, 2, 1.5)

Precision

The ifpServer will throw out vertex points of polyline and polygon maps which are closer togeather than needed for the GFE. Since opinions differ on how close points are before they are not needed, a ShapeFile can be assigned an optional attribute to define this. The attribute is called precision and is an integer or None assigned like so:

CWAzones.precision = 3

The server will then round all values in the data to this number of decimal places. Adjacent duplicate values will then be removed. This helps reduce the amount of data contained in the maps making them faster to display.

By default all polygon and polyline maps will be rounded to a precision of 2. The above example overrides this to 3. If a site wishes to do no rounding then precision can be set to None and this data reduction will be skipped entirely.

In summary, precision can be set to an integer greater than or equal to zero or None. The best way to change this value is in your localMaps.py file. The above example could be placed into localMaps.py to change the precision of the CWAzones map to 3.

Example localMaps.py configuration file

Placement of the localMaps.py file

The localMaps.py file should always be placed in the ***/etc/SITE directory as explained here.

Updating Map Shapefiles

Updating Map Shapefiles is described in the localMapFiles document. The site is responsible for obtaining and installing the correct set of map shapefiles.