..
.. Copyright (c) 2011 by Intevation GmbH, Germany <info@intevation.de>
.. 
.. This file is part of MXD2map.
..
.. This program is free software under the LGPL (>=v2.1)
.. Read the file LICENCE.txt coming with the software for details
.. or visit http://www.gnu.org/licenses/ if it does not exist.
..
.. MXD2map has been developed on behalf of the
.. Bundesamt fuer Seeschifffahrt und Hydrographie (BSH) in Hamburg
.. by Intevation GmbH.
..
.. Authors:
.. Raimund Renkert <raimund.renkert@intevation.de>
.. Bjoern Schilberg <bjoern.schilberg@intevation.de>
.. Stephan Holl <stephan.holl@intevation.de>


.. index:: features, functionality, configuration, runtime-parameter, commandline

-------------
Functionality
-------------

The MXD2map converter works as a commandline tool to transform maps from the
proprietary ArcGIS file format "MXD" to a MapServer configuration file.

To transform an ArcGIS mxd file to a MapServer configuration file the mxd file
must have a valid and available data source and must not fit the
:ref:`restriction-label` described in the appropriate section.

.. image:: ../funktionsweise/funktionsweise-MXD2map.png
    :align: center
    :alt: MXD2map-Schema
    :width: 500px

.. _howtouse-label:

How to use
----------

The converter is started via the commandline running the command::

  $java -jar mxd2map.jar

The converter can be configured in two ways:

1. The converter.properties file (see converter.properties.sample)
2. via commandline arguments

The converter.properties.sample file::


  # Java properties file for the MXD Converter Tool.
  mxd = \\full\\path\\to\\mxd-file
  map = \\full\\path\\to\\map-file
  map-template = \\full\\path\\to\\mapfile-template

Make sure  you mask backslahes with an additional backslash.

Both take a parameter for the path to the mxd file, the outputfile and a mapfile
template for initial mapfile config. Commandline parameters have a higher
priority than the properties file.

The available parameters on the commandline are::

  -m or --mxd		The mxd file to convert.

  -a or --map		The path to the output file. Should end with ".map".

  -t or --template	The template to use for an initial mapfile
			configuration.

To have the full functionality for ArcGIS map conversion it is necessary to have
the ESRI fonts available. ArcGIS products install these fonts to the default
windows font folder ``c:\\windows\\fonts``. To make them available for the converter
there has to be a MapServer font set (see
http://mapserver.org/mapfile/fontset.html). 

The MXD2map converter comes with an
initial fontset containing all relevant ESRI fonts and the free font FreeSans.
The font set file named fonts.txt can be edited and further fonts can be added.
To use a font set, the file needs to be referenced in the MapServer template
otherwise the converter can not create character symbols and will show up errors
in the conversion process.

The converter uses a separate symbol file to provide symbol sets to the
template to have initial symbols available. If no symbol file is referenced a
new one is created by the converter if necessary. The resulting symbol set is
written to the same directory as the output mapfile named
[mapfile-name]-symbols.sym.


Features
--------

MXD2map is optimized to work best with MapServer 6.x. Therfore the new
MapServer features (symbolhandling, styling etc) are built in.

MXD2map currently supportes the following features:

 * Datasources:

   * ArcSDE vector database connections (requires MapServer built against ArcSDE, Client-dlls ``[sde.dll, sg.dll and pe.dll]`` needed)
   * ESRI-Shapefiles

 * Symbols:

   * Simple marker symbols
   * Character marker symbols
   * Arrow marker symbols
   * Picture marker symbols (also trancparency is supported if set in MXD)
   * Symbols based on TTF-characters of special cartographic fonts
   * Any combination of character marker symbols
   * Linesymbols with pattern and cartographic attributes
   * Polygons filled with solid color and outline
   * Polygons filled with a hatch and hatched outline


 * Layer types:

   * Featurelayer (vectors) as POINT, LINESTRING and POLYGON
   * Classifications with unique values
   * Classifications with class breaks
   * Group-members are concatinated to group.layername. This ensures having discrete layernames
   * ArcGIS-layergroups are represented as WMS Named layers, which are WMS-layers without a title (so not requestable through GetMap)
   * all definition-queries for filtering the data on Layer- and classification-level

 * Further map attributes:

   * Projections and units based on the EPSG-table (if set in MXD)
   * Min/max scale denominations at layer and label-level
   * Global Map extent
   * Layer extent and SRS
   * Simple labeling
   * Filter and expressions
   * ArcSDE Jointables
   * Mapfile-Templating for OGC-related stuff
   * Simple Labeling-syntax (a subset of ArcGISs VBScript-labels)

 * Other features

   * Umlauts are translated into its equivalents within LAYER-names,
     CLASS-names and also mapfile-names. Though it is good standard not to
     use them since they mostly cause problems when using them within
     OWS-related services.
   * Creation of distinct layer-names by concatinating group- and
     layernames to WMS-titles. This comes handy mostly in ArcGIS
     layergroups.