.. index::
   single: REFERENCE

.. _reference:

*****************************************************************************
 REFERENCE
*****************************************************************************

Three types of reference maps are supported. The most common would be one
showing the extent of a map in an interactive interface. It is also possible
to request reference maps as part of a query. Point queries will generate an
image with a marker (see below) placed at the query point. Region based
queries will depict the extent of the area of interest. Finally, feature based
queries will display the selection feature(s) used.

.. index::
   pair: REFERENCE; COLOR

COLOR [r] [g] [b] | [hexadecimal string]
    Color in which the reference box is drawn. Set any component to -1 for 
    no fill. Default is red.
    
    - `r`, `g` and `b` shall be integers [0..255].  To specify green,
      the following is used:

        .. code-block:: mapfile

           COLOR 0 255 0

    - `hexadecimal string` can be

      - RGB value: "#rrggbb".  To specify magenta, the following is
        used:

        .. code-block:: mapfile

           COLOR "#FF00FF"

      - RGBA value (adding translucence): "#rrggbbaa".  To specify a
        semi-translucent magenta, the following is used:

        .. code-block:: mapfile

           COLOR "#FF00FFCC"         

.. index::
   pair: REFERENCE; EXTENT

EXTENT [minx][miny][maxx][maxy]
    The spatial extent of the base reference image.

.. index::
   pair: REFERENCE; IMAGE

IMAGE [filename]
    Full filename of the base reference image. Must be a GIF image.

.. index::
   pair: REFERENCE; MARKER

MARKER [integer|string]
    Defines a symbol (from the symbol file) to use when the box becomes too 
    small (see MINBOXSIZE and MAXBOXSIZE below). Uses a crosshair by default.

.. index::
   pair: REFERENCE; MARKERSIZE

MARKERSIZE [integer]
    Defines the size of the symbol to use instead of a box (see MARKER above).

.. index::
   pair: REFERENCE; MINBOXSIZE

MINBOXSIZE [integer]
    If box is smaller than MINBOXSIZE (use box width or height) then use the 
    symbol defined by MARKER and MARKERSIZE.

.. index::
   pair: REFERENCE; MAXBOXSIZE

MAXBOXSIZE [integer]
    If box is greater than MAXBOXSIZE (use box width or height) then draw 
    nothing (Often the whole map gets covered when zoomed way out and it's 
    perfectly obvious where you are).

.. index::
   pair: REFERENCE; OUTLINECOLOR

OUTLINECOLOR [r] [g] [b] | [hexadecimal string]
    Color to use for outlining the reference box. Set any component to -1 
    for no outline.

    - `r`, `g` and `b` shall be integers [0..255].  To specify green,
      the following is used:

        .. code-block:: mapfile

           OUTLINECOLOR 0 255 0

    - `hexadecimal string` can be

      - RGB value: "#rrggbb".  To specify magenta, the following is
        used:

        .. code-block:: mapfile

           OUTLINECOLOR "#FF00FF"

      - RGBA value (adding translucence): "#rrggbbaa".  To specify a
        semi-translucent magenta, the following is used:

        .. code-block:: mapfile

           OUTLINECOLOR "#FF00FFCC"   

.. index::
   pair: REFERENCE; SIZE

SIZE [x][y]
    Size, in pixels, of the base reference image.

.. index::
   pair: REFERENCE; STATUS

STATUS [on|off]
    Is the reference map to be created? Default it off.
