[mapserver-commits] r8698 - trunk/docs/tutorial

[svn at osgeo.org]

Author: pnaciona
Date: 2009-03-09 10:35:08 -0400 (Mon, 09 Mar 2009)
New Revision: 8698

Added:
   trunk/docs/tutorial/example1-4.txt
Log:
Add tutorial example 1.4

Added: trunk/docs/tutorial/example1-4.txt
===================================================================
--- trunk/docs/tutorial/example1-4.txt	                        (rev 0)
+++ trunk/docs/tutorial/example1-4.txt	2009-03-09 14:35:08 UTC (rev 8698)
@@ -0,0 +1,106 @@
+.. _example1-4:
+
+===========
+Example 1.4
+===========
+Labeling the Map
+----------------
+          
+We can also add labels to our map...
+
+.. image:: http://biometry.gis.umn.edu/cgi-bin/mapserv.exe?map=/ms4w/apps/tutorial/htdocs/example1-4.map&layer=states_poly&layer=states_line&mode=map
+
+MapServer has a very flexible labeling engine.  It supports native bitmap as 
+well as truetype fonts.  Font scaling is supported with truetype. The labeling 
+angles and placements can be customized...  If you take the time to learn the 
+many parameters involved in creating good labels, you will be rewarded with 
+informative and aesthetically pleasing maps.
+
+This is what the map file looks like: `Example1-4.map <http://biometry.gis.umn.edu/tutorial/example1-4.map>`_.
+
+The map file structure, by objects, looks like this:
+
+::
+
+                                  MAP
+      (states_poly) LAYER----------|---------LAYER (states_line)
+     (land) CLASS-----|-CLASS (water)        |-CLASS
+        STYLE-|-LABEL   |-STYLE                |-STYLE</pre>
+
+Here we introduce a few more parameters along with the LABEL object:
+
+**FONTSET**
+          Here we specify the full path to our truetype fonts list (or fontset)
+          file. This file lists each of the available fonts. See the file
+          itself and the `MapServer font set documentation
+          <http://mapserver.gis.umn.edu/doc/fontset.html>`_ for more info.
+          FONTSET is a parameter of the MAP object.
+
+**LABELITEM**
+          This specifies which data attribute to use for labeling, in this
+          case "STATE". LABELITEM is a parameter of the LAYER object.
+
+**LABEL**
+          Marks the beginning of the LABEL object. The label object can be used 
+          under other objects (i.e. the SCALEBAR object).
+
+**COLOR**
+          Within the LABEL object, COLOR specifies the color of the label text.
+
+**SHADOWCOLOR**
+          This specifies the shadow color of the label text.
+
+**SHADOWSIZE**
+          Specifies the shadow size. The value corresponds to the X and the Y 
+          shifts in pixels. So, "2 2" means two pixels wide by two pixels high.
+
+**TYPE**
+          Within the LABEL object, TYPE specifies what type of font to use. We 
+          have the choice of TRUETYPE or BITMAP (the built-in fonts). We choose 
+          TRUETYPE.
+
+**FONT**
+          If you specify TYPE as TRUETYPE, you need to specify what font to use. 
+          The value here is the "alias" in the font list file.
+
+**SIZE**
+          If using truetype fonts, the value is size in pixels. If bitmap, you
+          can say something like "small" or "large".
+
+**ANTIALIAS**
+          This turns truetype antialiasing on or off. Remember the value isn't 
+          on or off but TRUE or FALSE.
+
+**POSITION**
+          Where to position the label text in relation to the label points.
+          The value is a combination of vertical and horizontal positions. You
+          have the following choices for vertical alignment: C for center, U
+          for upper, and L for lower. For horizontal alignment you have the
+          following choices: C for center, L for left, and R for right. So, to
+          align the label text to the center of label ID you'd use the value
+          "CC" (center-center). Or if you'd like it to be on the
+          lower left of the ID, you'd use LL. Another way is to let MapServer
+          decide the best position for your labels. For this you would use
+          the value "AUTO".
+
+**PARTIALS**
+          Tells MapServer whether to generate incomplete label texts or not.
+          The default here is not to generate fragments of a label text. The
+          value is either TRUE or FALSE.
+
+**MINDISTANCE**
+          This is the minimum distance in pixels between duplicate labels. See
+          what happens if you increase or decrease this value.
+
+**BUFFER**
+          The padding (in pixels) for each label. This is used to enhance
+          readability. A BUFFER of 4 pixels mean that no label will be drawn
+          within four pixels of each other. Again, change to see how it works.
+
+          You can also create labels separate from a POLYGON layer. You do
+          this with the ANNOTATION data type. Have a look at the next example's 
+          map file to see how you'd implement this kind of labeling.  You will 
+          notice that the CLASS object within the "label" layer has a COLOR 
+          parameter value of "-1 -1 -1". The negative number tells MapServer to 
+          give this CLASS a transparent color (the label IDs don't show up). 
+          Once again, play with the values to understand how it affects the map.