.. index::
   single: SCALEBAR

.. _scalebar:

*****************************************************************************
 SCALEBAR
*****************************************************************************

Scalebars currently do not make use of TrueType fonts. The size of the 
scalebar image is NOT known prior to rendering, so be careful not to 
hard-code width and height in the <IMG> tag in the template file. Future 
versions will make the image size available.

.. index::
   pair: SCALEBAR; ALIGN

ALIGN [left|center|right]
    Defines how the scalebar is aligned within the scalebar image. Default 
    is center. Available in versions 5.2 and higher.
    
    .. versionadded:: 5.2

.. index::
   pair: SCALEBAR; BACKGROUNDCOLOR

BACKGROUNDCOLOR [r] [g] [b] | [hexadecimal string]
    Color to use for scalebar background, not the image background.
    
    - `r`, `g` and `b` shall be integers [0..255].  To specify green,
      the following is used:

        .. code-block:: mapfile

           BACKGROUNDCOLOR 0 255 0

    - `hexadecimal string` can be

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

        .. code-block:: mapfile

           BACKGROUNDCOLOR "#FF00FF"

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

        .. code-block:: mapfile

           BACKGROUNDCOLOR "#FF00FFCC"        

.. index::
   pair: SCALEBAR; COLOR

COLOR [r] [g] [b] | [hexadecimal string]
    Color to use for drawing all features if attribute tables are not used.
    
    - `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: SCALEBAR; IMAGECOLOR

IMAGECOLOR [r] [g] [b] | [hexadecimal string]
    Color to initialize the scalebar with (i.e. background).
    
    - `r`, `g` and `b` shall be integers [0..255].  To specify green,
      the following is used:

        .. code-block:: mapfile

           IMAGECOLOR 0 255 0

    - `hexadecimal string` can be

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

        .. code-block:: mapfile

           IMAGECOLOR "#FF00FF"

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

        .. code-block:: mapfile

           IMAGECOLOR "#FF00FFCC"     

INTERLACE [true|false]
    Should output images be interlaced? Default is [on]. This keyword is 
    now deprecated in favour of using the FORMATOPTION "INTERLACE=ON" line 
    in the :ref:`OUTPUTFORMAT` declaration.
    
    .. deprecated:: 4.6

.. index::
   pair: SCALEBAR; INTERVALS

INTERVALS [integer]
    Number of intervals to break the scalebar into. Default is 4.

.. index::
    pair: SCALEBAR; LABEL

:ref:`LABEL`
    Signals the start of a :ref:`LABEL` object.

.. index::
   pair: SCALEBAR; OFFSET

OFFSET [x] [y]
    'OFFSET' moves the scalebar closer to the center of the map.
    Examples:

    - If `POSITION` is "LL" then "OFFSET 5 2" will shift the scalebar 2
      pixels up and 5 pixels to the right.
    - If `POSITION` is "UR" then "OFFSET 5 2" will shift the scalebar 2
      pixels down and 5 pixels to the left.

    .. versionadded:: 7.2

.. index::
   pair: SCALEBAR; OUTLINECOLOR

OUTLINECOLOR [r] [g] [b] | [hexadecimal string]
    Color to use for outlining individual intervals. Set any component 
    to -1 for no outline which is the default.
    
    - `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: SCALEBAR; POSITION

POSITION [ul|uc|ur|ll|lc|lr]
    Where to place an embedded scalebar in the image. Default is lr.

.. index::
   pair: SCALEBAR; POSTLABELCACHE

POSTLABELCACHE [true|false]
    For use with embedded scalebars only. Tells the MapServer to embed the 
    scalebar after all labels in the cache have been drawn. Default is false.

.. index::
   pair: SCALEBAR; SIZE

SIZE [x][y]
    Size in pixels of the scalebar. Labeling is not taken into account.

.. index::
   pair: SCALEBAR; STATUS

STATUS [on|off|embed]
    Is the scalebar image to be created, and if so should it be embedded into 
    the image? Default is off. (Please note that embedding scalebars require 
    that you define a markerset. In essence the scalebar becomes a custom 
    marker that is handled just like any other annotation.) 

.. index::
   pair: SCALEBAR; STYLE

STYLE [integer]
    Chooses the scalebar style. Valid styles are 0 and 1.

TRANSPARENT [on|off]
    Should the background color for the scalebar be transparent. This flag is 
    now deprecated in favor of declaring transparency within :ref:`OUTPUTFORMAT`
    declarations. Default is off.
    
    .. deprecated:: 4.6

.. index::
   pair: SCALEBAR; UNITS

.. index::
   triple: SCALEBAR; UNITS; feet

.. index::
   triple: SCALEBAR; UNITS; inches

.. index::
   triple: SCALEBAR; UNITS; kilometers

.. index::
   triple: SCALEBAR; UNITS; meters

.. index::
   triple: SCALEBAR; UNITS; miles

.. index::
   triple: SCALEBAR; UNITS; nauticalmiles

UNITS [feet|inches|kilometers|meters|miles|nauticalmiles]
    Output scalebar units, default is miles. Used in conjunction with the 
    map's units to develop the actual graphic. Note that decimal degrees 
    are not valid scalebar units. `Nauticalmiles` was added in MapServer 5.6.
