Is it possible to fill polygons so that they are completely transparent in MapServer? I want to have a black background that is slightly opaque, and wherever there is a polygon I want that to be completely clear with no fill. I set my background in the following way:

   IMAGECOLOR     0 0 0

I've tried creating a class that is white to fill the polygon, and experimented with opacity using TRANSPARENCY with values from 0 - 100 but it does not result in a clear polygon:

      NAME "light"  
      EXPRESSION ([max_cost] == 2000)     
        OUTLINECOLOR 255 255 255
        COLOR 255 255 255
        SIZE       1
        WIDTH      2.0        

This is results in the following type of image:

enter image description here

Instead of the polygon having a white fill; I want it to have a fill with no color. I found one suggestion online to define the color like this:

COLOR -1 -1 -1

but it also did not work. In this part of the documentation, the following is described:

“PALETTE=/path/to/palette.txt” is used to define the absolute path where palette colors can be found. This file must contain 256 entries of r,g,b triplets for RGB imagemodes, or r,g,b,a quadruplets for RGBA imagemodes. The expected format is one triplet (or quadruplet) per line, each value separated by commas, and each triplet/quadruplet on a single line. If you want to use transparency with a palette, it is important to have these two colors in the palette file: 0,0,0,0 and 255,255,255,255.

After reading this, I also tried using COLOR 0 0 0 0 but this throws an error:

Unknown identifier. Parsing error near (0):(line 71)

I don't understand how I refer to a define color in PALETTE=/path/to/palette.txt but this seems like one possible way to achieve this.

  • One way to avoid headache could be converting polygons to lines.
    – nadya
    Commented Dec 14, 2012 at 22:05
  • how could I have no-fill of the polygon that way?
    – djq
    Commented Dec 14, 2012 at 22:06
  • 2
    I mean, to create the line shapefile representing the polygon outlines using any GIS software, and add these lines to Mapserver instead of the polygons. Lines cannot have fill at all.
    – nadya
    Commented Dec 14, 2012 at 22:11
  • I don't mind if the lines appear or not; I just want a clear polygon fill.
    – djq
    Commented Dec 14, 2012 at 23:59
  • 1
    There is no need to convert polygons to lines - you can define 'TYPE line' for layer in MAP file also for polygon geometry Commented Dec 20, 2012 at 14:51

4 Answers 4


Mapserver has recently introduced the concept of mask layers (a mask behaves quite like a mask in Photoshop by blending with the layer it is applied to).

The RFC describes what they do and how they can be used. By reading your answer it seems like you could use a mask layer to obtain the 'keyhole' effect you are looking for.

I am not sure if this feature made it into the 6.2 that was released a couple of weeks ago.

  • Mask is nice but does not solve the given problem: the mask enables you to draw only inside the geometry, while in the given problem we need to draw only outside the geometry (i.e. color the background only outside the geometry). How to have a mask that is inverted and draws only outside ?
    – Skrol29
    Commented Sep 1, 2022 at 14:46

So, you want to "penetrate" the black background by your transparent polygons to see the lower background. I am not sure that it is possible with MapServer, but I can suggest another trick.

You can create a very big polygon covering all your area and even more extended, using any GIS software. Then you can erase your polygons from this area polygon, and then this holed polygon you can put on MapServer and make it black, instead of the black background. The holes corresponding your polygons are going to be "transparent".


I had these lines in my .map file and the transparency lower than 100 was working.

    NAME         core_areas
    DATA         core_areas.shp
    STATUS       ON
    TYPE         POLYGON
    SIZEUNITS pixels
    END # projection
        COLOR        20 150 90
        OUTLINECOLOR 7 56 41
        WIDTH        1
      END # STYLE
    NAME "Core areas"
  END # Layer

Hope it helps.

  • Did this result in a completely transparent polygon? I tried experimenting with values of TRANSPARENCY from 0 - 100 and it seemed to just adjust the opacity. I realize this was not clear in my question intially - I revised it.
    – djq
    Commented Dec 14, 2012 at 21:58
  • So, you want to have just the outline of the polygon and everything transparent inside, right? I probably misunderstood and suggested general transparency.
    – nadya
    Commented Dec 14, 2012 at 22:02
  • Sorry for the double confusion; just clear polygon fill; lines do not matter.
    – djq
    Commented Dec 15, 2012 at 0:00
  • 1
    @djq TRANSPARENCY was depricated at version 5.0. Layer OPACITY is the correct property to use.
    – DavidF
    Commented Dec 20, 2012 at 15:43

Below is a sample image showing a transparent mask layer. If you make the mask much bigger, then your user's won't notice the outer edges. Similar to what @nadya suggested, you can:

  1. Create a large rectangular polygon
  2. Create polygons for each of the "cut-outs"
  3. Subtract the smaller polygons from the bigger one (the Difference tool in QGIS works nicely for this)

transparent mask

At this point you will have a finished mask. However, if you want to add labels to the cut-out spaces, then you will need to add (using a Union tool) the smaller polygons back to the mask. Then, with an SLD file in Mapserver, you can style the mask as transparent gray, and style the cut-outs as completely transparent, and apply the labels there. Here's a sample SLD file (this was built for Geoserver):

<?xml version="1.0" encoding="UTF-8"?>
<StyledLayerDescriptor xmlns="http://www.opengis.net/sld" xmlns:sld="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc" xmlns:gml="http://www.opengis.net/gml" version="1.0.0">
      <Title>Polygon Style</Title>
              <CssParameter name="fill">#555555</CssParameter>
              <CssParameter name="fill-opacity">0.5</CssParameter>
              <CssParameter name="stroke-width">0</CssParameter>
              <CssParameter name="fill">#555555</CssParameter>
              <CssParameter name="fill-opacity">0</CssParameter>
              <CssParameter name="stroke">#000000</CssParameter>
              <CssParameter name="stroke-opacity">0</CssParameter>
              <CssParameter name="stroke-width">0</CssParameter>
              <ogc:Function name="centroid">
              <CssParameter name="font-family">Arial</CssParameter>
              <CssParameter name="font-size">11</CssParameter>
              <CssParameter name="font-style">normal</CssParameter>
              <CssParameter name="font-weight">bold</CssParameter>
                <CssParameter name="fill">#FFFFFF</CssParameter>
            <VendorOption name="conflictResolution">true</VendorOption>
            <VendorOption name="goodnessOfFit">0</VendorOption>

Note that the polygons would need to have the "TYPE" property with values "inner" or "outer" for this to work properly.

  • Thanks for your answer - is the SLD for geoserver related at all? I don't see the similarity between it and MapServer.
    – djq
    Commented Dec 20, 2012 at 18:37
  • Mapserver can use SLD, too. Here is an example, and here are the docs on SLD for Mapserver. SLD is an OGC standard, but, alas, it is not implemented exactly the same way in Geoserver and Mapserver. However, I expect the example above to work - even the filter.
    – katahdin
    Commented Dec 21, 2012 at 8:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.