MapServer banner Home | Products | Issue Tracker | FAQ | Download
en it es zh_cn de el fr id sq tr

Flash Output

Author:Jeff McKenna
Contact:jmckenna at gatewaygeomatics.com
Author:Yewondwossen Assefa
Contact:assefa at dmsolutions.ca
Revision:$Revision$
Date:$Date$
Last Updated:2008/07/15

Introduction

Since MapServer 4.0, MapServer can output Flash files, in SWF format (or “Shockwave Flash Format”). The following document outlines how to enable Flash output in MapServer.

Note

SWF is no longer supported in version 6.0.

Installing MapServer with Flash Support

To check that your mapserv executable includes Flash support, use the “-v” command-line switch and look for “OUTPUT=SWF”.

$ ./mapserv -v
MapServer version 5.2.0-rc1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=AGG
SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT
SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER
SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS
SUPPORTS=GEOS SUPPORTS=RGBA_PNG INPUT=JPEG INPUT=POSTGIS
INPUT=ORACLESPATIAL INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE

Using Pre-compiled Binaries

Windows users can use MS4W, which supports SWF output.

Compiling MapServer with Flash Support

The library chosen to output SWF files is the Ming library. Ming is a C library for generating SWF (“Flash”) format movies, and it contains a set of wrappers for using the library from C++ and popular scripting languages like PHP, Python, and Ruby.

Building on Windows

  • download the Ming library (the version currently supported is 0.2a)

  • as of Ming 0.3 there was no makefile for Windows available in the distribution yet, but you can download a MS VC++ makefile (makefile.vc) from here (contains makefile and also libming.lib)

  • copy makefile.vc under the src directory (ming-0.2/src)

  • execute:

    nmake /f makefile.vc
  • at this point you should have a libming.lib that will be linked with MapServer

  • edit the nmake.opt in your MapServer directory and uncomment the MING=-DUSE_MING_FLASH flag, and point MING_DIR to your Ming directory.

  • build MapServer as usual

Building on Unix

Use the “–with-ming” configure flag to enable MING support on Unix. “–with-ming=dir” will try to find the include files and library in the indicated directory.

Note: compiling MapServer 4.4.2 with flash support (mingbeta version 0.3) requires
the -DMING_VERSION_03 option otherwise the make fails. This option should be included
in the configure.in after -DUSE_MING_FLASH as below:

   MING ENABLED= "-DUSE_MING_FLASH -DMING_VERSION_03"

How to Output SWF Files from MapServer

SWF output is specified by using the OUTPUTFORMAT object. There are 2 possible output types:

  1. A single movie containing the raster output for all the layers. To enable this, declare the following in the map file:

    OUTPUTFORMAT
      NAME swf
      MIMETYPE "application/x-shockwave-flash"
      DRIVER swf
      IMAGEMODE PC256
      FORMATOPTION "OUTPUT_MOVIE=SINGLE"
    END
  2. A movie for every layer (vector movies for vector layers and raster movies for raster layers). To enable this, declare the following in the map file:

    OUTPUTFORMAT
      NAME swf
      MIMETYPE "application/x-shockwave-flash"
      DRIVER swf
      IMAGEMODE PC256
      FORMATOPTION "OUTPUT_MOVIE=MULTIPLE"
    END

Other OutputFormat Options

  • FORMATOPTION “FULL_RESOLUTION=FALSE”

    The FULL_RESOLUTION applies only for vector layers. If set to FALSE, filtering will be applied to the vector elements. It results in a smaller SWF file. The default value is TRUE.

  • FORMATOPTION “LOAD_AUTOMATICALLY=OFF”

    Setting this option to OFF will not load the SWF files for each layer. The default value is ON.

Composition of the Resulting SWF Files

Several SWF Files will be produced from a single map file: there will be one SWF file for each layer defined in the map file and one ‘main’ SWF file containing critical information on the map file and the layers produced.

  • The ‘main’ SWF File will contain Action Script (AS) code that gives critical information on the map file and the SWF layers produced. Basically there will be an object called mapObj containing the height, width, extent, scale, number of layers, etc. Here is an example (in AS) of the contents of this main movie:

    mapObj = new Object ();
    mapObj.name = "DEMO_SWF";
    mapObj.width = 400;
    mapObj.height = 300;
    mapObj.extent = "-2594561.353333,3467361.353333,3467361.353333,3840000.000000"; ;
    mapObj.numlayers = 4;
    mapObj.layers = new Array ();
    function LayerObj (name, type, fullname, relativename) {
    this.name = name;
    this.type = type;
    this.fullname = fullname;
    this.relativename = relativename;
    }
    mapObj.layers[0] = new LayerObj ("park", "2", "c:/tmp/ms_tmp/102389536132841_layer_0.swf", "102389536132841_layer_0.swf");
    mapObj.layers[1] = new LayerObj ("popplace", "4", "c:/tmp/ms_tmp/102389536132841_layer_1.swf", "102389536132841_layer_1.swf");
    mapObj.layers[2] = new LayerObj ("rail", "1", "c:/tmp/ms_tmp/102389536132841_layer_2.swf", "102389536132841_layer_2.swf");
    mapObj.layers[3] = new LayerObj ("road", "1", "c:/tmp/ms_tmp/102389536132841_layer_3.swf", "102389536132841_layer_3.swf");

    This example is produced based on a mapfile with two layers defined in it. We create a layer class object containing useful information on a layer. The parameters are:

    • Name : the name found in the map file
    • Type : the type of layer ( 0 = Point Layer; 1=Line; 2=Polygon; 3=Raster; 4=Annotation; 6=Circle)
    • Fullname : Full name of the file with path included
    • Relative name : Relative Name

    For example you can use mapObj.layers[0].name to extract the name of the first layer.

    Note: All map parameters from MapServer are not exported at this time. We should come up with a list of information of what we want to output. Note that this information can be used in a Flash application to load the SWF file, to build a legend, to build a scale bar, etc.

  • SWF Files for each layer

    Each layer defined in the mapfile will have an associated SWF file created. The names of these SWF files are based on the name of the main file with an addition of ‘layer_X’ at the end of the name (where X is the layer index).

    These SWF files will contain vector and raster data as well as some Action Script depending on the layer and some configurations in the map file. We will see these configurations in detail in the following section.

Exporting Attributes

Exporting attributes works on a layer basis (it is only available for Vector Layers). To be able to export attributes to the SWF files, you have to define a metadata item called SWFDUMPATTRIBUTES in the layer section of the mapfile. Here is an example :

...
LAYER
NAME park
METADATA
  "DESCRIPTION""Parks"
  "RESULT_FIELDS" "NAME_E YEAR_EST AREA_KMSQ"
  "SWFDUMPATTRIBUTES" "NAME_E,AREA_KMSQ "
END
TYPE POLYGON
STATUS ON
DATA park
...

In the above example, the values for the attributes NAME_E and AREA_KMSQ will be exported for each element in the layer.

The resulting SWF File will have the values of these attributes (written in Action Script). Here is an example related to the above layer:

nAttributes= 2;
Attributes = new Array();
Attributes[0] = "NAME_E";
Attributes[1] = "AREA_KMSQ";
Element = new Array ();
Element[0] = new Array();
Element[0][0] = "Ellesmere Island National Park Reserve";
Element[0][1] = "1500";
Element[1][0] = " Aulavik National park";
Element[1][1] = "1500";

Events and Highlights

Here is what is currently implemented concerning events (events here refer to mouse events happening on an element. The available events are MOUSEUP, MOUSEDOWN, MOUSEOVER, MOUSEOUT):

  • Events are only available for layers that have defined attributes exported (using SWFDUMPATTRIBUTES). This is like defining that a certain layer is queryable.
  • When a mouse event happens on one of the elements, there is an Action Script call that is made: _root.ElementSelecetd(LayerId, ShapeId, Event) . The Flash application who wants to receive these events should define the function ElementSelected and use the information received to do actions like retrieving the attribute values from the specific SWF for the specified shape and display it.

In order to have highlighting, it has to be defined when the SWF is produced (basically highlighting means that the shape is redrawn using a different color).

As of MapServer 5.0, highlighting is available on queryable layers by using the QueryMap object in the map file to extract the color and do a highlight when on MOUSEOVER. The current implementation will highlight all objects that are in a layer that uses SWFDUMPATTRIBUTES, using the COLOR set in the QueryMap object in the mapfile.

Before MapServer 5.0, all objects that are in a layer that uses SWFDUMPATTRIBUTES are highlighted using a red color.

Fonts

Ming uses a special type of font called FDB files. It does not yet support Truetype fonts. Please refer to ming documentation on how to produce FDB files.

Outputting Raster SWF for Vector Layers

One mechanism would be to use the metadata for layer objects to define a raster output for vector layers. We could use something like “SWFOUTPUT” “RASTER”. If this sounds desirable, please file an enhancement ticket with this request, specifying the “Output-SWF” component.

What is Currently Supported and Not Supported

  1. Vector layers
    • Layer Point (case MS_LAYER_POINT) : done
      • msDrawMarkerSymbol
      • msDrawLabel
    • Layer line (case MS_LAYER_LINE) : done
      • msDrawLineSymbol
      • msDrawLabel
    • Layer circle ( case MS_LAYER_CIRCLE) : not done (should be done easily but missing data for testing)
      • omsCircleDrawLineSymbol
      • omsCircleDrawShadeSymbol
    • Layer annotation (case MS_LAYER_ANNOTATION): done
      • omsDrawMarkerSymbol
      • omsDrawLabel
    • Layer Polygon (MS_SHAPE_POLYGON): done
      • omsDrawShadeSymbol
      • omsDrawLineSymbol
      • omsDrawLabel
    • Vector Low Level functions
      • omsDrawMarkerSymbol
        • case(MS_SYMBOL_TRUETYPE) : done
        • case(MS_SYMBOL_PIXMAP) : done
        • case(MS_SYMBOL_ELLIPSE) : done
        • case(MS_SYMBOL_VECTOR) : done
      • omsDrawLineSymbol
        • case : simple line : done
    • drawing with the symbols : not done
      • omsDrawShadeSymbol
        • case : solid fill polygon : done
        • case : filled with symbols : cannot be implemented for now (tried to create a GD image to fill the shape but files created were huge)
      • omsCircleDrawLineSymbol : not done
      • omsCircleDrawShadeSymbol : not done
      • omsDrawLabel : done
      • omsDrawLabelCache : done
      • obillboard (shadow for texts) : not done
  2. Raster Layer
    • msDrawRasterLayer: done
  3. WMS Layer
    • msDrawWMSLayer: done
  4. Surround components (Legend, scalebar) : not supported