= Display of International Characters in !MapServer Labels =

== Credit ==

The following functionality was added to !MapServer 4.4.0 as a part of a project sponsored by the Information-technology Promotion Agency (IPA), in Japan.  Project members included: Venkatesh Raghavan, Masumoto Shinji, Nonogaki Susumu, Nemoto Tatsuya, Hirai Naoki (Osaka City University, Japan),
Mario Basa, Hagiwara Akira, Niwa Makoto, Mori Toru (Orkney Inc., Japan),
and Hattori Norihiro (E-Solution Service, Inc., Japan).

== Related Links ==

* !MapServer ticket:858

== Requirements ==

 * !MapServer >= 4.4.0
 * !MapServer compiled with the libiconv library

== Description ==

A MAPFILE LABEL parameter, named ''ENCODING'', can be used to convert strings from its original encoding system into one that can be understood by the True Type Fonts.
The ''ENCODING'' parameter accepts the encoding system as its parameter.

This uses GNU's libiconv ( http://www.gnu.org/software/libiconv/ ) so theoretically, every string with an encoding system supported by libiconv can be displayed as labels in MapServer as long as it has a matching font-set.

== Step 1: Verify ICONV Support and MapServer Version ==

Execute ''mapserv -v' at the commandline, and verify that your MapServer version >= 4.4.0 and it includes ''SUPPORTS=ICONV'', such as:

{{{
   > mapserv -v

     MapServer version 5.6.5 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG 
     SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=FRIBIDI 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 SUPPORTS=TILECACHE INPUT=JPEG 
     INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
}}}

== Step 2: Verify That Your Files' Encoding is Supported by ICONV ==

Since !MapServer uses the libiconv library to handle encodings, you can check the list of supported encodings here: http://www.gnu.org/software/libiconv/

Unix users can also use the ''iconv -l'' command on a system with
libiconv installed to get the complete list of supported encodings on
that specific system. 

== Step 3: Add ENCODING Parameter to your LABEL Object ==

Now you can simply add the ENCODING parameter to your mapfile LAYER object, such as:

{{{
  MAP
   ...
   LAYER
     ...
     CLASS
       ...
       LABEL
         ...
         ENCODING "SHIFT_JIS"
       END
     END
   END
  END
}}}

One of the benefits of having an "ENCODING" parameter within the LABEL object is that different LAYERS with different encoding systems can be combined together and display labels within a single map.  For example, labels from a Layer using Shapefile as it source which contains attributes in SHIFT-JIS can be combined with a Layer from a PostGIS database server with EUC-JP attributes.
A sample Mapfile can look like this:

{{{
  LAYER
    NAME "chimei"
    DATA chimei
    STATUS DEFAULT
    TYPE POINT
    LABELITEM "NAMAE"
    CLASS
      NAME "CHIMEI"
      STYLE
        COLOR 10 100 100
      END
      LABEL
        TYPE TRUETYPE
        FONT kochi-gothic
        COLOR 220 20 20
        SIZE 10
        POSITION CL
        PARTIALS FALSE
        BUFFER 0
        ENCODING SJIS
      END
    END
  END

  LAYER
    NAME "chimeipg"
    CONNECTION "user=username password=password dbname=gis host=localhost port=5432"
    CONNECTIONTYPE postgis
    DATA "the_geom from chimei"
    STATUS DEFAULT
    TYPE POINT
    LABELITEM "NAMAE"
    CLASS
      NAME "CHIMEI PG"
      STYLE
        COLOR 10 100 100
      END
      LABEL
        TYPE TRUETYPE
        FONT kochi-mincho
        COLOR 20 220 20
        SIZE 10
        POSITION CL
        PARTIALS FALSE
        BUFFER 0
        ENCODING EUC-JP
      END
    END
  END 

== Step 4: Test with the shp2img utility ==

 * see http://mapserver.org/utilities/shp2img.html