YLUPC
DataStyling – Yukon Planning Atlas

Data Styling

Table of Contents

  1. PlanYukon Regional Planning Database Best Practices Wiki
    1. Background
    2. Purpose
    3. Framework
    4. Roles
    5. Acknowledgment
  2. Getting Started as an Administrator
    1. Introduction
    2. Helpful Software
      1. Text editor
      2. Subversion
        1. Troubleshooting
      3. MS4W
        1. Trouble-Shooting
    3. Trac
    4. WinSCP
  3. Data File Management
    1. Valid Spatial Data Sources
      1. Vector Files
      2. Raster Files
      3. Non-local Data
    2. Accepted Data Projection
    3. Data File Naming Conventions
    4. Data File Contents
    5. Data File Storage
    6. Database Architecture
      1. Specifications
      2. Tables
        1. groups
        2. layers
        3. layers_perm
        4. spatial_ref_sys
        5. themes
        6. themes_perm
        7. users
        8. widgets
        9. widgets_perm
    7. Government of Yukon CSW Catalog WMS Service
      1. GetCapabilities
      2. Supported Projections
      3. Native Projection
      4. Layer Names
      5. Scale Ranges
  4. Data Styling
    1. Background on MapServer .map files
    2. Theme Files
    3. Template Files
    4. Layer Files
    5. .Lay Guidelines
      1. Naming
      2. Groups
      3. Layer TYPEs
      4. Metadata
    6. Using Classes
    7. Using Styles
    8. Labeling
      1. Available Fonts
      2. Label Size
      3. Label Scale
      4. Label Force
      5. Label Partials
      6. Label Minfeaturesize
      7. Label Buffer
      8. Label Priority
    9. Symbols
    10. Projection
      1. EPSG Usage
      2. PROJ.4 Usage
    11. Using Scales
      1. MINSCALE and MAXSCALE Deprecated
      2. Atlas Scale Ranges
  5. Metadata Management
    1. Implemented Standards
    2. Layer Metadata
      1. Atlas Keywords
    3. Theme Metadata
    4. Accessing Metadata through the Atlas
    5. Accessing OGC Metadata through the WMS Service
      1. GetCapabilities Request
    6. Management Tools
      1. ArcCatalog?
        1. About
        2. Functionality
        3. Assessment
      2. CatMDEdit
        1. About
        2. Functionality
        3. Assessment
      3. gvSIG
        1. About
        2. Functionality
        3. Assessment
  6. Data Processing Work Flow
    1. Step 1: Preparing the Spatial Data
      1. Guidelines
      2. Getting the Required Tools
      3. Documentation For Command Tools
      4. Useful Commands
        1. Reproject a Vector File
        2. Merge 2 Vector Files
        3. Keep Only Specific Attribute Values
        4. Keep Only Specific Fields
        5. Prep Raster Files
    2. Step 2: Create a .lay file
      1. .lay Templates
        1. Vector File Template
        2. Raster File Template
        3. WMS/OGC Template
      2. Generate .lay Metadata
      3. .lay Guidelines
    3. Step 3: Submit for Publication
    4. Step 4: Publishing a Layer
    5. Step 5: Add Layer to Existing Theme File
    6. Step 6: Verify Layer Processing
    7. Refresh Layer Data
  7. Quality Control
    1. Layer Quality Assurance Checklist
      1. Published Layer QA Checklist Forms
    2. Data Optimization Checklist
    3. Publishing Atlas Data
      1. WMS Mapfile Location
      2. Publish Local Data to WMS
      3. MapServer Required Metadata
      4. WMS GetCapabilities Warnings
      5. GeoConnections Discovery Portal Registration
  8. Recommended Data Management Tools
    1.  MXD2WMS
    2.  FGS
    3.  MapServer for Windows
    4.  QuantumGIS
    5.  uDig

Background on MapServer .map files

The basic configuration file for display of spatial data in MapServer is the .map file (or “mapfile”). The mapfile is an ASCII (text) file that is separated into objects. MapServer parses the mapfile from top to bottom, which essentially means that an object placed at the end of a mapfile will be drawn last (or on top) in the output map image. Comments are distinguished by a “#” character.

The Atlas was one of the first public applications to incorporate MapServer's ability to store individual layers from a mapfile into separate files. Individual files can be loaded into a mapfile using the INCLUDE parameter, which was added to the Mapserver 4.10 release.

For more information on the .map file, please see the  Mapfile Reference.

Theme Files

In order to differentiate between the various included files and the .map file, the Atlas has adopted the term “theme file” to describe the .map file. The Atlas' theme file contains relative paths to various objects, which includes the various data layers and reference objects. An example of a theme file follows:

  • Name: base
  • Description: Base mapfile 
MAP
  # include reference objects
  INCLUDE "../templates/template.ref"
  #
  # Start of layer definitions
  #
  INCLUDE "../layers/usa/usa_outline.lay"
  INCLUDE "../layers/canada/base/1m/provinces.lay"
  INCLUDE "../layers/yukon/base/yukon_dem.lay"
  INCLUDE "../layers/yukon/base/yukon_dem_250k.lay"
  INCLUDE "../layers/yukon/base/yukon_border_250k.lay"
  INCLUDE "../layers/yukon/base/yukon_border_1m.lay"
  INCLUDE "../layers/canada/base/1m/roads_atlas_of_canada_1m.lay"
  INCLUDE "../layers/canada/base/1m/roads_atlas_of_canada_1m_shields.lay"
  INCLUDE "../layers/canada/base/1m/populated_places.lay"
END # Map File

Template Files

In order to differentiate between the various included files and the .map file, the Atlas has adopted the term “template file” to describe the objects common to every theme file. A template file has a “.ref” extension and contains objects such as reference maps, scalebars, and the map extents. An example template file follows: 

STATUS ON
SIZE 400 400
SYMBOLSET “../../etc/symbols.txt”
EXTENT -117257.05822339 552592.110573445 1120576.60394401 1790425.77274085
UNITS METERS
SHAPEPATH "../../data"
IMAGECOLOR 156 188 217
FONTSET “../../etc/fonts.txt”
WEB
  ...
  METADATA
    ...
  END
END
# Map projection
PROJECTION
  ...
END
LEGEND
  ...
END
SCALEBAR
  ...
END

Layer Files

In order to differentiate between the various included files and the .map file, the Atlas has adopted the term “layer file” to describe files with the “.lay” extension, which contain a single MapServer layer. A layer is used to style a single data source, and contains objects such as metadata, projection, class, and style. It is important to note that the DATA path in the layer file should be relative to the SHAPEPATH that is specified in the associated template (.ref) file. For representation of data in more than one style, such as outlined, hatched or solid, it is necessary to create multiple .lay files, appending hatched or outline to the layer name, so its easier to see that multiple files may need updating. An example layer file follows: 

LAYER
  # layername must not contain any spaces or special characters
  NAME "footprints_50k"
  GROUP "North Yukon Footprints"
  METADATA
    ...   
  END
  TYPE POLYGON
  STATUS ON
  DATA "../data/yukon/thematic/50k/footprints/ny_footprint"
  # layer projection
    # this is the actual projection of the data
  PROJECTION
    ...
  END
  # style the data
  CLASS
    NAME 'Footprints'
    STYLE
      OUTLINECOLOR 120 120 120
      COLOR 205 207 202
    END 
  END
  TEMPLATE "dummy.html" 
END # layer

.Lay Guidelines

Naming

.lay files should be all lowercase, without spaces. A more human-readable name (with capitalization and spaces) can be used in the METADATA code block in the "ows_title" line.

Groups

It is good practice to use the GROUP parameter in a layer to combine common layers (such as a roads layer and its associated highway shields layer) into a single legend entry. See LayerGroups for a list of groups in use. Note that this grouping is different from CatalogGroups, in that layers are grouped by theme, and not by extent. The Atlas engine uses the GROUP parameter to group the layers, but used the "ows_group_title" parameter in the METADATA code block to label it.

Layer TYPEs

The Atlas supports all of MapServer's layer types, which include RASTER, POINT, LINE, POLYGON, and ANNOTATION. Point layers that contain labels should use the ANNOTATION layer type, so that specific label logic for annotation layers can be used by Mapserver.

Metadata

Please see the Metadata Management page.

Using Classes

CLASS objects are used to provide styles for a layer. A layer can be classified using the CLASS object's EXPRESSION parameter. Mapserver supports three types of expressions:

  1. String comparison
    • e.g. “highway”
    • fastest computationally
  2. Regular expression
    • e.g. /^4|^100$/
    • should be used if the data cannot be separated into individual files
  3. Logical expression
    • e.g. ([POPULATION] > 1000)
    • very slow computationally, and should be avoided

For more assistance, refer to the  MapServer Expressions howto.

Using Styles

Style objects are used to provide appropriate colours for a classified layer. A single CLASS can have multiple styles on top of each other. An example of multiple styles could be a roads layer, where you have a darker colour outside of a lighter colour for a road feature, as follows: 

	LAYER
	  ...
	  CLASS
	    NAME “Roads”
	    STYLE
	      COLOR 213 211 205
	      WIDTH 4
	    END
	    STYLE
	      COLOR 234 230 225
	      WIDTH 1
	    END
	  ...
	END

Note that the above example requires MapServer version >= 5.0.

Labeling

Available Fonts

The available fonts to use within the Atlas are listed in the /etc/fonts.txt file, as follows:

  • sans
  • sans-bold
  • sans-italic
  • sans-bold-italic
  • serif
  • serif-bold
  • mono
  • mono-bold
  • mono-italic
  • mono-bold-italic

Italic fonts should only be used for water features.

Label Size

The recommended default label size is 8. Size can vary with scale, however a size larger than 8 is not recommended.

Label Scale

Labels can be useful at any map scale, however it is important that the labels do not prevent other labels from appearing.

Label Force

MapServer's LABEL object's FORCE TRUE parameter will force all labels for that layer to appear and knock out other layer's labels; therefore FORCE TRUE should never be used in a layer in the Atlas, unless for debugging purposes only.

Label Partials

MapServer's LABEL object has a PARTIALS TRUE parameter that will allow partial labels such as “White” of “Whitehorse” to appear on the edge of a map image. PARTIALS TRUE should therefore never be used in the Atlas (the default is FALSE).

Label Minfeaturesize

MapServer's LABEL object has a MINFEAUTURESIZE parameter to specify the minimum size of a feature to be labelled, in pixels. This is very useful to avoid small features such as islands being labelled when the user is zoomed far out.

Label Buffer

MapServer's LABEL object has a BUFFER parameter to specify the padding around labels, in pixels. For example, if a value of 5 is specified, all labels from other layers will not be drawn within a 5 pixel radius of this layer's label.

Label Priority

MapServer version >= 5.0 contains the PRIORITY parameter in a LABEL object, which can be used to set a higher priority for a layer's labels. The possible priority values range from 10 (highest) to 1 (lowest). For more information please see Mapserver's Mapfile Reference.

Symbols

The available symbols to use within the Atlas are listed in the /etc/symbols.sym text file, as follows:

  • tent
  • star
  • triangle
  • square
  • plus
  • cross
  • circle
  • highway (pixmap)
  • roads (pixmap)
  • community (pixmap)
  • town (pixmap)
  • city (pixmap)

MapServer does support the use of PNG and GIF symbols (“pixmaps”). For more assistance, please see  MapServer's Symbology Reference.

Projection

As mentioned previously, MapServer does support reprojection-on-the-fly, however all Atlas data should use the EPSG:3578 projection. It was recently discovered in MapServer that lookups to the epsg file cause a slight performance hit, therefore the full PROJ.4 definition of the Yukon Albers projection should be used in each layer as much as possible. Here are examples of both methods:

EPSG Usage

  PROJECTION
    “init=epsg:3578”
  END

PROJ.4 Usage

  PROJECTION
    "proj=aea"
    "ellps=GRS80"
    "lat_0=59"
    "lon_0=-132.5"
    "lat_1=61.667"
    "lat_2=68"
    "x_0=500000.0"
    "y_0=500000.0"
    "units=m"
    "no_defs"
  END

Using Scales

MINSCALE and MAXSCALE Deprecated

As of MapServer 5.0, the use of the mapfile parameters MINSCALE and MAXSCALE are no longer recommended. Therefore all Atlas layers should use the proper MINSCALEDENOM and MAXSCALEDENOM parameters instead.

Atlas Scale Ranges

All Atlas layers should try to use the following MapServer scale ranges wherever possible:

Break ReferenceMaxscaledenomRange
020,0000 - 20000
1100,00020001- 100000
2500,000100001 - 500000
31,500,000500001 - 1500000
42,500,0001500001- 2500000
59,000,0002500001 - 900000

Here are ranges for specific Atlas layer types:

Layer DescriptionReal-world ScaleMapServer Scale
zones, planning areas1,000,000500,000
regions, habitat areas, placenames, transportation250,000125,000
districts, footprints50,00025,000