.. _rfc14:

===============================================================
  MS RFC 14: Relative Coordinates for INLINE features
===============================================================

:Date: 2006/04/10 
:Author: Steve Lime
:Contact: steve.lime at DNR.STATE.MN.US
:Status: Complete
:Version: MapServer 4.10

Description: Current it is possible to have features with pixel coordinates 
and to draw them by setting TRANSFORM FALSE in a layer definition. However 
the coordinates are relative to the upper lefthand corner of the image (0,0) 
which makes it impossible to anchor things like copyright statements to the 
other corners of the images if the image size can change (e.g. via WMS).

The proposed solution extends the behavior of the LAYER TRANSFORM parameter 
that would tell MapServer to use an alternative origin that the UL corner 
of the image. 

C Structural Changes
~~~~~~~~~~~~~~~~~~~~

None. Existing structure, members and constants would be utilized. The 
position enumeration should probably be given a different starting value to 
avoid conflict with variables like MS_TRUE and MS_FALSE.

Mapfile Changes
~~~~~~~~~~~~~~~~~

This functionality is really geared towards inline features. However, I'd 
like to keep the door open to support features from any datasource. The 
proposed change would extend the use of the LAYER TRANSFORM parameter. 
Currently it takes values TRUE or FALSE (default is TRUE). I propose 
extending to also take any of the standard explicit position values. So for 
the typical inline feature use you'd see a layer like:

::

  LAYER
    NAME 'copyright'
    TYPE POINT
    TRANSFORM LL
    FEATURE
      POINTS 10 -10 END
      TEXT 'Copyright &copy; MNDNR'
    END
    CLASS
      ...
    END
  END

Within MapScript the syntax would be similarly simple:

::

  $layer->{transform} = $mapscript::MS_LL;
  ... draw as normal ...

Files affected
~~~~~~~~~~~~~~~~~

- map.h => change starting value of the positions enumeration
- mapfile.c => add detection of the additional TRANSFORM values 
- mapprimitive.c => add a new offset shape function that would take the 
  map hight, width and shapeObj as input.
- mapdraw.c => update shape drawing code to use the new function 
  (basically an else condition for all the if (layer->transform) checks). 

Testing
~~~~~~~

- Python suite: none needed
- MsAutoTest suite: a mapfile testing all 9 positions would be developed

Backwards compatibility issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

N/A, new functionality. A value for TRANSFORM of FALSE implies UL... It 
should be noted that by changing the starting value for the position 
enumeration there is the possibility of breaking scripts that refer 
position by integer (poor programming practice). I would expect this to be a 
remote possibility and worth the risk. 

Bug ID
~~~~~~~~

`1547`_

Voting history
~~~~~~~~~~~~~~~~~

Passed

.. _1547: https://github.com/mapserver/mapserver/issues/1547
