= !MapGuide RFC 108 - Support Watermark =

This page contains a change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date|| July 30,2010 ||
||Last Modified|| Buddy Hu, July 30,2010 ||
||Author|| Buddy Hu||
||RFC Status|| frozen for vote||
||Implementation Status||(pending)||
||Proposed Milestone|| 2.3 ||
||Assigned PSC guide(s)||Bruce Dechant||
||'''Voting History'''||Aug 17, 2010||
||+1|| Tom||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

This RFC updates !MapGuide to support Watermarks.

== Motivation ==

Provide a standard way to add watermarks to the Map definition.

== Proposed Solution ==

1.	Create a new resource type for watermark, which defines content (in the format of an inline symbol definition), appearance (rotation / transparency) and position information of watermark. The schema of watermark definition is attached below.
	Referencing another symbol definition resource as content is not supported. There are three main reasons for this: 1) Usually, content of watermark is usually very simple (maybe just text / image). 2) The biggest reason of referencing symbol definition as a outer resource is for reusing. However, the concept of watermark already supports reuse. 3) Supports both inline and referencing outer resource is a complex idea and bring confusion to the end user (like "Which part of watermark is defined in the referenced symbol definition and which is defined in watermark definition itself?"). Using inline symbol definition will treat the watermark definition as a whole concept to the end user.

2.	User can add a watermark to !MapDefinition or !LayerDefinition by referencing corresponding watermark resource(s) in it. However, we do NOT support inline watermark in !MapDefinition and !LayerDefinition.
	The inline-and/or-reference problem also shows here. Not supporting both mode is to reduce the complexity of watermark concept. As we need to support watermark as a separate resource so that user can reuse it very easily, inline watermark is not supported.

3.	When !MapDefinition or !LayerDefinition references a watermark resource, it can choose to override its appearance and position information to bring flexibility to the user. The override attributes defining in !MapDefinition or !LayerDefinition has a higher priority than that in watermark when rendering.
	Sometimes users may want to move watermark a little (or change opacity) when using it in map / layer but don't want to change watermark in other maps referencing it. This often happens when user have two watermarks on the same map and there are some overlapping between these two watermarks. At that time, user can use this "override" mechanism to only change watermark a little in this map / layer.

4.	When being rendered, the watermark group of an !MgMap is actually the collection of the watermarks referenced in its !MapDefinition and the watermarks referenced in the !LayerDefinition in it, no matter if the MgMap is used in AJAX / Fusion viewer or in WMS service. Client(Maestro or other ones) should be responsible for copying / moving watermark references if needed (for example, when "Publishing WMS"), while server / web extension will not do any related work automatically.

5.	When using watermark in !LayerDefinition, user can decide in what situation the watermark is visible during rendering by defining “Usage” properties. For example, a watermark of a WMS layer is only visible when the value of its “Usage” properties is “WMS” or “ALL”. (There is no such problem when using watermark in !MapDefinition, because it will never be used in WMS.)
	Currently, the value of "Usage" can be "WMS" (WMS only), "Viewer" (AJAX /Fusion Viewer only) and "ALL".

6. About the position of watermark: there are two types of position in watermark: XY position and tile position. Tile position means the watermark will repeat itself in the map image (it has nothing to do with tile service).
		I)  The offset for tile position is the offset of watermark within tile (repeat unit), not map image.[[BR]]
		II) The alignment base of offset is different depending on the alignment way. For horizontal alignment: [[BR]]
			i) If the alignment is left, then the offset means the distance between left edge of watermark and that of map image / tile. [[BR]]
			ii) If the alignment is center, then the offset means the distance between center of X-axis of watermark and that of map image / tile. [[BR]]
			iii) If the alignment is right, then the offset means the distance between right edge of watermark and that of map image / tile.[[BR]]
		      For vertical alignment: [[BR]]
			i) If the alignment is top, then the offset means the distance between top edge of watermark and that of map image / tile. [[BR]]
			ii) If the alignment is center, then the offset means the distance between center of Y-axis of watermark and that of map image / tile. [[BR]]
			iii) If the alignment is bottom, then the offset means the distance between bottom edge of watermark and that of map image / tile.[[BR]]

	    Here are several examples:
		a)  XY position: X-Offset: 10 pixels from right, Y-Offset: 20 pixels from bottom. Watermark is a 40 * 30 pixel image. Map image size 400*300 pixels. Then the position of watermark is:[[BR]]
			The left edge of watermark is 400 - 10 - 40 = 350 pixels (!ImageWidth - XOffset - !WatermarkWidth) from left edge of map image.[[BR]]
			The top edge of watermark is 300 - 20 - 30 = 250 pixels (!ImageHeight - YOffset - !WatermarkHeight) from top edge of map image.[[BR]]
		b) Tile position: X-Offset: 10 pixels from right, Y-Offset: 20 pixels from bottom. Tile width: 210 pixels, tile height: 170px. Watermark is a 40 * 30 pixel image. Map image size 400*300 pixels. There will be four watermarks in map:[[BR]]
			i) Left: 210 - 10 - 40 = 160, Top: 170 - 20 - 30 = 120[[BR]]
			ii) Left: 2*210 - 10 - 40 = 370, Top: 170 - 20 - 30 = 120 (part of watermark is not visible for out of map image bound). [[BR]]
			iii) Left: 2*210 - 10 - 40 = 370, Top: 170*2 - 20 - 30 = 290 (part of watermark is visible for out of map image bound). [[BR]]
			iv) Left: 210 - 10 - 40 = 160, Top: 170*2 - 20 - 30 = 290 (part of watermark is visible for out of map image bound).[[BR]]
	The unit of watermark position is the unit of "paper length", not the "actual length in map". So it will not align with the existing unit list in layer definition.
== Implications ==

Maestro will need to be updated to add watermark support.  There are changes to the !MapDefinition, !LayerDefinition, and there is a new !WatermarkDefinition resource.

== Test Plan ==

!Build/Run on !Windows/Linux 

== Funding / Resources ==

Supplied by Autodesk