\section{Making MapServer Map Files}\label{sec:mapserver_export}

QGIS can be used to create map files for MapServer. You use QGIS to
``compose'' your map by adding and arranging layers, symbolizing them, and
customizing the colors.

In order to use the MapServer exporter, you must have Python on your
system and QGIS must have been compiled with support for it.

\subsection{Creating the Project File}

To create a MapServer map file:

\begin{enumerate}
\item Add your layers to QGIS
\item Symbolize your layers, setting the renderer and colors
\item Arrange the layers in the order you want them to appear in MapServer
\item Save your work to a QGIS project file
\end{enumerate} 

This gets us to the point where we are ready to create the map file.

\begin{Tip}\caption{\textsc{MapServer Export Requires a QGIS Project File}}
\qgistip{This has been a source of confusion for a number of people. The
MapServer export tool operates on a saved QGIS project file,
\textbf{not} the current contents of the map canvas and legend. When 
using the tool, you need to specify a QGIS project file as input.
}
\end{Tip} 

\subsection{Creating the Map File}

The exporter tool (\textsl{msexport}) is installed in your QGIS binary directory and can be
used independently of QGIS. 

From QGIS you can start the exporter by choosing \textsl{Export to MapServer
  Map...} from the \textsl{File} menu.

  Here is a summary of the input fields:
  \begin{description}

    \item [Map file] \mbox{}\\
Enter the name for the map file to be created. You can use the button at the right to browse for the directory where you want the map file created. 

\item [Qgis project file] \mbox{}\\
Enter the full path to the QGIS project file (.qgs) you want to export. You can use the button at the right to browse for the QGIS project file.
\item [Map Name] \mbox{}\\
A name for the map. This name is prefixed to all images generated by the mapserver.
\item [Map Width] \mbox{}\\
Width of the output image in pixels.

\item [Map Height] \mbox{}\\
Height of the output image in pixels.
\item [Map Units] \mbox{}\\
Units of measure used for output
\item [Image type] \mbox{}\\
Format for the output image generated by MapServer
\item [Web Template] \mbox{}\\
Full path to the MapServer template file to be used with the map file
\item [Web Header] \mbox{}\\
Full path to the MapServer header file to be used with the map file
\item [Web Footer] \mbox{}\\
Full path to the MapServer footer file to be used with the map file
\end{description}

Only the Map file and QGIS project file inputs are required to create a
map file, however you may end up with a non-functional map file, depending
on your intended use. Although QGIS is good at creating a map file from
your project file, it may require some tweaking to get the results you
want - but it's still way better than writing a map file from scratch.  

\textbf{Creating a Map File}

Let's create a map file using the shape files \textsl{alaska}, \textsl{lakes} 
and \textsl{rivers} layers from the qgis\_sample\_data:

\begin{enumerate}
  \item Load the \textsl{alaska}, \textsl{rivers} and \textsl{lakes} 
  layers into QGIS
  \item Change the colors and symbolize the data as you like
  \item Save the project using \textsl{Save Project} from the
    \textsl{File} menu
  \item Open the exporter by clicking on \textsl{Export to MapServer
    Map...} in the \textsl{File} menu
  \item Enter a name for your new map file
  \item Browse and find the project file you just saved
  \item Enter a name for the map
  \item Enter 600 for the width and 400 for the height
  \item Our layers are in decimal degrees so we don't need to change the
    units
  \item Choose ``png'' for the image type
  \item Click \textsl{OK} to generate the map file
\end{enumerate}


\begin{figure}[ht]
\begin{center}
  \caption{Export to MapServer map module in QGIS}\label{fig:mapserver_export}\smallskip
  \includegraphics[clip=true, width=0.8\textwidth]{mapserver_export}
\end{center}
\end{figure}

You'll notice there is no feedback on the success of your efforts. This
is an enhancement scheduled for the next version. 

You can view the map file in an editor or using \textsl{less}. If you
take a look, you'll notice that the export tool adds the metadata needed
to enable our map file for WMS. 

\subsection{Testing the Map File}

Let's test our work by using the \textsl{shp2img} command to create an image
from the map file. The  \textsl{shp2img} utility is part of MapServer,
but is also distributed with FWTools. To create an image from our map:

\begin{itemize}
\item Open a terminal window
\item If you didn't save your map file in your home directory, change to
  the directory where you saved it
\item Run shp2img 
\item View the created image 
\end{itemize}
 
Assuming our map file was named \textsl{mapserver\_test.map}, the
shp2img command is:

\begin{verbatim}
shp2img -m mapserver_test.map -o mapserver_test.png
\end{verbatim}

This creates a PNG for us to view, containing all the layers that were on
when we saved the QGIS project. In addition, the extent of the PNG will be the same as
when we saved the project.

If you plan to use the map file to serve WMS requests, you probably don't
have to tweak anything. If you plan to use it with a mapping template or a
custom interface, you may have a bit of manual work to do. To see how easy
it is to go from QGIS to serving maps on the web, take a look at
Christopher Schmidt's 5 minute flash video.
\footnote{\url{http://openlayers.org/presentations/mappingyourdata/}}
