Mapserver 5 - Terminology clean-up

Mon Oct 30 19:36:46 EST 2006

What do other projects use for scale? I believe I've seen references to MaxScaleDenominator (etc...) 
for OWS context. I could live with that but also think that this can be handled by documentation (this
doesn't seem to be a huge source for confusion):

"In MapServer scale is represented using the denominator of the representative fraction...."

Steve

>>> Havard Tveite <havard.tveite at umb.no> 10/27/2006 4:09:40 AM >>>
Steve Lime wrote:
> I guess I'm not clear on the need to swich the MINSCALE and MAXSCALE meanings if you
> allow two ways of specifying a scale. You're not going to be perfect in both cases and
> there will still be confusion- new keywords will only add to it. 

The problem is that in the current version of Mapserver, MINSCALE
and MAXSCALE are switched compared to common usage of the word
scale in science.
1:100 is a larger scale than 1:5000, even if the number to the
right of the colon is smaller for 1:100 than 1:5000.

> Since we used the denominator only in the past the MIN/MAX work as is. Swapping those will mean
> a huge number of code changes, although a scale checking macro should probably be introduced
> regardless.

That was the reason why I suggested to add _DENOMIATOR to the
MIN/MAX.  That way, there would be no need to change any code.

If scale is still represented internally as only the denominator
(as I guess is current practice), there would be no changes,
except for changing the map file keywords.

> I'm really not sure which is the best solution but I only see 4 viable options, although I'm not
> partial to keyword additions.
> 
> 1) Don't do anything and handle this through documentation (e.g. scales are expressed as the
> denominator of the representative fraction).

This solution remedies some of the terminology problems, but
does not remove one of the main causes of confusion (incorrect
usage of min and max in the mapfile).

> 2) Leave MINSCALE/MAXSCALE... meaning alone and just provide an alternative method
> of specifying the scale. This leads to the MIN vs. MAX confusion in some cases.

This helps a bit, but not enough.

> 3) Flip-flop meaning of MINSCALE/MAXSCALE and allow two ways to set scale. All heck breaks
> loose with this change IMHO.

I agree that this is not an option, as it will break backward
compatibility.

> 4) Introduce new keywords and depricate the old, but leave the meaning the same (see Havard's
> original message), but only use the denominator to set scale...

I think this is OK (adding _DENOMINATOR, _DENOM or a something
better to *SCALE).  This will not have to break backward
compatibility, and will result in terminology that is not incorrect.

>>From a MapScript perspective it is *much* easier to treat scale as it is now, and it's much easier for
> the user (once they've read the documentation) to write 10000 instead of 0.0001, plus setting
> 1:10000 means having to write typemaps which are hairy (and need maintenance).

I never meant "0.00001" to be used.  The scale denominator will of
course be used (with or without a leading "1:").  Alternatives are:
SCALE 1 : xxxxxx
SCALE_DENOM xxxxxx

> I'm starting to think that option 1) is the best one and could live with 4) pending a TSC vote.

Then I think the RFC should go for option 4.
The question is then how the SCALE keywords should be changed.
Is *SCALE_DENOM acceptable, or are there better alternatives?

How to proceed?

Håvard

> 
> Steve
> 
>>>> Havard Tveite <havard.tveite at umb.no> 10/26/2006 7:48:35 AM >>>
> Frank Warmerdam wrote:
>> I was thinking of you and Steve working on the RFC.  There is no reason
>> you can't take the lead on writing the RFC though, perhaps with Steve
>> filling in some technical details.
>>
>> I don't think the RFC needs to be very long, but it should include the
>> consensus plan so far, and sections addressing testing, documentation
>> changes, backwards compatibility, when it will be complete, etc.
>>
>> You can see example RFCs at:
>>
>>   http://mapserver.gis.umn.edu/development/rfc/ 
>>
>> If you don't have permission to create a new RFC you might want to talk
>> to Howard about getting permission.
>>
>> I must admit getting you to work on the RFC is a blatant attempt on my
>> part to transfer the work off the developers, and get more people involved
>> in the process of preparing and refining technical proposals.
> 
> Dear Frank and Steve,
> 
> I have started on an RFC for the terminology clean-up.
> I have included the first draft below.  What do you think?
> 
> We seem to agree on TRANSPARENCY->OPACITY and the SCALE
> "type".
> Then there is the issue of erroneous MAXSCALE / MINSCALE
> terminology that we have not really discussed.  In order
> to fix the MAXSCALE-MINSCALE issue while not breaking
> backward compatibility, I think new keywords will have to
> be introduced in the layer and map objects of the mapfile.
> I suggest MAXIMUMSCALE/MINIMUMSCALE (and
> LABELMAXIMUMSCALE/LABELMINIMUMSCALE) below.
> 
> Regards,
> 
> Håvard
> 
> *************************************************************
> MS RFC XX: Mapserver terminology clean-up
> 
> Mapserver usage is growing, and Mapserver terminology should be
> as sound and consistent as possible.
> 
> 
> 1) Overview
> Mapserver terminology is mostly good and consistent, with a
> few exceptions.  TRANSPARENCY and SCALE are two cases
> where Mapserver terminology is not in line with mainstream
> terminology.
> 
> TRANSPARENCY is used in the Mapserver mapfile layer object
> for what is in fact opacity (as pointed out in the current
> documentation).
> 
> The  current type of the "*SCALE" (SCALE, MINSCALE, MAXSCALE,
> LABELMINSCALE, LABELMAXSCALE, SYMBOLSCALE) keywords used
> in the Mapserver mapfile map, web and layer objects is a
> single double.
> Scale shall be expressed as 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 not consistent
> with proper terminology.
> 
> The purpose of this proposal is to make Mapserver even easier
> to use, removing confusion that can arise in cases of
> inconsistent terminology.
> 
> 
> 2) Technical details
> To achieve more consistent terminology, the following should be
> done:
> 
> 2.1 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.
> 
> 2.2 Changing the type for the "*SCALE" keywords
> The type of the "*SCALE" keywords (found in the map, web and layer
> objects in the mapfile) will have to be changed from double to
> the integer "1", followed by zero or more spaces, followed by the
> character ":", followed by zero or more spaces, followed by a
> double.  The final double is the same as the double that is
> currently used for "*SCALE".
> 
> Pseudo-code regular expression:
> 1\s*:\s*double
> 
> Layer: LABELMAXSCALE*, LABELMINSCALE*, MAXSCALE*, MINSCALE*, SYMBOLSCALE,
> Map: SCALE
> Web: MAXSCALE*, MINSCALE*
> * The names of these keywords may have to changed, see below.
> 
> 2.3 Changing the sematics of the "*MAXSCALE" and "*MINSCALE" keywords
> Currently, MAXSCALE and MINSCALE are interchanged compared to proper
> terminology.
> Currently, if one wants a map to be displayed only in the scale range
> 1:10000 to 1:1000000, the following entries must be present in the
> MAP object of the mapfile
> MINSCALE 10000
> MAXSCALE 1000000
> The correct way of specifying this (using the new scale type and
> assuming the same keywords could be used) is:
> MINSCALE 1:1000000
> MAXSCALE 1:10000
> 
> To achieve backward compatibility, it will be necessary to introduce
> new keywords that can live in parallel with the existing (deprecated)
> keywords.
> I suggest to use "MINIMUMSCALE" and "MAXIMUMSCALE":
> MINIMUMSCALE 1:10000
> MAXIMUMSCALE 1:1000000
> 
> The same applies to MAXSCALE/MINSCALE and LABELMAXSCALE/LABELMINSCALE
> in the layer object.
> 
> 
> 3) Mapfile Implications
> 3.1 TRANSPARENCY -> OPACITY
> The parser will have to support both OPACITY and TRANSPARENCY
> (for backward compatibility).  The type will not change.
> 
> 3.2 SCALE type
> Since the type of the keyword is changed, the parser will have
> to be updated accordingly.  Support for the old way of specifying
> scale should be continued (for backward compatibility), so the
> parser will have to accomodate two ways of specifying scale.
> Mapfiles using the new style for giving scale (the number 1, followed
> by a colon (":"), followed by a number can not be used with old
> versions of Mapserver.
> 
> 3.3 "*MAXSCALE" / "*MINSCALE" semantics
> The semantics of the keywords are changed.  MAXIMUMSCALE will now
> have to be saved as the value currently specified with MINSCALE.
> 
> 
> 4) MapScript Implications
> 4.1 TRANSPARENCY -> OPACITY
> TRANSPARENCY is deprecated, so OPACITY will have to be the default
> mapscript variable.  The transparency variable should, however, be
> offered as an alias for opacity to ensure backward compatibility.
> 
> 4.2 SCALE type
> Scale can still be available as a variable of type double in
> mapscript.
> 
> 4.3 Changing the sematics of the "*MAXSCALE" and "*MINSCALE" keywords
> Everything is turned upside down, so backwards compatibility can only
> be achieved by indtroducing new keywords.
> 
> 5) Documentation Implications
> 5.1 TRANSPARENCY -> OPACITY
> 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 occurences
> of the word transparency)
> 
> 5.2 SCALE type
> The mapfile documentation will have to be updated with the new type
> for scale (map, web, layer).
> All other documentation that references SCALE will have to be updated
> with the new type. For mapscript documentation, some care will have
> to be taken to point out that the type of the mapscript variable is
> different from the "type" used in the mapfile.
> 
> 5.3 "*MAXSCALE" / "*MINSCALE" semantics
> Map file documentation should be updated, noting that MAXSCALE/MINSCALE
> and LABELMAXSCALE/LABELMINSCALE is  deprecated, and explainging the
> new MAXIMUMSCALE/MINIMUMSCALE and LABELMAXIMUMSCALE/LABELMINIMUMSCALE
> keywords.
> *************************************************************
> 

-- 
Håvard Tveite
Department of Mathematical Sciences and Technology, UMB
Drøbakveien 14, POBox 5003, N-1432 Ås, NORWAY
Phone: +47 64965483 Fax: +47 64965401 http://www.umb.no/imt