[mapserver-commits] r8146 - trunk/docs/development/rfc
svn at osgeo.org
svn at osgeo.org
Sun Nov 30 15:57:35 EST 2008
Author: hobu
Date: 2008-11-30 15:57:35 -0500 (Sun, 30 Nov 2008)
New Revision: 8146
Modified:
trunk/docs/development/rfc/ms-rfc-25.txt
trunk/docs/development/rfc/ms-rfc-26.txt
Log:
styling, break at 80, formatting
Modified: trunk/docs/development/rfc/ms-rfc-25.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-25.txt 2008-11-30 20:52:18 UTC (rev 8145)
+++ trunk/docs/development/rfc/ms-rfc-25.txt 2008-11-30 20:57:35 UTC (rev 8146)
@@ -13,13 +13,34 @@
Overview
========
-At present MapServer uses different pixel and extent model than defined by OGC services such as WCS and WMS. MapServer uses the center of a pixel to represent its unique coordinate value. An extent is interpreted as the bounding box that runs from the center of the UL pixel in an image to the center of the LR pixel in an image. Why? Well, it goes back to companion software that existed along side MapServer to display satellite data stored in ERDAS that used the center to center extent model. The math is simple and there is a certain logic in having the extent actually represent pixel values - that is, if you render the extent as a polygon you get the exact edge of the image as one might expect.
+At present MapServer uses different pixel and extent model than defined by OGC
+services such as WCS and WMS. MapServer uses the center of a pixel to represent
+its unique coordinate value. An extent is interpreted as the bounding box that
+runs from the center of the UL pixel in an image to the center of the LR pixel
+in an image. Why? Well, it goes back to companion software that existed along
+side MapServer to display satellite data stored in ERDAS that used the center
+to center extent model. The math is simple and there is a certain logic in
+having the extent actually represent pixel values - that is, if you render the
+extent as a polygon you get the exact edge of the image as one might expect.
-On the other hand, OGC service specifications define an extent (BBOX) to refer to the dimensions of the outside edges of the image being requested. This appears to be a far more common means of expressing an area of interest.
+On the other hand, OGC service specifications define an extent (BBOX) to refer
+to the dimensions of the outside edges of the image being requested. This
+appears to be a far more common means of expressing an area of interest.
-I've not been able to ascertain where the coordinate of an individual pixel is located from various OGC specifications. MapServer '''could''' retain a center-based pixel model. That does add complexity to the map <=> image coordinate transformations since you have to offset things by one-half cellsize. Since that computation is done many times I would expect a performance hit. We could optimize things by computing and storing the one-half cellsize value once (as cellsize is now), but that complicates the C APIs and requires huge amounts of change. I propose moving to a upper-left-based pixel model to simplify these conversions.
+I've not been able to ascertain where the coordinate of an individual pixel
+is located from various OGC specifications. MapServer '''could''' retain a
+center-based pixel model. That does add complexity to the map <=> image
+coordinate transformations since you have to offset things by one-half
+cellsize. Since that computation is done many times I would expect a
+performance hit. We could optimize things by computing and storing the
+one-half cellsize value once (as cellsize is now), but that complicates the
+C APIs and requires huge amounts of change. I propose moving to a
+upper-left-based pixel model to simplify these conversions.
-Note: In looking at the code there were past efforts to go to the OGC extent in 4.8 and 4.10, but it was not universally applied. This RFC would ensure that the same extent and pixel model is in use throughout MapServer and that it is consistent with OGC.
+Note: In looking at the code there were past efforts to go to the OGC extent
+in 4.8 and 4.10, but it was not universally applied. This RFC would ensure
+that the same extent and pixel model is in use throughout MapServer and that
+it is consistent with OGC.
model diagram: http://maps.dnr.state.mn.us/mapserver_docs/rfc25_extent.pdf
@@ -60,7 +81,11 @@
- various raster layer handlers: Need Frank's comments here.
- mapscript ...zoom functions: I don't believe these will need any change.
-The affect of these changes on end-users should be minimal since it is unlikely they the are aware of differences in extent interpretation. The larger impact may be on 3rd party applications like dBox, Chameleon and QGIS that manage extents and call MapServer. Efforts must be made to make those folks aware of the change.
+The affect of these changes on end-users should be minimal since it is
+unlikely they the are aware of differences in extent interpretation. The
+larger impact may be on 3rd party applications like dBox, Chameleon and QGIS
+that manage extents and call MapServer. Efforts must be made to make those
+folks aware of the change.
Mapfile Implications
====================
@@ -75,16 +100,27 @@
Documentation Implications
==========================
-The models for a pixel and an extent need to documented in a couple of places: mapfile reference, the related OWS service how-to's and perhaps a new how-to pertaining to just this topic.
+The models for a pixel and an extent need to documented in a couple of
+places: mapfile reference, the related OWS service how-to's and perhaps a
+new how-to pertaining to just this topic.
Test Plan
=========
-Need to develop some tests to somehow validate the math. The WCS interface or output drivers using GDAL are excellent candidates since they produce georeferenced output. Some testing has already been done to verify the existence of the issue (first discovered via WCS) and the proposed fix.
+Need to develop some tests to somehow validate the math. The WCS interface
+or output drivers using GDAL are excellent candidates since they produce
+georeferenced output. Some testing has already been done to verify the
+existence of the issue (first discovered via WCS) and the proposed fix.
-Mini-images (e.g. 7x7) can be used to verify rendering makes sense. For example, if you draw the extent as a polygon you would expect to see lines for the left and top edges, but not for the bottom and right. That is because the maxx,miny extent values won't represent a pixel in the output (rather the next tile to the right and/or below).
+Mini-images (e.g. 7x7) can be used to verify rendering makes sense.
+For example, if you draw the extent as a polygon you would expect to see
+lines for the left and top edges, but not for the bottom and right. That is
+because the maxx,miny extent values won't represent a pixel in the output
+(rather the next tile to the right and/or below).
Staffing / Timeline
===================
-Changes to maputil.h, map.h, mapwcs.c and mapwms.c would be done by Steve Lime. Changes to other portions of MapServer would be coordinated with the various component owners. This RFC would be completed for the 5.0 release.
\ No newline at end of file
+Changes to maputil.h, map.h, mapwcs.c and mapwms.c would be done by Steve
+Lime. Changes to other portions of MapServer would be coordinated with the
+various component owners. This RFC would be completed for the 5.0 release.
Modified: trunk/docs/development/rfc/ms-rfc-26.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-26.txt 2008-11-30 20:52:18 UTC (rev 8145)
+++ trunk/docs/development/rfc/ms-rfc-26.txt 2008-11-30 20:57:35 UTC (rev 8146)
@@ -11,39 +11,50 @@
: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).
+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.
+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.
+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).
+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 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 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.
+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.
+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 depricated and OPACITY should be used instead.
+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.
+Since the layerObj will no longer contain a transparency member this will
+break old scripts. The fix will be evident.
5) Documentation Implications
@@ -59,13 +70,19 @@
1) Overview
-SCALE and MAXSCALE/MINSCALE is a case where Mapserver terminology is not in line with mainstream map terminology.
+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.
+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:
+To achieve more consistent terminology, the following could be done with
+limited consequences:
Change all occurrences of "SCALE" in keywords to "ScaleDenom".
@@ -96,45 +113,64 @@
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).
+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 depricated and ...SCALEDENOM should be used instead.
+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.
+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.
+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.
+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 occurences 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.
+All occurences 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.
+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.
+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).
+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 depricated and PATTERN should be used instead.
+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 programatically would break. They would need to reference the patter parameter instead.
+As above the symbolObj structure would be altered and so MapScript scripts
+that set a symbol style programatically would break. They would need to
+reference the patter parameter instead.
5) Template Implications
@@ -146,4 +182,5 @@
7) Documentation Implications
-The symbolObj reference guides would need to updated to reflect the name change.
+The symbolObj reference guides would need to updated to reflect the name
+change.
More information about the mapserver-commits
mailing list