MS RFC 26: Version 5 Terminology Cleanup

Date

2007/04/21

Author

Steve Lime, Havard Tveite

Contact

steve.lime at dnr.state.mn.us, havard.tveite at nmbu.no

Status

Implemented

Version

MapServer 5.0

MapServer terminology is mostly good and consistent, with a few exceptions. The two that generate the most confusion and TRANSPARENCY (layerObj) and various scale referencing parameters (e.g. MINSCALE).

Another change would be changing the symbolObj STYLE parameter to PATTERN instead. This would be simply to avoid confusion with the classObj STYLE.

The The purpose of this proposal is to make MapServer even easier to use, removing confusion that can arise in cases of inconsistent terminology.

TRANSPARENCY

1. Overview

TRANSPARENCY is used in the MapServer mapfile layer object for what is in fact opacity (as is also pointed out in the current documentation).

2) Technical details To achieve more consistent terminology, the following should be done:

Changing the keyword TRANSPARENCY to OPACITY

The old mapfile layer keyword “TRANSPARENCY” will be deprecated, but shall be supported in future versions of MapServer as an alias for OPACITY.

The new mapfile layer keyword OPACITY should replace TRANSPARENCY. There will be no changes in type or semantics, only a change of keyword name.

The internal structure member name in the layerObj will change from transparency to opacity.

3. Mapfile Implications

The parser will have to support both OPACITY and TRANSPARENCY (for backward compatibility). The type will not change.

At debug level 1 a warning will be issued that the TRANSPARENCY parameter is deprecated and OPACITY should be used instead.

4. MapScript Implications

Since the layerObj will no longer contain a transparency member this will break old scripts. The fix will be evident.

5. Documentation Implications

Documentation should be updated, introducing OPACITY as a new layer keyword with documentation similar to the current transparency. The layer keyword TRANSPARENCY should be documented as deprecated. All other documentation that references TRANSPARENCY will have to be updated (simple search-replace with a manual check of all occurrences of the word transparency?)

SCALE

1. Overview

SCALE and MAXSCALE/MINSCALE is a case where MapServer terminology is not in line with mainstream map terminology.

In proper usage, scale is a representative fraction. The scale 1:50000 tells us that one meter on the map corresponds to 50000 meters in the “terrain”. 1:1000 (0.001) is a larger scale than 1:50000 (0.00002). The current use of MAXSCALE and MINSCALE is therefore not consistent with proper terminology.

2. Technical details

To achieve more consistent terminology, the following could be done with limited consequences:

Change all occurrences of “SCALE” in keywords to “ScaleDenom”.

MinScale 10000 Maxscale 1000000

will become:

MinScaleDenom 10000 MaxScaleDenom 1000000

This will apply to the following occurrences of SCALE in mapserver keywords:

Map object:

SCALE -> ScaleDenom

Web object:

MAXSCALE/MINSCALE

Layer object:

MAXSCALE/MINSCALE LABELMAXSCALE/LABELMINSCALE SYMBOLSCALE

Class object:

MAXSCALE/MINSCALE

3. Mapfile Implications

The parser would have to accept the new keywords. The old keywords will be unique prefixes of the new keywords, and could be accepted by the parser (in a transition period or for eternity).

At debug level 1 a warning will be issued that the …SCALE parameter is deprecated and …SCALEDENOM should be used instead.

4) MapScript Implications For all scale variables, scale should be changed to scaledenom (for consistency reasons). The type (double) will not change. Like opacity above this could break old scripts.

5. Template Implications

The [scale] substitution should be deprecated (but still supported) and [scaledenom] added.

6. CGI Imaplications

The scale CGI parameter would continue to be supported (e.g. users often define a map extent using a center point and a scale value). Scaledenom would also be supported.

7. Documentation Implications

All occurrences of scale keywords in the documentation will have to be changed to reflect the new names. The old style keywords could be included, but should marked as deprecated.

PATTERN

1. Overview

Currently both the symbolObj and classObj contain STYLE parameters. The symbolObj style stores dash patterns used for line symbols. The name is derived from GD terminology. To avoid confusion with the classObj STYLE the symbolObj STYLE should be renamed to more concisely reflect it’s purpose.

2. Technical details

In the symbolObj structure definition the member style will be renamed pattern. All references to the style in the code will also be updated.

3. Mapfile/symbol file Implications

The parser would have to accept the new keywords. The old keywords will be unique prefixes of the new keywords, and could be accepted by the parser (in a transition period or for eternity).

At debug level 1 a warning will be issued that the STYLE parameter is deprecated and PATTERN should be used instead.

4. MapScript Implications

As above the symbolObj structure would be altered and so MapScript scripts that set a symbol style programmatically would break. They would need to reference the patter parameter instead.

5. Template Implications

None

6. CGI Implications

None

7. Documentation Implications

The symbolObj reference guides would need to updated to reflect the name change.