The element of personal knowledge, rather than general knowledge, is what can make a somewhat useful map into one that is very powerful. When words fail to describe the location of something that isn’t general knowledge, a map can round out the picture for you. Maps can be used to supplement a verbal description, but because creating a map involves drawing a perspective from your head, it can be very intimidating. That intimidation and lack of ownership over maps has created an interesting dilemma. In our minds, maps are something that professionals create, not the average person. Yet a map like the one shown in Figure 1-1 can have much more meaning to someone than a professional map of the same area. So what are the professional maps lacking? They show mostly common information and often lack personal information that would make the map more useful or interesting to you.

Digital mapping isn’t a new topic. Ever since computers could create graphic representations of the earth, people have been creating maps with them. In early computing, people used to draw with ASCII text-based maps. (I remember creating ASCII maps for role-playing games on a Tandy color computer.) However, designing graphics with ASCII symbols wasn’t pretty. Thankfully, more sophisticated graphic techniques on personal computers allow you to create your own high-quality maps.

Figure 1-1. A personal map drawn by Ryan Mendenhall showing Chicago Heights, Illinois, U.S.A.; this map is courtesy of Lori Napoleon’s maps project web site: http://www.subk.net/maps.html

You might already be creating your own maps but aren’t satisfied with the tools. For some, the cost of commercial tools can be prohibitive, especially if you just want to play around for a while to get a feel for the craft. Open source software alleviates the need for immediate, monetary payback on investment.

For others, cost may not be an issue but capabilities are. Just like proprietary software, open source mapping products vary in their features. Improved features might include ease of use or quality of output. One major area of difference is in how products communicate with other products. This is called interoperability and refers to the ability of a program to share data or functions with another program. These often adhere to open standards—protocols for communication between applications. The basic idea is to define standards that aren’t dependent on one particular software package; they would depend instead on the communication process a developer decided to implement. An example of these standards in action is the ability of your program to request maps from another mapping program over the Internet. The real power of open standards is evident when your program can communicate with a program developed by a different group/vendor. This is a crucial issue for many large organizations, especially government agencies, where sharing data across departments can make or break the efficiency in that organization. Products that implement open standards will help to ensure the long-term viability of applications you build. Be warned, however, that some products claim to be interoperable yet stop

short of implementing the full standards. Some companies modify the standards for their product, defeating the purpose of those standards. Interoperability standards are also relatively young and in a state of flux.

Costs and capabilities may not be the main barrier for you. Maybe you want to create your own maps but don’t know how. Maybe you don’t know what tools are available. This book describes some of the free tools available to you, to get you moving toward your end goal of map production.

Another barrier might be that you lack the technical know-how required for digital mapping. While conventional mapping techniques cut out most of the population, digital mapping techniques also prohibit people who aren’t very tech-savvy. This is because installing and customizing software is beyond the scope of many computer users. The good news is that those who are comfortable with the customization side of computerized mapping can create easy-to-use tools for others. This provides great freedom for both parties. Those who have mastered the computer skills involved gain by helping fill other’s needs. New users gain by being able to view mapping information with minimal effort through an existing mapping application.

Technological barriers exist, but for those who can use a computer and want to do mapping with that computer, the possibilities are endless. The mapping tools described here aren’t necessarily easy to use: they require a degree of technical skill. Web mapping programs are more complicated than traditional desktop software. There are often no simple, automated installation procedures, and some custom configuration is required. But in general, once set up, the tools require minimal intervention.

Generally speaking, there are two types of people who use web maps: service providers and end users.

For instance, I am a service provider because I have put together a web site that has an interactive mapping component you can see it at: http://spatialguru.com/maps/apps/global. One of the maps available to my end users shows the locations of several hurricanes. I’m safely tucked away between the Rocky and Coastal mountain ranges in western Canada, so I wouldn’t consider myself a user of the hurricane portion of the site. It is simply a service for others who are interested.

An end user might be someone who is curious about where the hurricanes are, or it may be a critical part of a person’s business to know. For example, they may just wonder how close a hurricane is to a friend’s house or they may need to get an idea of which clients were affected by a particular hurricane. This is a good example of how interactive mapping can be broadly applicable yet specifically useful.

End-user needs can vary greatly. You might seek out a web mapping site that provides driving directions to a particular address. Someone else might want to see an aerial photo and topographic map for an upcoming hiking trip. Some end users have a web mapping site created to meet their specific needs, while others just look on the Internet for a site that has some capabilities they are interested in.

Service providers can have completely different purposes in mind for providing a web map. A service provider might be interested in off-loading some of the repetitive tasks that come his way at the office. Implementing a web mapping site can be an excellent way of taking previously inaccessible data and making it more broadly available. If an organization isn’t ready to introduce staff to more traditional GIS software (which can have a steep learning curve), having one technical expert maintain a web mapping site is a valuable service.

Another reason a service provider might make a web mapping site available is to more broadly disseminate data without having to transfer the raw data to clients. A good example of this is my provincial government, the Province of British Columbia, Canada. They currently have some great aerial photography data and detailed base maps, but if you want the digital data, you have to negotiate a data exchange agreement or purchase the data from them. The other option is to use one of their web mapping sites. They have a site available that basically turns mapping into a self-serve, customizable resource; check it out at: http://maps.gov.bc.ca.

There are many web mapping sites available for you to use and explore. Table 1-1 lists a few that use software or apply similar principles to the software described in this book.

Figures 1-3, 1-4, and 1-5 show the web pages of three such sites. They show how diverse some MapServer applications can be, from street-level mapping to statewide overviews.

Figure 1-3. The MapServer-based restaurant mapping application from MapItOut

Figure 1-4. A MapServer-based tourism application for Hawaii from MapSherpa

Figure 1-5. A web map for finding recreation sites in Minnesota, U.S.A.

Of course, not all maps out there are built with MapServer; Table 1-2 lists other mapping sites that you may want to look to for inspiration.

A bad map isn’t much better than a blank map. This book doesn’t discuss good map design (the art of cartography), but an equally important factor plays into digital mapping: the quality of source data. Because maps are based on some sort of source data, it is imperative to have good quality information at the beginning. The maxim garbage in, garbage out definitely applies; bad data makes for bad maps and analysis. This is discussed in more detail in Chapter 5.

With the advent of digital mapping has come the loss of many traditional mapping skills. While digital tools can make maps, there are some traditional skills that are helpful. You might think that training in digital mapping would include the theory and techniques of traditional mapping processes, but it often doesn’t. Today, many who do digital mapping are trained to use only a specific piece of software. Take away that software or introduce a large theoretical problem, and they may be lost. Map projection problems are a good example. If you don’t understand how projections work, you can severely degrade the quality of your data when reprojecting and merging datasets as described in Chapter 8 and discussed in Appendix A.

Another example would be the ignorance of geometric computations. It was quite humiliating to realize that I didn’t know how to calculate the area of an irregular polygon; nor was it even common knowledge to my most esteemed GIS colleagues. Figure 2-2 shows a range of common shapes and the formulae used to calculate their area.

Figure 2-2. How to calculate the area of common shapes, including a square, circle, triangle, and the infamous irregular polygon

Many of the calculations were taught in elementary school but not for the irregular polygon. It doesn’t use a simple formula, and there are multiple ways to calculate the area. One method is to triangulate all the vertices that make up the polygon boundary and then calculate and sum the area of all those triangles. You can see why we let the computer do this kind of task!

It was rather amusing to realize that we used digital tools to calculate areas of polygons all the time but had little or no idea of how it was done. On the other hand it was disconcerting to see how much of our thinking was relegated to the computer. Most of us could not even verify computed answers if we wanted to!

Digital mapping and GIS need to become more than just a tool for getting to the end goal. More theory and practice of manual skills would better enable the map maker and analyst to use digital tools in a wise manner. It goes without saying that our dependency on digital tools doesn’t necessarily make us smarter. Because this book doesn’t teach cartographic theory, I recommend you find other texts that do. There are many available, including:

There are many different mapping data formats in use today. In order to use map data effectively you must understand what format your data is in, and you must know what data format you need. If the current format isn’t suitable, you must be able to convert it to an intermediate format or store it in a different manner.

Make sure you understand what task you are going to need the source data for. Will you be printing a customized map and combining it with other pieces of data, or will you simply view it on the screen? Will you need to edit the data or merge it with other data for analysis? Your answers to these questions will help you choose the appropriate formats and storage methods for your tasks.

There are numerous digital mapping tools available. This makes the choice of any given tool difficult. Some think that the biggest, most expensive tools are the only way to go. They may secretly believe that the product is more stable or better supported (when, in fact, it may just be slick marketing). Choosing the right tool for the job is very difficult when you have so many (seemingly) comparable choices. For example, sometimes GIS tools are used when a simple drawing program may have been more effective, but this was never considered because the users were thinking in terms of a GIS software package.

Examples of extreme oversimplification and extreme complexity are frequently found when using mapping and GIS software. You can see the best example of this problem when comparing computer-aided design (CAD) technicians and GIS analysts. GIS analysts often maintain very modular, relatively simple pieces of data requiring a fair bit of work to make a nice visual product. CAD users have a lot of options for graphical quality, but often lack easy-to-use analytical tools. The complexity of trying to understand how to style, move, or edit lines, etc., makes many CAD programs difficult to use. Likewise, the complexities of data management and analytical tools make some GIS software daunting.

Viewing and mapping data aren’t necessarily the same thing. Some applications are intended only for visualizing data, while others target map production. Map production is more focused on a high-quality visual product intended for print. In the case of this book, viewing tools are used for visually gathering information about the map data—how the data is laid out, where (geographically) the data covers, comparing it to other data, etc.

Mapping tools are used to publish data to the Internet through web mapping applications or web services. They can also be used to print a paper map. The concepts of viewing and mapping can be grouped together because they both involve a graphic output/product. They tend to be the final product after the activities in the following categories are completed.

Just viewing maps or images isn’t usually the final goal of a project. Certain types of analysis are often required to make data visualization more understandable or presentable. This includes data classification (where similar features are grouped together into categories), spatial proximity calculations (features within a certain distance of another), and statistical summary (grouping data using statistical functions such as average or sum). Analysis tends to summarize information temporarily, whereas manipulating data can change or create new data.

This category can include creating features, which uses a process often referred to as digitizing. These features may be created as a result of some sort of analysis. For example, you might keep features that are within a certain study area.

You can manipulate data with a variety of tools from command-line programs to drag and drop-style graphical manipulation. Many viewing applications can’t edit features. Those that can edit often create new data only by drawing on screen (a.k.a. digitizing) or moving features. Some products have the ability to do more, such as performing buffering and overlap analysis or grouping features into fewer, larger pieces. Though these are common in many commercial products, open source desktop GIS products with these capabilities are just starting to appear.

Certain applications require data to be in certain file or database formats. This is particularly the case in the commercial world where most vendors support their own proprietary formats with marginal support for others. This use of proprietary data formats has led to a historic dependency upon a vendor’s product. Fortunately, recent advances in the geomatics software industry have led to cross-application support for more competitor formats. This, in turn, has led to interoperable vendor-neutral standards through cooperative organizations such as the Open Geospatial Consortium (OGC). The purpose of the OGC and their specifications are discussed in more detail in Chapter 12.

Source data isn’t always in the format required by viewing or manipulating applications. If you receive data from someone who uses a different mapping system, it’s more than likely that conversion will be necessary. Output data that may be created by manipulation processes isn’t always in the format that an end user or client may require. Enter the role of data conversion tools that convert one format into another.

Data conversion programs help make data available in a variety of formats. There are some excellent tools available, and there are also support libraries for applications, making data conversion unnecessary. Data access libraries allow an application to access data directly instead of converting the data before using it with the application.

Some examples of these libraries are discussed later in this chapter. For an excellent commercial conversion tool, see Safe Software’s Feature Manipulation Engine (FME) at http://safe.com.

You are probably reading this book because you desire to share maps and mapping data. There is a certain pleasure in creating and publishing a map of your own. Because of the variety of free tools and data now available, this is no longer just a dream.

This book addresses two aspects of that sharing. First, sharing maps (static or interactive) through web applications and second, using web service specifications for sharing data between applications.

The term web mapping covers a wide range of applications and processes. It can mean a simple web page that shows a satellite image or a Flash-based application with high levels of interaction, animations, and even sound effects. But, for the most part, web mapping implies a web page that has some sort of interactive map component. The web page may present a list of layers to the user who can turn them on or off, changing the map as he sees fit. The page may also have viewing tools that allow a user to zoom in to the map and view more detail.

The use of Open Geospatial Consortium (OGC) web services (OWS) standards allow different web mapping applications to share data with each other or with other applications. In this case, an application can be web-enabled but have no graphical mapping interface component riding on top of it. Instead, using Internet communication standards other applications can make a request for data from the remote web service. This interoperability enables different pieces of software to talk to each other without needing to know what kind of server is providing the information. These abilities are still in their infancy, particularly with commercial vendors, but several organizations are already depending on them. Standardized web services allows organizations to avoid building massive central repositories, as well as access data from the source. They also have more freedom when purchasing software, with many more options to choose from. OWS is an open standard for sharing and accessing information; therefore organizations are no longer tied to a particular vendor’s data format. The software needs only to support OWS. For example, Figure 2-3 shows a map created from multiple data sources. Several layers are from a copy of map data that the mapping program accesses directly. The other two layers are from OWS data sources: one from a company in The Netherlands (elevation shading), and the other (weather radar imagery) from a university in the United States.

Figure 2-3. A map made from multiple remote servers using an OWS specification

MapServer supports a variety of formats. Some are native to the MapServer executable, while others are accessed through the GDAL/OGR libraries. The latter approach is necessary for formats not programmed directly into MapServer. Access through the libraries adds an extra level of communication between MapServer and the data source itself (which can cause poor performance in some cases).

In general, formats supported natively by MapServer should run faster than those using GDAL/OGR. For example, the most basic format MapServer uses is the ESRI shapefile or GeoTiff image. OGR supports the U.S. Census TIGER file format. The performance difference between loading TIGER or shapefiles can be considerable. However, using GDAL/OGR may not be the problem. Further investigation shows that the data formats are often the bottleneck. If the data in a file is structured in a way that makes it difficult to access or requires numerous levels of interpretation, it affects map drawing speed.

The general rule of thumb for best performance is to use ESRI shapefile format or GeoTiff image format. Because gdal_translate and ogr2ogr can write into these formats, most source data can be translated using these tools. If you access data across a network, storing data in the PostGIS database may be the best option. Because PostGIS processes your queries for data directly on the server, only the desired results are sent back over the network. With file-based data, more data has to be passed around, even before MapServer decides which pieces it needs. Server-side processing in a PostGIS database can significantly improve the performance of MapServer applications.

Wholesale conversions aren’t always possible, but when tweaking performance, these general rules may be helpful.

MapServer and its supporting tools are available for many hardware and operating systems. Furthermore, MapServer functionality can be accessed through a variety of programming language interfaces, making it possible to integrate MapServer functionality into custom programs. MapServer can be used in custom environments where other web mapping servers may not run.

Because MapServer is open source, developers can improve, fix, and customize the actual code behind MapServer and port it to new operating systems or platforms. In fact, if you require a new feature, a developer can be hired to add it, and everyone in the community can benefit from the work.

MapServer is primarily a viewing and mapping application; users access maps through a web browser or other Internet data sharing protocols. This allows for visual sharing of mapping information and real-time data sharing with other applications using the OGC specifications. MapServer can perform pseudo data conversion by reading in various formats and providing access to another server or application using common protocols. MapServer isn’t an analysis tool, but it can present mapping information using different cartographic techniques to visualize the results.

GDAL supports dozens of raster formats. This list is taken from the GDAL web site formats list page found at http://www.gdal.org/formats_list.html.

This list is comprehensive but certainly not static. If a format you need isn’t listed, you are encouraged to contact the developers. Sometimes only a small change is required to meet your needs. Other times it may mean your request is on a future enhancement waiting list. If you have a paying project or client with a particular need, hiring the developer can make your request a higher priority. Either way, this is one of the great features of open source software development—direct communication with the people in charge of development.

All these formats can be read, but GDAL can’t write to or create new files in all these formats. The web page shown earlier lists which ones GDAL can create.

As mentioned earlier, an important feature of GDAL is its availability as a set of programming libraries. Developers using various languages can take advantage of GDAL’s capabilities, giving them more time to focus on other tasks. Custom programming to support formats already available through GDAL isn’t necessary: reusability is a key strength of GDAL.

GDAL’s application programming interface (API) tutorial shows parallel examples of how to access raster data using C, C++, and Python. You can also use the Simplified Wrapper and Interface Generator (SWIG) to create interfaces for other programming languages such as Perl, Java, C#, and more. See http://www.swig.org/ for more information on SWIG.

The ability to directly link to GDAL libraries has helped add features to an array of GIS and visualization programs both commercial and open source. The GDAL website lists several projects that use GDAL, including FME, MapServer, GRASS, Quantum GIS, Cadcorp SIS, and Virtual Terrain Project.

GDAL also has some powerful utilities. Several command-line data access/manipulation utilities are available. All use the GDAL libraries for tasks such as the following:

In general, GDAL aids in accessing, converting, and manipulating rasters/images. When further programming is done using languages such as Python, GDAL can also serve as a powerful analysis tool. In one sense GDAL can also be used as a rough viewing tool because it allows conversion into commonly viewable formats (e.g., JPEG) for which many non-GIS users may have viewing software.

The following list of the vector data formats supported by OGR was taken from the OGR formats web page at http://www.gdal.org/ogr/ogr_formats.html. The web page also shows which formats can be written or only read by OGR.

OGR is part of the GDAL/OGR project and is packaged with GDAL. GDAL deals with raster or image data, and OGR deals with vector data. GDAL is to painting as OGR is to connect-the-dot drawings. These data access and conversion libraries cover the breadth of mapping data.

Like GDAL, OGR consists of a set of libraries that can be used in applications. It also comes with some powerful utilities:

OGR, like GDAL, aids in accessing, converting, and manipulating data, specifically vector data. OGR can also be used with scripting languages, allowing programmatic manipulation of data. GDAL/OGR packages typically come with OGR modules for Python. In addition to Python bindings, Java and C# support for GDAL/OGR are in development as of Spring 2005. Perl and PHP support may also be available in the future.

PostGIS allows you to use SQL statements to manipulate and create geographic data—for example, to buffer points and create circles. This is just the tip of the iceberg. PostGIS can be a GIS in and of itself while at the same time, all the power of PostgreSQL as a tabular database is available. GIS overlays, projecting and reprojecting of features into other coordinate systems, and spatial proximity queries are all possible using PostGIS. It is possible to have all the standard GIS overlay and data manipulation processes available in a server-side database solution. Example 3-1 illustrates the marriage of SQL and GIS capabilities by selecting points contained by another shape. More examples are shown in Chapter 13.

> SELECT town_name
                  
    FROM towns, ontario
                  WHERE Contains(ontario_polygon,#first feature
                  town_points);    #containing the others

     town_name
-------------------
 Port Hope Simpson
 Hopedale
 Makkovik
 Churchill Falls
 North West River
 Rigolet
 Cartwright
 Tignish
 Cheticamp
 Sheet Harbour
(10 rows)

PostGIS is increasingly used as a tool for map data storage and manipulation. It is ideal for situations in which multiple applications access information simultaneously. Regular processing tasks can be set up while also making the data available to a web mapping site.

Other GIS and mapping tools are able to interact with PostGIS data. OGR, for example, can read/write PostGIS data sources. MapServer can also access PostGIS data. Many people rely on this combination to serve up their maps. Some use custom MapServer applications to add or update information stored in PostGIS-enabled databases. A product called GeoServer (see http://geoserver.sourceforge.net) uses the OGC Transactional Web Feature Server (WFS-T) standard for read/write access to PostGIS and other formats. A PostGIS function exists for returning Scalable Vector Graphics (SVG) representations of geometries. The Quantum GIS (QGIS) desktop program (see http://www.qgis.org) can also read from PostGIS, and current development will extend that to also allow editing.

The internal programming capabilities of PostgreSQL (using related procedural languages such as Pl/Pgsql and Pl/Python) allow programmatic access to various PostGIS functions and PostGIS data. Many PostGIS functions allow for a range of manipulation as well as conversion into different data types (e.g., as simple text strings, binary, or even as SVG).

A PostGIS spatial has many of the functions of a normal database—one being that they both use SQL commands to access data. With PostGIS, the information can also include the PostGIS geometry data. PostGIS functions can then manipulate, summarize, or create new spatial data.

The simplest form of MapServer runs as an executable CGI application on a web server. Technically, MapServer is considered an HTTP-based stateless process. Stateless means that it processes a request and then stops running. A CGI application receives requests from a web server, processes them, and then returns a response or data to the web server. CGI is by far the most popular due to its simplicity: no programming is required to get it working. You edit the text-based, runtime configuration file, create a web page, and then set them up to be served by a web server.

Figure 4-3. Main MapServer application components

The MapServer CGI executable acts as a middle man between the mapping data files and the web server program requesting the map. The requests are passed in the form of CGI parameters from the web server to MapServer. The images that are created by MapServer are then fed back to the web server and, ultimately, to the user’s web browser. More on the MapServer executable and how to install it is discussed later in this chapter.

The focus of this chapter is on using MapServer to create a map image. MapServer can also create scale bars, legends, and reference/key maps for your application, as discussed in Chapters 10 and 11.

MapServer is like an engine that requires fuel to run and a fuel delivery system to get the fuel to the engine. The MapServer program needs to know what map layers to draw, how to draw them, and where the source data is located. The data is the fuel, and the map file—also known as the mapping file or .map file—serves as the delivery system. The map file is a text configuration file that lists the settings for drawing and interacting with the map. It includes information about what data layers to draw, where the geographic focus of the map is, what projection system is being used, and which output image format to use, and it sets the way the legends and scale bars are drawn. An extremely simple version of a map file is shown in Example 4-1.

MAP
  SIZE 600 300
  EXTENT -180 -90 180 90
  LAYER
    NAME countries
    TYPE POLYGON
    STATUS DEFAULT
    DATA countries.shp
    CLASS
      OUTLINECOLOR 100 100 100
    END
  END
END

When a request comes to a MapServer application, the request must specify what map file to use. Then MapServer creates the map based on the settings in the map file. This makes the map file the central piece of any MapServer application. Map files are covered in greater detail in Chapter 10, where the process of creating a MapServer application is discussed.

If the map file is the fuel delivery system, the data sources are the fuel. MapServer can use a vast array of data sources to create maps. Out-of-the-box support covers the most common formats. Optional data access add-ons open up access to dozens of vector and raster formats (formats supported by the GDAL and OGR libraries). These may be GIS data files, database connections, or even flat comma-separated text files using the Virtual Spatial Data format capabilities of OGR.

MapServer can also use the OGC web specifications to access and share data across the Internet. Map layers can be requested from remote servers that also use OGC specifications. More on data sources is discussed in Chapter 5. For more about the purpose and goals of the OGC and OGC web services, see Chapter 12.

While the map file is the central part of any MapServer application, the map image that is generated is usually what the end user is after. After all the layers are processed and written to a web-friendly graphics file, the user’s web browser is then directed to load the image into the web page for viewing. Many first-time users experience problems with MapServer not returning the output map image. Chapter 11 covers in more detail how to set up MapServer to handle the map image.

The map isn’t the only image that can be created. Scale bars, graphic legends and reference maps can also be part of a MapServer application. These are handled in a similar manner as the map image. Chapters 10 and 11 show examples that use these.

Many operating systems and processors can run MapServer successfully. A recent survey of MapServer application developers showed dozens of different implementations running on many processor speed and type combinations. Included in the survey results were the following operating systems:

Reported processor speeds were as low as 120 MHz and as little as 64 MB of memory. Others use the latest processing and memory resources available. With the diversity and flexibility required to meet these cross-platform requirements many developers have found MapServer to be the only option for serving web-based maps.

Many documents or how-tos include information on compiling MapServer, which can lead you to assume that compiling MapServer from source code is required. For most users it isn’t required. Acquiring binaries refers to the process of downloading executables and libraries that are ready to run on your operating system of choice, without compiling from source code.

Any project claiming to be open source must provide access to the source code. In MapServer’s case, this allows you to modify the MapServer code to meet your specific needs. Even if you don’t plan to modify the source code, you may still want to compile directly from the source code. Some MapServer users find they need to compile their own version to include (or exclude) certain features. For example, there are a variety of data formats usually included in the binary distributions of MapServer. Quite often there are more formats than you require for a given application and you can remove support for those formats. If a certain format isn’t available by default, it can usually be added during the compilation process.

The compilation examples in this chapter are shown using Linux and open source compiling tools from the GNU project (see http://gnu.org). Tools and commands are run from the command line or shell console. Compiling for other operating systems varies depending on what tools are available. This section assumes that you are comfortable compiling code and have the appropriate tools available, including a C compiler such as gcc and configuration/building tools such as autoconf and automake.

    # tar -xzvf mapserver-4.4.0.tar.gz

# ./configure
loading cache ./config.cache
checking for gcc... (cached) gcc
checking whether the C compiler (gcc  ) works... yes
checking whether the C compiler (gcc  ) is a cross-compiler... no
checking whether we are using GNU C... (cached) yes
checking whether gcc accepts -g... (cached) yes
checking for c++... (cached) c++
checking whether the C++ compiler (c++  ) works... yes
checking whether the C++ compiler (c++  ) is a cross-compiler... no
....
checking where PNG is installed...
checking for png_init_io in -lpng... no
        PNG (libpng) library cannot be found, possibly needed for GD
checking where libXpm is installed...
checking for XpmFreeXpmImage in -lXpm... no
        XPM (libXpm) library cannot be found, possibly needed for GD
checking where libiconv is installed...
checking for libiconv_open in -liconv... no
        libiconv library cannot be found, possibly needed for GD
checking for GD 2.0.12 or higher...
checking for gdImageSetAntiAliased in -lgd... yes
        using libgd 2.0.12 (or higher) from system libs
              (-L/usr/lib -lgd -ljpeg -lfreetype  -lz  ).
....
checking whether we should include PROJ.4 support...
        PROJ.4 support not requested.
checking whether we should include thread safe support...
        thread safe support disabled.
checking whether we should include ESRI SDE support...
        ESRI SDE support not requested.
checking whether we should compile in MPATROL support...
        MPATROL support not requested.
checking whether we should include OGR support...
        OGR support not requested.
checking if GDAL support requested... no
checking if PostGIS support requested... no
checking if MyGIS support requested... no
checking if OracleSpatial support requested... no
checking if MING/Flash support requested... no
checking whether we should include WMS Server support...
        OGC WMS Compatibility not enabled (PROJ.4 is required for WMS).
checking whether we should include WFS Server support...
        OGC WFS Server support not requested.
checking whether we shou install/erase scriptlets from  package(s)
ld include WMS Client Connections support...
        OGC WMS Client Connections not enabled (PROJ.4 and libcurl required).
checking whether we should include WFS Client Connections support...
        OGC WFS Client Connections not enabled (PROJ.4, libcurl and OGR required).
....
updating cache ./config.cache
creating ./config.status
creating Makefile

loading cache ./config.cache
checking for gcc... (cached) gcc
checking whether the C compiler (gcc  ) works... no
configure: error: installation or configuration problem:
                   C compiler cannot create executables.

    PNG (libpng) library cannot be found, possibly needed for GD

    PROJ.4 support not requested.

ESRI SDE support not requested.
checking if PostGIS support requested... no
checking if MyGIS support requested... no
checking if OracleSpatial support requested... no

updating cache ./config.cache
creating ./config.status
creating Makefile

    # ./configure --help  | more

--with-jpeg[=DIR]       Include JPEG support (DIR is LibJPEG's install dir).
--with-freetype=DIR     GD: Specify where FreeType 2.x is installed
                          (DIR is path to freetype-config program or install dir).
--with-zlib=DIR GD: Specify where zlib is installed (DIR is path to zlib install dir).
--with-png=DIR GD: Specify where PNG is installed (DIR is path to PNG install dir).
--with-xpm=DIR  GD: Specify where libXpm is installed (DIR it the libXpm install prefix).
--with-libiconv=DIR     GD: Specify where libiconv is installed
                          (DIR is path to libiconv install dir).
--with-gd[=[static,]DIR] Specify which version of GD to use (DIR is GD's install dir).
--with-pdf[=DIR]        Include PDF support (DIR is PDFlib's install dir).
--with-tiff[=DIR]       Include TIFF support (DIR is LibTIFF's install dir).
--with-eppl             Include EPPL7 support.
--with-proj[=DIR]       Include PROJ.4 support (DIR is PROJ.4's install dir).
--with-threads[=linkopt]Include thread safe support
--with-sde[=DIR]        Include ESRI SDE support (DIR is SDE's install dir).
--with-sde-version[=VERSION NUMBER]  Set ESRI SDE version number (Default is 80).
--with-mpatrol[=DIR]    Include MPATROL support (DIR is MPATROL's install dir).
--with-ogr[=PATH]       Include OGR support (PATH is path to gdal-config).
--with-gdal[=PATH]      Include GDAL support (PATH is path to gdal-config)
--with-postgis[=ARG]    Include PostGIS Support (ARG=yes/path to pg_config)
--with-mygis[=ARG]      Include MyGIS Support (ARG=yes/path to my_config)
--with-oraclespatial[=ARG] Include OracleSpatial Support (ARG=yes/path to Oracle home)
--with-ming[=DIR]       Include MING/Flash Support (DIR=path to Ming
                          directory)
--with-wfs              Enable OGC WFS Server Support (OGR+PROJ4 required).
--with-wmsclient        Enable OGC WMS Client Connections (PROJ4 and libcurl
                          required).
--with-wfsclient        Enable OGC WFS Client Connections (PROJ4, libcurl and
                          OGR required).
--with-curl-config=PATH Specify path to curl-config.
--with-httpd            Specify path to 'httpd' executable.
--enable-ignore-missing-data   Ignore missing data file errors at runtime
                                 (enabled by default).
--enable-debug          Include -g in CFLAGS for debugging and enable
                        msDebug() output to stderr (i.e. server log file).
--with-php=DIR          Specify directory where PHP4 source tree is
                        installed. Required in order to compile the
                        PHP/MapScript module.

                  ./configure --with-jpeg

     --with-jpeg[=DIR]

    Include JPEG support (DIR is LibJPEG's install dir)

    ./configure --with-jpeg=/usr

    --with-gdal[=PATH] Include GDAL support (PATH is path to gdal-config)

                  ./configure --with-jpeg --with-png --with-ogr --with-gdal=/usr/local/bin/gdal-config
    --with-postgis

    checking whether we should include OGR support...
    ./configure: line 1: /usr/local/bin/gdal-config: No such file or directory

# ./configure --without-gd
...
checking for GD 2.0.12 or higher...
configure: error: GD library cannot be disabled

    rpm -qa | grep <name of package>

    rpm -qa | grep gd

# make
gcc -c -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include maptemplate.c -o maptemplate.o
gcc -c -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include mapbits.c -o mapbits.o

[ *.........80+ lines removed...........* ]

gcc -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include sortshp.o
   -L. -lmap -lgd -L/usr/lib -lgd -ljpeg -lfreetype -lz -ltiff -ljpeg
   -lfreetype -lz -ljpeg -lm -lstdc++ -o sortshp
touch mapscriptvars
pwd > mapscriptvars
echo -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT >> mapscriptvars
echo -I.  -I/usr/include >> mapscriptvars
echo  -L. -lmap -lgd -L/usr/lib -lgd -ljpeg -lfreetype -lz -ltiff -ljpeg
   -lfreetype -lz -ljpeg -lm -lstdc++ >> mapscriptvars
echo   >> mapscriptvars
gcc -c -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include tile4ms.c -o tile4ms.o
gcc -O2 -Wall -DIGNORE_MISSING_DATA -DUSE_TIFF -DUSE_JPEG -DUSE_GD_PNG
   -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_FT -I/usr/include tile4ms.o
   -L. -lmap -lgd -L/usr/lib -lgd -ljpeg -lfreetype -lz -ltiff -ljpeg
   -lfreetype -lz -ljpeg -lm -lstdc++ -o tile4ms
#

# make install
***** MapServer Installation *****
To install MapServer, copy the 'mapserv' file to your web server's cgi-bin
directory.
If you use MapScript then see the documentation for your specific MapScript
version for installation instructions.

# ./mapserv -v
MapServer version 4.4.0 OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
   SUPPORTS=FREETYPE INPUT=TIFF INPUT=JPEG INPUT=SHAPEFILE

# ./mapserv
This script can only be used to decode form results and
should be initiated as a CGI process via a httpd server.

    http://localhost/cgi-bin/mapserv
    No query information to decode. QUERY_STRING is set, but empty.

# rpm -qpl mapserver-4.0.1-1.i386.rpm
/usr/bin/shp2img
/usr/bin/shptree
/usr/bin/sortshp
/usr/bin/tile4ms
/var/www/cgi-bin/mapserv

A quick test of the install

You can run a basic test on MapServer by running the mapserv or mapserv.exe program. The simplest test you can do is from the command line. First, you open a command prompt, and change into, or at least find, the folder that contains mapserv, mapserv.exe, or mapserv_ xx where xx can be a version number such as 44 for mapserv Version 4.4. For MS4W, mapserv.exe is located in the c:\ms4w\apache\cgi-bin folder.

If you compile from source, mapserv is in the source code folder it was compiled in. If you install from an RPM binary, mapserv is in the default Apache web server folder. For example, on SuSE, it’s in /srv/www/cgi-bin, and on Fedora, it’s in /var/www/cgi-bin.

From the command prompt, execute the mapserv program. For example, on SuSE Linux, use the command:

    /srv/www/cgi-bin/mapserv

With MS4W, use:

    c:\ms4w\apache\cgi-bin\mapserv.exe

Either way, the output you get should look like:

    This script can only be used to decode form results and
    should be initiated as a CGI process via a httpd server.

Yes, this is an error message, but it confirms that you at least have a working version of the MapServer program. Congratulations—you are ready to start working with MapServer in Chapters 10 and 11.

If all the dependencies for MapServer aren’t available, you may get a different error message. Figure 4-4 shows an example of a Windows error message when a supporting library, GDAL for instance, can’t be found.

Figure 4-4. Dependency error message from MapServer on Windows

If you want to make a custom map, you need to determine what kind of map data you require. There are two kinds of maps, each requiring different kinds of map data.

A vector map shows features made up of points, lines, or polygon areas, as in Figure 5-1. For instance, this can be a local road map or a global map showing locations of power stations and their respective countries.

An image or raster map is made from data sources such as aerial photography, satellite imagery, or computer-generated images of Earth’s surface. Figure 5-2 shows an example of a raster map made from weather satellite data.

One variant of the raster map is the scanned map. When a paper map is scanned, it is converted into a digital raster map and can then be used as a layer on other maps. This is one way to make mapping data more readily available without having to recreate the maps using digital sources.

Figure 5-1. A vector map showing roads, country borders, and some major cities in North America

Figure 5-2. A raster map showing cloud cover over North America

A map often combines vector and raster data to create a more effective map than either could produce in isolation, as in Figure 5-3. Pure vector maps and pure raster maps are at opposite ends of a continuum of map types; many maps include both kinds of data.

Each of the three types of vector data (point, line, and polygon) can be used to show certain types of information on a map. Points can show the location of towns or the position of a radio tower. Lines can show travel routes or boundaries. Polygons can be shaded to show a lake or highlight a country on a world map. Each piece of vector

Figure 5-3. A combined vector and raster map over North America

data can have other information associated with it that could, for example, be used to label a feature on the map.

When determining what kind of vector data you require, consider what you want to draw on your map. Will you need to draw text labels on top of line features? Are you planning to use a simple list of coordinates (e.g., in a spreadsheet) to show the point location of features, or do you need more complex boundary data to outline an area?

Digital images, such as aerial photographs or satellite images, are part of the raster family of mapping data. A raster represents a continuous grid of data. The grid is made up of small squares, also known as cells or pixels. Each square can have one or more values associated with it. Values used in color images, like photographs, represent the levels of red, green, and blue in a cell. Values can also represent elevations when used in a digital elevation model (DEM) raster.

Decide what kind of raster data you need. Then, when you’ve found some data, you need to decide whether it is useful as is or if you need to modify or enhance it.

If you’ve ever looked for a small lake near your home on a map of the world, you’ll understand that maps can’t show every tiny feature. If you took a 12-inch map of the world and stretched it to fit the side of a house, you might be able to see some smaller features; they would be larger than they were before. This kind of map would be called large-scale because it makes features larger for the viewer. A smaller-scale map shrinks these features but can cover a greater area.

Understanding the size and scale of the map you want to create is very important because it will dictate the precision of data you require. For example, if you want to make a map of your neighborhood, basic world map data may not be detailed enough to even show your street. Likewise, if you want to create a global map that shows the distribution of weather patterns, highly detailed road line data is probably going to be irrelevant.

Most data is created to be viewed at a specific scale. If you try to use the data at a different scale than it was intended for, it may not look right and might not align with other features properly. Decide on the size of map you want to create, especially if you plan to print the map onto paper. Then decide what you want to fit onto that map—something showing your country or your city? How big do you really want it to end up being drawn? If it is only going to be a digital map, how much of the map do you want to see on the screen? This will help you know what scale of information to hunt down. Of course, if it is a digital map, you will have a lot more flexibility than if you are looking to print the final product.

Sometimes you want to create a map that can give a three dimensional (3D) perspective to your data. This type of analysis can be complex.

Three-dimensional perspectives simulate what an area of land looks like from above looking down or from the ground looking up. These maps are used in areas where a good view of the physical relief is required, such as when planning a hike up a mountain range or planning a hydroelectric dam project. A traditional 2D map is still quite useful, but there is nothing like creating a map that makes information look more like the real world.

If you want to try 3D mapping, you need to keep a few things in mind. First, you need to decide how you are going to represent the elevation data. An elevation model is often represented by a 2D raster that shows the changes in elevation. In general, the raster is shaded from dark to light to represent these elevation changes, and each square on the raster is shaded to show a certain elevation. Figure 5-4 shows an elevation shaded raster where black is the lowest level, and white is the highest. In some programs, this type of raster is called a height field map or hillshade.

Figure 5-4. Example hillshade image in northern Minnesota, U.S.A.

The other element to 3D mapping is the type of information you want to lay on top of the elevation model. Other images or vectors can be overlaid on top of the elevation model through a process known as draping. Draping is named after the concept of laying a piece of light fabric on a bumpy surface, like a bed sheet over a basketball. The draped layer takes the form of the underlying elevation model to give a unique perspective to the draped information. Figure 5-5 shows the same image as in Figure 5-4 but represented in 3D using OpenEV.

Figure 5-5. Example hillshade image draped over a 3D surface

If you can’t find elevation model data or decide what types of information to drape over it, you will probably not be able to do 3D mapping. Specific examples of 3D mapping are given in Chapter 8.

Sometimes all you want is a premade, basic map of the world or a specific country. The Internet can be a good place to find these. One excellent site is the CIA World Factbook at http://www.cia.gov/cia/publications/factbook/geos/ag.html. Here you will find a basic political map for every country and also a detailed demographic, cultural, and political summaries. Large-size, print-quality reference maps are also available in Portable Document Format (PDF).

Another good resource is the University of Texas Online Map Library at http://www.lib.utexas.edu/maps/. With a brief walk through some of the links, you can find diverse maps that show, for example, a street map of Baghdad or a shaded relief map of the United Kingdom, nicely showing the Scottish Highlands. The library has scanned many of these maps and made them available to the public domain.

Premade maps from images or shaded elevation models are also available. The CIA Factbook (http://www.cia.gov/ciapublications/factbook) has small political maps for each country. Other reference maps that show more physical data (e.g., bathymetry and elevation) or even photographic examples of the earth can be found. The U.S. National Geophysical Data Center (NGDC) includes some beautiful premade gallery images of their more detailed source data; look for them at http://www.ngdc.noaa.gov/seg/topo/globegal.shtml.

The Internet contains a wealth of geographic information for your projects. It is a natural place to begin your quest for mapping data. Some government agencies make their mapping data freely available on the Internet. Certain organizations have even made it their mission to make mapping data available for others for free. Other groups have created catalogs of mapping data you can search.

Plenty of Internet map data sources are available for the United States. North American data is also widely accessible, with Canada having some excellent products. Global data is more of a challenge. International organizations such as the United Nations or even American-based organizations that observe global events, such as the National Oceanic and Atmospheric Administration (NOAA), are some of the better sources for global data.

There are a variety of data repositories on the Internet to choose from, and they each have a certain target scale of application that can’t be ignored. For example, a satellite image can show pictures of where you live. Figure 5-6, for example, shows the different colors of surfaces such as roads, fields, and waterways, but only to a certain level of detail. If you hope to use it for planning a walk to the corner store, you will be sorely disappointed. However, if you want to see how your city is laid out, you will probably be satisfied. Figure 5-7 shows a closer look at the same image as Figure 5-6. The maximum amount of detail has been reached, and the image looks bad. This is an attempt to use the image beyond its intended scale of application.

There are multiple ways to hunt for good data. You can announce your search to email mailing lists or review web sites that summarize free data sources. Local mapping companies and government agencies are also a good place to start. Many states, provinces, and municipalities have their own GIS and mapping offices. Your search can also include local consulting companies, industries, or nonprofit organizations related to environmental or natural resource management and use. Just ask to speak to someone in the mapping or GIS department. Most people in these organizations

Figure 5-6. A Landsat satellite image showing the region around Toronto

Figure 5-7. A closer (though fuzzy) look at the Landsat image used in Figure 5-6

are willing to discuss what data they can share. If they can’t share the data, they can at least point you to the original source for you to seek out on your own. Table 5-1 lists a few web sites and email lists that include free map data or people who can help you find data.

There are some proactive ways to get access to data. If your project needs a certain type of data and you can help meet the objectives of the custodian as well, it might be a good idea to enter into a project together. One group puts time and effort into the project, and the other contributes data. A long-term data exchange agreement may also play a mutually beneficial role. The idea is that one party provides mapping data, and the other gets open access to it. In return, the user provides their updates of the data back to the custodian. Of course, each agreement should be negotiated to include only certain kinds of updates or sharing of only certain pieces of data (such as nonconfidential information).

This data sharing/update model is increasingly common, but at the same time many groups are making their information freely available for open use. It is important to get a broad feel for others who are also interested in, or may already have, the data you are looking for. Data can be shared without having to copy source data by using OGC web specifications. For example, the satellite image in Figure 5-6 is from a free web service and requested by a mapping application. See Chapter 12 for more about the OGC and web services.

Finding and getting access to data aren’t the only problems. Some data may be unusable or inappropriate for the task at hand. This goes beyond matters of scale and resolution, referring more to accuracy and supplementary attributes. One example is a forestry initiative of the government of British Columbia (Canada) to map certain types of pest-infected trees. Traditionally this has been mapped using a fixed-wing aircraft carrying a reconnaissance mapper who spots the trees and then draws their location on a paper map. At the office, the paper maps are digitized onto a base map in the computer. While these maps are useful for general landscape-level analysis, you would not want to depend on the map to lead you to a particular tree in the middle of a dense forest. Wise use and understanding of the appropriate application of your data will help you have realistic expectations when starting your mapping project.

The Internet isn’t the only source of mapping data. Chapter 9 discusses how to create some of your own data with map-editing tools or using coordinates taken from a GPS receiver.

The MapServer demo data includes a variety of vector spatial files; therefore you will use the ogrinfo tool to gather information about the files. At the command prompt, change into the workshop folder, and run the ogrinfo command to have it list the datasets that are in the data folder. The output from the command will look like Example 6-1.

> ogrinfo data
INFO: Open of 'data'
using driver 'ESRI Shapefile' successful.
1: twprgpy3 (Polygon)
2: rmprdln3 (Line String)
3: lakespy2 (Polygon)
4: stprkpy3 (Polygon)
5: ctyrdln3 (Line String)
6: dlgstln2 (Line String)
7: mcd90py2 (Polygon)
8: twprdln3 (Line String)
9: plsscpy3 (Polygon)
10: mcdrdln3 (Line String)
11: majrdln3 (Line String)
12: drgidx (Polygon)
13: airports (Point)
14: ctybdpy2 (Polygon)

This shows that there are 14 layers in the data folder (the order of the listing may vary on other systems). You can also see that the folder contains ESRI shapefile format files. Each shapefile is a layer in this listing. If you look at the files located in the data folder, you will see that there are way more than 14 files. This is because a shapefile consists of more than one file: one holds spatial data, another holds tabular data, etc.

A summary of more information for each layer can be seen by adding the name of the layer to the ogrinfo command and a -summary parameter, as shown in Example 6-2.

> ogrinfo -summary data airports
INFO: Open of 'data'
using driver 'ESRI Shapefile' successful.

Layer name: airports
Geometry: Point
Feature Count: 12
Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)
Layer SRS WKT:
(unknown)
NAME: String (64.0)
LAT: Real (12.4)
LON: Real (12.4)
ELEVATION: Real (12.4)
QUADNAME: String (32.0)

This example shows information about the airports layer.

    Geometry: Point

The geographic features in this file are points. In the next example, you will see that each airport feature has one pair of location coordinates.

    Feature Count: 12
    Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)

There are 12 airport features in this layer, and they fall within the range of coordinates shown in the Extent line. The coordinates are measured in meters and are projected into the Universal Transverse Mercator (UTM) projection.

    Layer SRS WKT:
    (unknown)

This explains what map projection the data is in. SRS stands for spatial reference system and WKT for well-known text format. Without getting into too much detail, these are terms popularized or created by the OGC. The SRS gives information about projections, datums, units of measure in the data, etc. WKT is a method for describing those statistics in a text-based, human-readable format (as opposed to a binary format). Refer to Appendix A for more information about map projections, SRS, and the EPSG numbering system. See Chapter 12 for more information on the OGC and its role in setting standards.

The previous example also says unknown because the creator of the data didn’t explicitly include projection information within the file. This isn’t very helpful if you don’t know where the data is from. However, those familiar with the data might guess that it is in UTM coordinates.

    NAME: String (64.0)
    LAT: Real (12.4)
    LON: Real (12.4)
    ELEVATION: Real (12.4)
    QUADNAME: String (32.0)

These five lines tell you about the other types of nonspatial information that accompany each geographic feature. A feature, in this case, is a coordinate for an airport. These different pieces of information are often referred to as attributes, properties, columns, or fields. Each attribute has a name identifier and can hold a certain type of information. In the previous example, the text before the colon is the name of the attribute. Don’t be confused by the fact that there is also an attribute called NAME in this file. The first line describes an attribute called NAME. The word after the colon tells you what kind of data can be held in that attribute—either String (text characters) or Real (numbers). The numbers in the parentheses tell more specifically how much of each kind of data can be stored in the attribute. For example NAME: String (64.0) means that the attribute called NAME can hold up to 64 letters or numbers. Likewise ELEVATION: Real (12.4) means that the ELEVATION attribute can hold up to only 12-digit numbers with a maximum of 4 decimal places.

You may be wondering why this is important to review. Some of the most common errors in using map data can be traced back to a poor understanding of the data. This is why reviewing data with tools such as ogrinfo can be very helpful before launching into mapmaking. If you don’t understand what kind of attributes you have at your disposal, you may not use the data to its fullest potential or you may push its use beyond appropriate bounds. Understanding your data in this depth will prevent future mistakes during the mapping process or during any analysis you may undertake. If your analysis relies on a certain kind of numbers with a level of precision or expected length of text, you need to make sure that the data you are analyzing actually holds these kinds of values, or you will get misleading results. Having this knowledge early in the process will help you have a more enjoyable experience along the way.

Summary information tells only part of the story. The same tools can be used to provide detailed information about the geographic data and its attributes. To get details, instead of summary information, you can use ogrinfo with a dataset and layer name like that in Example 6-3, but don’t include the -summary parameter.

> ogrinfo data airports
INFO: Open of 'data'
using driver 'ESRI Shapefile' successful.

Layer name: airports
Geometry: Point
Feature Count: 12
Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)
Layer SRS WKT:
(unknown)
NAME: String (64.0)
LAT: Real (12.4)
LON: Real (12.4)
ELEVATION: Real (12.4)
QUADNAME: String (32.0)
OGRFeature(airports):0
  NAME (String) = Bigfork Municipal Airport
  LAT (Real) =      47.7789
  LON (Real) =     -93.6500
  ELEVATION (Real) =    1343.0000
  QUADNAME (String) = Effie
  POINT (451306 5291930)

OGRFeature(airports):1
  NAME (String) = Bolduc Seaplane Base
  LAT (Real) =      47.5975
  LON (Real) =     -93.4106
  ELEVATION (Real) =    1325.0000
  QUADNAME (String) = Balsam Lake
  POINT (469137 5271647)

This view of the airport details tells you what value each airport has for each attribute. As you can see, the summary information is still included at the top of the listing, but then there are small sections for each feature. In this case there are seven lines, or attributes, for each airport. For example, you can see the name of the airport, but you can also see the UTM coordinate shown beside the POINT attribute.

Only two features are shown in this example, the first starting with OGRFeature(airports):0. The full example goes all the way to OGRFeature(airports):11, including all 12 airports. The rest of the points aren’t shown in this example, just to keep it simple.

ogrinfo is a great tool for digging even deeper into your data. There are more options that can be used, including a database query-like ability to select features and the ability to list only features that fall within a certain area. Running man ogrinfo (if your operating system supports manpages) shows the full usage for each parameter. Otherwise, the details are available on the OGR web site at http://www.gdal.org/ogr/ogr_utilities.html. You can also run the ogrinfo command with the --help parameter (ogrinfo --help) to get a summary of options. Example 6-4 shows some examples of how they can be used with your airport data.

> ogrinfo data airports 
                  
                     -
                  
                  where "name='Bolduc Seaplane Base'"
INFO: Open of 'data'
using driver 'ESRI Shapefile' successful.

Layer name: airports
Geometry: Point
Feature Count: 1
Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)
Layer SRS WKT:
(unknown)
NAME: String (64.0)
LAT: Real (12.4)
LON: Real (12.4)
ELEVATION: Real (12.4)
QUADNAME: String (32.0)
OGRFeature(airports):1
  NAME (String) = Bolduc Seaplane Base
  LAT (Real) =      47.5975
  LON (Real) =     -93.4106
  ELEVATION (Real) =    1325.0000
  QUADNAME (String) = Balsam Lake
  POINT (469137 5271647)

This example lists only those airports that have the name Bolduc Seaplane Base. As you can imagine, there is only one. Therefore, the summary information about this layer and one set of attribute values are listed for the single airport that meets this criteria in Example 6-5. The -sql option can also specify what attributes to list in the ogrinfo output.

> ogrinfo data airports -sql "select name from airports where quadname='Side Lake'"
INFO: Open of 'data'
using driver 'ESRI Shapefile' successful.
layer names ignored in combination with -sql.

Layer name: airports
Geometry: Point
Feature Count: 2
Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)
Layer SRS WKT:
(unknown)
name: String (64.0)
OGRFeature(airports):4
  name (String) = Christenson Point Seaplane Base
  POINT (495913 5279532)

OGRFeature(airports):10
  name (String) = Sixberrys Landing Seaplane Base
  POINT (496393 5280458)

The SQL parameter is set to show only one attribute, NAME, rather than all seven attributes for each feature. It still shows the coordinates by default, but none of the other information is displayed. This is combined with a query to show only those features that meet a certain QUADNAME requirement.

Example 6-6 shows how ogrinfo can use some spatial logic to find features that are within a certain area.

> ogrinfo data airports -spat 451869 5225734 465726 5242150
Layer name: airports
Geometry: Point
Feature Count: 2
Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)
Layer SRS WKT:
(unknown)
NAME: String (64.0)
LAT: Real (12.4)
LON: Real (12.4)
ELEVATION: Real (12.4)
QUADNAME: String (32.0)
OGRFeature(airports):7
  NAME (String) = Grand Rapids-Itasca County/Gordon Newstrom Field
  LAT (Real) =      47.2108
  LON (Real) =     -93.5097
  ELEVATION (Real) =    1355.0000
  QUADNAME (String) = Grand Rapids
  POINT (461401 5228719)

OGRFeature(airports):8
  NAME (String) = Richter Ranch Airport
  LAT (Real) =      47.3161
  LON (Real) =     -93.5914
  ELEVATION (Real) =    1340.0000
  QUADNAME (String) = Cohasset East
  POINT (455305 5240463)

The ability to show only features based on where they are located is quite powerful. You do so using the -spat parameter followed by two pairs of coordinates. The first pair of coordinates 451869 5225734 represent the southwest corner of the area you are interested in querying. The second pair of coordinates 465726 5242150 represents the northeast corner of the area you are interested in, creating a rectangular area.

ogrinfo then shows only those features that are located within the area you define. In this case, because the data is projected into the UTM coordinate system, the coordinates must be specified in UTM format in the -spat parameter. Because the data is stored in UTM coordinates, you can’t specify the coordinates using decimal degrees (°) for instance. The coordinates must always be specified using the same units and projection as the source data, or you will get inaccurate results.

Example 6-7 is similar to a previous example showing complex query syntax using the -sql parameter, but it differs in one respect.

> ogrinfo data airports 
                  
                     -
                  
                  sql "select * from airports where elevation > 1350 and quadname
like '%Lake'" -summary
INFO: Open of 'data'
using driver 'ESRI Shapefile' successful.
layer names ignored in combination with -sql.

Layer name: airports
Geometry: Point
Feature Count: 5
Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)

If you add the -summary option, it doesn’t list all the attributes of the features, but shows only a summary of the information. In this case, it summarizes only information that met the criteria of the -sql parameter. This is very handy if you just want to know how many features meet certain criteria or fall within a certain area but don’t care to see all the details.

You can download a sample satellite image from http://geogratis.cgdi.gc.ca/download/RADARSATRADARSAT/mosaic/canada_mosaic_lcc_1000m.zip. If you unzip the file, you create a file called canada_mosaic_lcc_1000m.tif. This is a file containing an image from the RADARSAT satellite. For more information about RADARSAT, see http://www.ccrs.nrcan.gc.ca/ccrs/data/satsens/radarsat/rsatndx_e.html.

To better understand what kind of data this is, use the gdalinfo command. Like the ogrinfo command, this tool lists certain pieces of information about a file, but the GDAL tools can interact with raster/image data. The output from gdalinfo is also very similar to ogrinfo as you can see in Example 6-8. You should change to the same folder as the image before running the gdalinfo command.

> gdalinfo canada_mosaic_lcc_1000m.tif
Driver: GTiff/GeoTIFF
Size is 5700, 4800
Coordinate System is:
PROJCS["LCC         E008",
    GEOGCS["NAD83",
        DATUM["North_American_Datum_1983",
            SPHEROID["GRS 1980",6378137,298.2572221010042,
                AUTHORITY["EPSG","7019"]],
            AUTHORITY["EPSG","6269"]],
        PRIMEM["Greenwich",0],
        UNIT["degree",0.0174532925199433],
        AUTHORITY["EPSG","4269"]],
    PROJECTION["Lambert_Conformal_Conic_2SP"],
    PARAMETER["standard_parallel_1",49],
    PARAMETER["standard_parallel_2",77],
    PARAMETER["latitude_of_origin",0],
    PARAMETER["central_meridian",-95],
    PARAMETER["false_easting",0],
    PARAMETER["false_northing",0],
    UNIT["metre",1,
        AUTHORITY["EPSG","9001"]]]
Origin = (-2600000.000000,10500000.000000)
Pixel Size = (1000.00000000,-1000.00000000)
Corner Coordinates:
Upper Left  (-2600000.000,10500000.000) (177d17'32.31"W, 66d54'22.82"N)
Lower Left  (-2600000.000, 5700000.000) (122d54'49.00"W, 36d12'53.87"N)
Upper Right ( 3100000.000,10500000.000) (  9d58'39.57"W, 62d25'50.45"N)
Lower Right ( 3100000.000, 5700000.000) ( 62d32'49.65"W, 34d18'5.61"N)
Center      (  250000.000, 8100000.000) ( 89d56'43.00"W, 62d46'47.18"N)
Band 1 Block=5700x1 Type=Byte, ColorInterp=Gray

There are five main sections in this report. Unlike ogrinfo, there aren’t a lot of different options, and attributes are very simplistic. The first line tells you what image format the file is.

    Driver: GTiff/GeoTIFF

In this case, it tells you the file is a GeoTIFF image. TIFF images are used in general computerized photographic applications such as digital photography and printing. However, GeoTIFF implies that the image has some geographic information encoded into it. gdalinfo can be run with a —formats option, which lists all the raster formats it can read and possibly write. The version of GDAL included with FWTools has support for more than three dozen formats! These include several proprietary software vendor formats and many related to specific types of satellite data.

The next line shows the size of the image:

    Size is 5700, 4800.

An image size is characterized by the number of data rows and columns. An image is a type of raster data. A raster is made up of numerous rows of adjoining squares called cells or pixels. Rows usually consist of cells that are laid out east to west, whereas columns of cells are north to south. This isn’t always the case but is a general rule of thumb. This image has 5,700 columns and 4,800 rows. The first value in the size statement is usually the width, therefore the number of columns of cells. Row and column numbering usually begins at the upper-left corner of the image and increases toward the lower-right corner. Therefore, cell 0,0 is the upper left, and cell 5700, 4800 is the lower right.

Images can be projected into various coordinate reference systems (see Appendix A for more about map projections):

    Coordinate System is:
    PROJCS["LCC         E008",
        GEOGCS["NAD83",
            DATUM["North_American_Datum_1983",
               SPHEROID["GRS 1980",6378137,298.2572221010042,
                    AUTHORITY["EPSG","7019"]],
                AUTHORITY["EPSG","6269"]],
            PRIMEM["Greenwich",0],
            UNIT["degree",0.0174532925199433],
            AUTHORITY["EPSG","4269"]],
        PROJECTION["Lambert_Conformal_Conic_2SP"],
        PARAMETER["standard_parallel_1",49],
        PARAMETER["standard_parallel_2",77],
        PARAMETER["latitude_of_origin",0],
        PARAMETER["central_meridian",-95],
        PARAMETER["false_easting",0],
        PARAMETER["false_northing",0],
        UNIT["metre",1,
            AUTHORITY["EPSG","9001"]]]

These assign a cell to a global geographic coordinate. Often these coordinates need to be adjusted to improve the appearance of particular applications or to line up with other pieces of data. This image is in a projection called Lambert Conformal Conic (LCC). You will need to know what projection data is in if you want to use it with other data. If the projections between data don’t match, you may need to reproject them into a common projection.

The latitude of origin and central meridian settings are given in geographic coordinates using degree (°) units. They describe where the coordinate 0,0 starts. Latitude 0° represents the equator. In map projections central meridians are represented by a longitude value. Longitude -95°, or 95° West, runs through central Canada.

        PARAMETER["latitude_of_origin",0],
        PARAMETER["central_meridian",-95],

Note that in the earlier projection, the unit setting is metre. When you look at Pixel Size in a moment, you will see a number but no unit. It is in this unit (meters) that the pixel sizes are measured.

Cells are given row and column numbers, but are also given geographic coordinate values. The origin setting tells what the geographic coordinate is of the cell at row 0, column 0. Here, the value of origin is in the same projection and units as the projection for the whole image. The east/west coordinate -2,600,000 is 2,600,000 meters west of the central meridian. The north/south coordinate is 10,500,000 meters north of the equator.

    Origin = (-2600000.000000,10500000.000000)
    Pixel Size = (1000.00000000,-1000.00000000)

Cells are also called pixels and each of them has a defined size. In this example the pixels have a size of 1000 × 1000: the -1000 is just a notation; the negative aspect of it can be ignored for now. In most cases, your pixels will be square, though it is possible to have rasters with nonsquare pixels. The unit of these pixel sizes is in meters, as defined earlier in the projection for the image. That means each pixel is 1,000 meters wide and 1,000 meters high.

Much like the previous origin settings, corner coordinates tell you the geographic coordinate the corner pixels and center of the image have:

    Corner Coordinates:
    Upper Left  (-2600000.000,10500000.000) (177d17'32.31"W, 66d54'22.82"N)
    Lower Left  (-2600000.000, 5700000.000) (122d54'49.00"W, 36d12'53.87"N)
    Upper Right ( 3100000.000,10500000.000) (  9d58'39.57"W, 62d25'50.45"N)
    Lower Right ( 3100000.000, 5700000.000) ( 62d32'49.65"W, 34d18'5.61"N)
    Center      (  250000.000, 8100000.000) ( 89d56'43.00"W, 62d46'47.18"N)

Notice that the coordinates are first given in their projected values, but also given in their unprojected geographic coordinates, longitude, and latitude. Knowing this will help you determine where on the earth your image falls. If you thought this image was in Greece, you’d be wrong. The geographic coordinates clearly put it in the western hemisphere: 177d17'32.31"W is 177 degrees, 17 minutes, 32.31 seconds west of the prime meridian.

Images are made up of different bands of data. In some cases, you can have a dozen different bands, where each band stores values about a specific wavelength of light that a sensor photographed. In this case, there is only one band Band 1. The ColorInterp=Gray setting tells you that it is a grayscale image, and Type=Byte tells you that it is an 8-bit (8 bits=1 byte) image. Because 8 bits of data can hold 256 different values, this image could have 256 different shades of gray.

    Band 1 Block=5700x1 Type=Byte, ColorInterp=Gray

If you add the -mm parameter to the gdalinfo command, as shown in Example 6-9, you get a summary of the minimum and maximum color values for the bands in the image.

> gdalinfo canada_mosaic_lcc_1000m.tif 
                  
                     -
                  
                  mm
...
Band 1 Block=5700x1 Type=Byte, ColorInterp=Gray
    Computed Min/Max=0.000,255.000

This shows that there are 256 different values used in this image (with 0 being the minimum value).

These text-processing tools are sometimes packaged together, but are usually separate projects in and of themselves. Most of them were formed as part of the GNU/Free Software Foundation and are registered with the GNU free software directory at http://www.gnu.org/directory/. The targets of GNU software are free operating systems, which can cause some problems if you are dependent on an operating system such as Microsoft Windows. Some operating system don’t normally include these tools, but they can often be acquired from Internet sources or even purchased.

A very comprehensive set of these tools for Windows is available at http://unxutils.sourceforge.net/. You can download a ZIP file that contains all the programs. If you unzip the file and store the files in a common Windows folder, such as C:\Windows\System32 or C:\winnt\System32, they will be available to run from the command prompt.

If the tool or command you want isn’t included, the next place to look is the GNU directory (http://gnu.org). This is where to start if you are looking for a particular program. A home page for the program and more information about it are available. Look for the download page for the program first to see if there is a binary version of the tool available for your operating system. If not, you may need to download the source code and compile the utility yourself.

Another resource to search is the Freshmeat web site at http://freshmeat.net. This site helps users find programs or projects and also provides daily news reports of what is being updated. Many projects reported in Freshmeat are hosted on the Sourceforge web site at http://sourceforge.net.

One source that is commonly used on Windows is the Cygwin environment, which can be found at http://www.cygwin.com. The web site describes Cygwin as “a Linux-like environment for Windows.” Cygwin can be downloaded and installed on most modern Windows platforms and provides many of the text-processing tools mentioned previously. Furthermore, it also provides access to source-code compilers such as GCC.

Mac OS X includes many of the same kinds of text-processing tools. They may not be exactly the same as the GNU programs mentioned here, but similar alternatives are available in the Darwin core underlying OS X. For ones that aren’t available natively in OS X, they can be compiled from the GNU source code or acquired through your favorite package manager such as Fink.

The standard output of ogrinfo reports are a set of lines displaying information about each feature. As earlier, this output is quite verbose, showing some summary information first, then sections for each feature. In the case of the airport data, each airport has its own section of seven lines. Example 6-10 shows a couple of these sections covering 2 of the 12 features (the rest were removed to reduce unnecessary length).

> ogrinfo data airports
INFO: Open of 'data'
using driver 'ESRI Shapefile' successful.

Layer name: airports
Geometry: Point
Feature Count: 12
Extent: (434634.000000, 5228719.000000) - (496393.000000, 5291930.000000)
Layer SRS WKT:
(unknown)
NAME: String (64.0)
LAT: Real (12.4)
LON: Real (12.4)
ELEVATION: Real (12.4)
QUADNAME: String (32.0)
OGRFeature(airports):0
  NAME (String) = Bigfork Municipal Airport
  LAT (Real) =      47.7789
  LON (Real) =     -93.6500
  ELEVATION (Real) =    1343.0000
  QUADNAME (String) = Effie
  POINT (451306 5291930)

OGRFeature(airports):1
  NAME (String) = Bolduc Seaplane Base
  LAT (Real) =      47.5975
  LON (Real) =     -93.4106
  ELEVATION (Real) =    1325.0000
  QUADNAME (String) = Balsam Lake
  POINT (469137 5271647)

But what if you don’t really care about a lot of the information that is displayed? You can use the ogrinfo options -sql and -where, but they still show you summary information and don’t necessarily format it the way you want. Various other operating system programs can help you reformat the output of ogrinfo. Examples of these commands follow, starting with the grep command.

The grep commands can be used to show only certain lines being printed to your screen; for example, to find a certain line in a text file. In this case, we are piping the text stream that ogrinfo prints into the grep command and analyzing it. The results are that any line starting with two spaces and the word NAME are printed; the rest of the lines won’t show. Note that the pipe symbol | is the vertical bar, usually the uppercase of the key \ on your keyboard. This tells the command-line interpreter to send all the results of the ogrinfo command to the grep command for further processing. You then add an option at the end of the command telling it which lines you want to see in your results, as shown in Example 6-11.

> ogrinfo data airports | grep '  NAME'
  NAME (String) = Bigfork Municipal Airport
  NAME (String) = Bolduc Seaplane Base
  NAME (String) = Bowstring Municipal Airport
  NAME (String) = Burns Lake Seaplane Base
  NAME (String) = Christenson Point Seaplane Base
  NAME (String) = Deer River Municipal Airport
  NAME (String) = Gospel Ranch Airport
  NAME (String) = Grand Rapids-Itasca County/Gordon Newstrom Field
  NAME (String) = Richter Ranch Airport
  NAME (String) = Shaughnessy Seaplane Base
  NAME (String) = Sixberrys Landing Seaplane Base
  NAME (String) = Snells Seaplane Base

If you want some other piece of information to show instead, simply change 'NAME' (including two preceding spaces) to 'abc', which is the text or numbers you are interested in. For example, grep 'LAT' shows only the LAT lines. Notice that using 'NAME' without the preceding spaces as in NAME lists the QUADNAME attributes as well.

Now that you have a list of attribute values in your airports file, you can start to use other commands. The wc command can perform a variety of analysis functions against a list of text. The name wc stands for word count. It can count the number of characters, words, or lines in a list of text (or a file) and report them back to you. Output from grep or ogrinfo can be redirected to wc to be further analyzed.

In this case we use wc to count the number of lines (using the -l line count option). Combined with the grep command, as shown in the following example, this shows the number of airports that grep would have printed to your screen.

    > ogrinfo data airports | grep '  NAME' | wc -l
               
    12

Another very powerful tool is the text stream-editing tool called sed. sed allows a user to filter a list of text (in this case the listing from ogrinfo) and perform text substitutions (search and replace), find or delete certain text, etc. If you are already familiar with regular expression syntax, you will find yourself right at home using sed, because it uses regex syntax to define its filters.

In this example, you take the full output of the ogrinfo command again and search entries that contain the words Seaplane Base. What makes this different than the grep example is the inclusion of the trailing dollar $ sign at the end of the phrase. This symbol represents the end of the line. This example, therefore, prints only airport names that have Seaplane Base at the end of the name; it doesn’t print any airport without Seaplane Base in its name and also excludes airports that have the phrase in anything but the last part of the name. As in Example 6-12, the airport named Joes Seaplane Base and Cafe wouldn’t be returned.

> ogrinfo data airports | sed -n '/Seaplane Base$/p'
  NAME (String) = Bolduc Seaplane Base
  NAME (String) = Burns Lake Seaplane Base
  NAME (String) = Christenson Point Seaplane Base
  NAME (String) = Shaughnessy Seaplane Base
  NAME (String) = Sixberrys Landing Seaplane Base
  NAME (String) = Snells Seaplane Base

    | awk -F= '{print $2}'.

The display of the previous example may be fine only for purposes of quick data review. When some type of report or cut/paste function needs to take place, it is often best to reformat the results. Example 6-13 uses grep to filter out all the lines that aren’t airport names, as in the previous example. It then uses two sed filters to remove the attribute name information, and then to remove any airports that start with B. As you can see, the example runs ogrinfo results through three filters and produces an easy-to-read list of all the airports meeting your criteria.

> ogrinfo data airports | grep '  NAME' | sed 's/  NAME (String) = //' | sed '/^B/d'
Christenson Point Seaplane Base
Deer River Municipal Airport
Gospel Ranch Airport
Grand Rapids-Itasca County/Gordon Newstrom Field
Richter Ranch Airport
Shaughnessy Seaplane Base
Sixberrys Landing Seaplane Base
Snells Seaplane Base

The usage of the last sed filter looks somewhat obscure, because it uses the caret ^ symbol. This denotes the start of a line, so, in this case, it looks for any line that starts with B. It doesn’t concern itself with the rest of the line at all. The final /d means “delete lines that meet the ^B criteria.”

Example 6-14 uses a similar approach but doesn’t require the text to be at the beginning of the line. Any airport with the word Municipal in the name is deleted from the final list.

> ogrinfo data airports | grep '  NAME' | sed 's/  NAME (String) = //' | sed '/Municipal/d'
Bolduc Seaplane Base
Burns Lake Seaplane Base
Christenson Point Seaplane Base
Gospel Ranch Airport
Grand Rapids-Itasca County/Gordon Newstrom Field
Richter Ranch Airport
Shaughnessy Seaplane Base
Sixberrys Landing Seaplane Base
Snells Seaplane Base

sed has many different options and can be very sophisticated, especially when combining sed filters. Example 6-15 shows how you can string numerous commands together and do a few filters all at once.

> ogrinfo data airports | sed -n '/^  NAME/,/^  ELEVATION/p' | sed '/LAT/d' | sed '/LON/d'
| sed 's/..................//'
Bigfork Municipal Airport
 =    1343.0000
Bolduc Seaplane Base
 =    1325.0000
Bowstring Municipal Airport
 =    1372.0000
Burns Lake Seaplane Base
 =    1357.0000
Christenson Point Seaplane Base
 =    1372.0000
Deer River Municipal Airport
 =    1311.0000
Gospel Ranch Airport
 =    1394.0000
Grand Rapids-Itasca County/Gordon Newstrom Field
 =    1355.0000
Richter Ranch Airport
 =    1340.0000
Shaughnessy Seaplane Base
 =    1300.0000
Sixberrys Landing Seaplane Base
 =    1372.0000
Snells Seaplane Base
 =    1351.0000

This example uses sed to do only four filters on the list. The first is perhaps the most complex. It has two options separated by a comma:

               
    '/^  NAME/,/^  ELEVATION/p'

You can see the use of the caret again, which always denotes that the filter is looking at the beginning of the line(s). In this case it looks for the lines starting with NAME (including a couple spaces that ogrinfo throws in by default), but then there is also ELEVATION specified. The comma tells sed to include a range of lines—those that fall between the line starting with NAME and the next line starting with ELEVATION. NAME is called the start; ELEVATION is called the end. This way you can see a few lines together rather than selecting one line at a time. This is helpful because it shows the lines in the context of surrounding information and is important for text streams that are listed like ogrinfo output, which groups together attributes of features onto multiple lines.

               
    sed '/LAT/d' | sed '/LON/d'

The second and third filters are simple delete filters that remove any LAT and LON lines. Notice that these lines originally fell between NAME and ELEVATION in the list, so the filter is simply removing more and more lines building on the previous filter.

               
    sed 's/..................//'

The fourth filter isn’t a joke, nor did I fall asleep on the keyboard. It is a substitute or search/replace filter, which is signified by the preceding s/. Each period represents a character that sed will delete from the beginning of each line.

The end result of these four filters is a much more readable list of all the airports in the shape file and their respective elevations.

Another very handy command-line tool is sort. sort does just what the name promises: it puts text or numbers in a certain order. It sorts in ascending order by default, from smallest to highest or from lowest letter (closest to “a”) to highest letter (closest to “z”).

In Example 6-16 all the lines are filtered out except those including ELEVATION. Unwanted letters are then stripped from the beginning of each line. The output is then filtered through sort which reorders the output in ascending order.

> ogrinfo data airports | grep 'ELEVATION' | sed -n 's/  ELEVATION (Real) =   //p' | sort
 1300.0000
 1311.0000
 1325.0000
 1340.0000
 1343.0000
 1351.0000
 1355.0000
 1357.0000
 1372.0000
 1372.0000
 1372.0000
 1394.0000

The output from sort includes some duplicate or repeated values. Obviously some airports rest at the same elevation: 1,372 feet. If this output is going to be used in a report, it may not make sense to include repeated values, especially when it is just a list of numbers.

The uniq command can help make the results more presentable. In Example 6-17, the results of grep, sed, and sort were passed to the uniq command. uniq processes the list and removes duplicate lines from the list. You’ll notice only one occurrence of 1372 now.

> ogrinfo data airports | grep 'ELEVATION' | sed -n 's/  ELEVATION (Real) =   //p' | sort
| uniq
 1300.0000
 1311.0000
 1325.0000
 1340.0000
 1343.0000
 1351.0000
 1355.0000
 1357.0000
 1372.0000
 1394.0000

uniq has some other options. As seen in Example 6-18, -c tells uniq to also print the number of times each line occurs. Notice that only elevation 1372 occurred more than once.

> ogrinfo data airports | grep 'ELEVATION' | sed -n 's/  ELEVATION (Real) =   //p' | sort
| uniq -c
      1  1300.0000
      1  1311.0000
      1  1325.0000
      1  1340.0000
      1  1343.0000
      1  1351.0000
      1  1355.0000
      1  1357.0000
      3  1372.0000
      1  1394.0000

The -d option for uniq shows only duplicate records. You can combine multiple options to help give you exactly what you are looking for. As shown in Example 6-19, if you are only interested in airports with the same elevation, and you want to know how many there are, you would only have to add d to the options for uniq.

> ogrinfo data airports | grep 'ELEVATION' | sed -n 's/  ELEVATION (Real) =   //p' | sort
| uniq -cd

To add line numbers to you output, pass your text stream through the nl command. Example 6-20 shows what this looks like.

> ogrinfo data airports | grep 'ELEVATION' | sed -n 's/  ELEVATION (Real) =   //p' | sort
| uniq -c | nl
     1        1  1300.0000
     2        1  1311.0000
     3        1  1325.0000
     4        1  1340.0000
     5        1  1343.0000
     6        1  1351.0000
     7        1  1355.0000
     8        1  1357.0000
     9        3  1372.0000
    10        1  1394.0000

Keep in mind that uniq checks each line only against surrounding lines, therefore the sort beforehand helps make sure that all duplicates are side by side. If they aren’t, there is no guarantee that uniq will produce the expected results. Other text-processing commands may better suit you if you are unable to use sort. For example, tsort , referenced in the next section may do what you want.

Most Unix implementations, including Linux, have many more processing commands available. The list below shows a summary of the text-processing commands you may find useful. If you are wondering how to use some of them, you can usually add —help after the command name to get a list of options. Or you may also be able to read the manual for the command by typing man < command name >.

I highly recommend the Linux Documentation Project site to get a comprehensive list and examples of these text-processing commands. This is helpful for those other platforms as well because these tools often exist for other platforms. The site address is http://www.tldp.org/—search for the “Text Processing” HOWTO document. Other HOWTO documents and tutorials go into more depth for specific text processing programs. Check out the O’Reilly book Unix Power Tools for more Unix help.

One example of a text-based format is Geography Markup Language (GML). It uses a text syntax to encode coordinates into a text file. GML can then be read or manually edited without needing a special piece of software or at least nothing more than a common text editor. Creating GML from scratch isn’t very pleasant. Fortunately, another OGR utility exists that can convert OGR-supported data formats into and out of other formats, including GML.

GML has three different versions: GML1, GML2, and GML3. There are many sub-versions as well. The differences between versions can be a problem because certain features may not be directly transferable to another. The tools introduced in this chapter use ogr2ogr, which outputs to GML2 format.

GML was designed to be suitable for data interoperability, allowing the exchange of spatial data using a common format. This has opened up the possibilities for various web services that operate using different software yet can communicate using this standard format. See Chapter 12 to learn more about this example.

GML’s downside is its size. Text files can’t hold as much raw computer data as a binary file, so GML files tend to be much larger than other data formats. It isn’t ideal to store all your data as GML, but it’s perfect for sending data to someone who may not be able to support other formats. Because GML is text, it compresses very well using tools such as gzip and WinZip.

Extensible Markup Language (XML) is a popular standard for general data exchange, especially through the Internet. XML-based datafiles (such as GML) typically have an associated schema document. Schema documents aren’t discussed, but you should know that they do exist. They describe how the data is structured in the XML data file—what attributes they have, what version of XML is being used, what type of information is in an attribute, etc. Schema documents have a filename suffix of .xsd. Therefore, a GML file called airports.gml also has an associated airports.xsd file describing the contents of airports.gml.

Example 7-1 shows how to convert the airports data from shapefile format to GML using the ogr2ogr conversion utility.

> ogr2ogr -f "GML" airports.gml data/airports.shp airports
> more airports.gml
<?xml version="1.0" encoding="utf-8" ?>
<ogr:FeatureCollection
     xmlns:xsi="http://www.w3c.org/2001/XMLSchema-instance"
     xsi:schemaLocation=". airports.xsd"
     xmlns:ogr="http://ogr.maptools.org/"
     xmlns:gml="http://www.opengis.net/gml">
  <gml:boundedBy>
    <gml:Box>
      <gml:coord><gml:X>434634</gml:X><gml:Y>5228719</gml:Y></gml:coord>
      <gml:coord><gml:X>496393</gml:X><gml:Y>5291930</gml:Y></gml:coord>
    </gml:Box>
  </gml:boundedBy>
  <gml:featureMember>
    <airports fid="0">
      <NAME>Bigfork Municipal Airport</NAME>
      <LAT>     47.7789</LAT>
      <LON>    -93.6500</LON>
      <ELEVATION>   1343.0000</ELEVATION>
      <QUADNAME>Effie</QUADNAME>
      <ogr:geometryProperty><gml:Point><gml:coordinates>451306,5291930</gml:coordinates>
               </gml:Point></ogr:geometryProperty>
    </airports>
  </gml:featureMember>
  <gml:featureMember>
    <airports fid="1">
      <NAME>Bolduc Seaplane Base</NAME>
      <LAT>     47.5975</LAT>
      <LON>    -93.4106</LON>
      <ELEVATION>   1325.0000</ELEVATION>
      <QUADNAME>Balsam Lake</QUADNAME>
      <ogr:geometryProperty><gml:Point><gml:coordinates>469137,5271647</gml:coordinates>
                </gml:Point></ogr:geometryProperty>

This converts the airports shapefile into GML format and can be read (by either humans or programs) with little effort. GML data can be changed or appended to and then reconverted or used as is if your application supports the GML format. For example if you want to change the location of an airport, simply edit the text file using a text editor such as Notepad (on Windows) or vim (on Unix). Programs such as Word or Wordpad can also be used as text editors, but you must specify to save the files as plain text, or the data is saved as a binary format made for a word processor.

When editing the airports.gml file, you can see there are hierarchical sections in the file. Each airport feature has a section starting with <gml:featureMember> and ending with </gml:featureMember>. The last attribute listed in each section is <ogr:geometryProperty>. This is the section containing all the geometry information. To edit an airport file, simply change the coordinates that are entered between the <gml:coordinates> tags. For example:

    <gml:coordinates>444049,5277360</gml:coordinates>

can be changed to:

    <gml:coordinates>450000,5260000</gml:coordinates>

ogrinfo can be used again to view information about the GML file, or ogr2ogr can be used to convert the data back into the shapefile format someone else may be expecting. This is shown in the following example:

    > ogr2ogr -f "ESRI Shapefile" airport_gml.shp airports.gml airports

This takes the GML file and converts it back to shapefile format. Now ogrinfo can be run on it to compare the results with the earlier tests.

You will find that sometimes you get a set of data for a project but are interested in only a small portion of it. For example, if I’m making a map of my local municipality, I might want only the location of the nearest airport and not all 12 that are available from my government data source. Reducing the set of features is possible using ogr2ogr, and the syntax that selects the feature(s) of interest is almost identical to ogrinfo.

It is possible to use ogr2ogr as a feature extraction tool. For example, if you want to make a map of the Bigfork airport, you can use ogr2ogr and the -where option to create a new shapefile that only includes the Bigfork Municipal Airport, as shown in the following example:

    > ogr2ogr -f "ESRI Shapefile" bigfork data/airports.shp -where "name='Bigfork  Municipal Airport'"

The first parameter tells ogr2ogr to create a shapefile. The command then creates a folder called bigfork and creates the airports shapefile within it. As seen in Example 7-2, when you run ogrinfo against this dataset, you can see there is now only one feature, Bigfork Municipal Airport.

> ogrinfo bigfork airports
INFO: Open of 'bigfork'
using driver 'ESRI Shapefile' successful.

Layer name: airports
Geometry: Point
Feature Count: 1
Extent: (451306.000000, 5291930.000000) - (451306.000000, 5291930.000000)
Layer SRS WKT:
(unknown)
NAME: String (64.0)
LAT: Real (12.4)
LON: Real (12.4)
ELEVATION: Real (12.4)
QUADNAME: String (32.0)
OGRFeature(airports):0
  NAME (String) = Bigfork Municipal Airport
  LAT (Real) =      47.7789
  LON (Real) =     -93.6500
  ELEVATION (Real) =    1343.0000
  QUADNAME (String) = Effie
  POINT (451306 5291930)

The power of ogr2ogr is its ability to handle several vector data formats. To get a list of possible formats, run ogr2ogr without any parameters, as shown in Example 7-3. You will see the help information displayed as well as the -f format name options.

 -f format_name: output file format name, possible values are:
     -f "ESRI Shapefile"
     -f "TIGER"
     -f "S57"
     -f "MapInfo File"
     -f "DGN"
     -f "Memory"
     -f "GML"
     -f "PostgreSQL"

Creating other formats is as easy as changing the -f option to the needed format, then entering in an appropriate output dataset name. The -where clause can remain as is.

Converting to other file-based formats is particularly easy. The following example shows how to create a GML file:

    > ogr2ogr -f "GML" bigfork_airport.gml data/airports.shp -where "name='Bigfork Municipal Airport'"

This example shows how to convert to DGN format:

    > ogr2ogr -f "DGN" -select "" bigfork_airport.dgn data/airports.shp -where "name='Bigfork Municipal Airport'"

DGN format can’t support attribute fields. When converting to DGN, you’ll see an error message:

    ERROR 6: CreateField() not supported by this layer.

The file is created, but it doesn’t include any attributes. One workaround to this problem is to use the -select option. With other formats, the -select option allows you to specify what attributes you want to convert into the destination layer. Because ogr2ogr can’t convert any attributes to the DGN file, you select no fields by providing an empty value, such as two double quotes as shown in the DGN example.

ogr2ogr can also convert data to database formats, such as PostgreSQL (using the PostGIS spatial extension if it is available). The syntax for the command is more complicated than simple file-based formats because there are certain parameters that must be used to connect to the destination database. These options aren’t discussed in detail here but are covered in Chapter 13.

This example shows how to convert from a shapefile to a PostgreSQL database:

    > ogr2ogr -f "PostgreSQL" "PG:dbname=myairports host=myhost.com user=pgusername"
    data/airports.shp -where "name='Bigfork Municipal Airport'"

The command in this example connects to the myairports database on a server called myhost.com using the PostgreSQL database user pgusername. It then creates a table called airports. This is the same name as the input shapefile, which is the default. Querying the database using the PostgreSQL query tool psql shows that the conversion was successful, as in Example 7-4.

psql> select * from airports;
-[ RECORD 1 ]+--------------------------------------------------
ogc_fid      | 1
wkb_geometry | SRID=-1;POINT(451306 5291930)
name         | Bigfork Municipal Airport
lat          | 47.7789
lon          | -93.6500
elevation    | 1343.0000
quadname     | Effie

More detailed PostgreSQL usage is covered in Chapter 13, where an example problem shows how to load data into a spatial database and also extracts data from the database.

Just as ogr2ogr has several conversion options, so does gdal_translate. The syntax for the command is slightly different but similar in concept. Here is the usage:

    gdal_translate <options> <input_image> <output_image>

The options available can be listed by running the command without any parameters, as in Example 7-5.

> gdal_translate
Usage: gdal_translate [--help-general]
       [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/
             CInt16/CInt32/CFloat32/CFloat64}] [-not_strict]
       [-of format] [-b band] [-outsize xsize[%] ysize[%]]
       [-scale [src_min src_max [dst_min dst_max]]]
       [-srcwin xoff yoff xsize ysize] [-a_srs srs_def]
       [-projwin ulx uly lrx lry] [-co "NAME=VALUE"]*
       [-gcp pixel line easting northing]*
       [-mo "META-TAG=VALUE"]* [-quiet]
       src_dataset dst_dataset

GDAL 1.2.1.0, released 2004/06/23

This first part of the output of Example 7-5 shows the various options. Each item enclosed with brackets [] is optional. Without them, the program simply converts one image to another, creating the output in GeoTIFF format by default. Some options are used in the examples of the following sections and in more depth in other chapters of this book. Example 7-5 also shows the software version number and the official release date of the GDAL project.

Example 7-6 shows a list of all available image formats. This list will vary depending on the operating system and (only if you compiled it yourself) the options you specified during the configuration process. This lists many formats, though it may actually be able to read more image types. The list shows only potential output formats that can be used with the -of option. You supply this option with the abbreviated name for that format as shown in Example 7-6. For the latest capabilities, be sure to see the GDAL support formats page http://www.gdal.org/formats_list.html.

The following format drivers are configured and support output:
  VRT: Virtual Raster
  GTiff: GeoTIFF
  NITF: National Imagery Transmission Format
  HFA: Erdas Imagine Images (.img)
  ELAS: ELAS
  AAIGrid: Arc/Info ASCII Grid
  DTED: DTED Elevation Raster
  PNG: Portable Network Graphics
  JPEG: JPEG JFIF
  MEM: In Memory Raster
  GIF: Graphics Interchange Format (.gif)
  XPM: X11 PixMap Format
  BMP: MS Windows Device Independent Bitmap
  PCIDSK: PCIDSK Database File
  PNM: Portable Pixmap Format (netpbm)
  ENVI: ENVI .hdr Labelled
  EHdr: ESRI .hdr Labelled
  PAux: PCI .aux Labelled

  MFF: Atlantis MFF Raster
  MFF2: Atlantis MFF2 (HKV) Raster
  BT: VTP .bt (Binary Terrain) 1.3 Format
  JPEG2000: JPEG-2000 part 1 (ISO/IEC 15444-1)
  FIT: FIT Image
  USGSDEM: USGS Optional ASCII DEM (and CDED)

Keep in mind that any type of image format supported by GDAL can be translated, including digital camera photos or images from a web site. The most basic example of conversion, such as the following example, takes an image in one format and outputs it to another format.

    > gdal_translate image1.png image1.tif
    > gdal_translate -of "PNG" image1.tif image1.png

An image can be translated back to the same format too, if creation of that format is supported by GDAL.

In Chapter 6, gdalinfo was used to show the details of a RADARSAT image of Canada. The image was a whopping 5,700 × 4,800-pixel image and more than 25 MB in size. Only special image-handling programs like gdal-related tools can handle files that large. This isn’t an image you would want to send to a friend as an email attachment! Not only would the file size be a problem but your friend probably could not use basic image viewers because it is a very large GeoTIFF file.

The gdal_translate utility is a handy tool for many things, one of which is reducing the size of an image and outputting it to a more usable format for the project at hand. In Example 7-7, gdal_translate reduces the size of the image to 5% and creates a small JPEG format file as output. Running gdalinfo against this new file shows that the resulting file is now a mere 285 × 240 pixels and is a JPEG format image. The file size is now less than 20 KB. This is easily viewable by the simplest image viewer on most personal computers.

> gdal_translate -of "JPEG" -outsize 5% 5% canada_mosaic_lcc_1000m.tif can_radar.jpg
> gdalinfo can_radar.jpg
Driver: JPEG/JPEG JFIF
Size is 285, 240

Figure 7-1 shows what the can_radar.jpg image looks like after Example 7-13.

Figure 7-1. The original radar satellite image before clipping

gdal_translate can also be used to specify only a portion of an image to be translated. The result is a clipped portion of the image being put into a new file. This is done using the -projwin option to specify geographic coordinates of the area to clip out, or -srcwin if you know which pixels you want to include. You can use OpenEV to preview the image and get an idea of what the upper-left and lower-right coordinates are around your area of interest. Then do the same type of translation as before, but provide coordinates in the -projwin parameter. Example 7-8 shows this kind of clipping as well as a conversion, all in one command.

> gdal_translate -of "JPEG" -projwin -2281300 7464800 -1812300 7001800 canada_mosaic_lcc_1000m.tif can_radar_clip.jpg
Input file size is 5700, 4800
Computed -srcwin 318 3035 469 463 from projected window.

Figure 7-2 shows the resulting clipped satellite image.

Figure 7-2. A satellite image clipped using the gdal_translate -projwin option

Here is a list of some of the free and open source desktop GIS and mapping programs available today:

For more comprehensive lists of open source GIS and mapping tools, see:

Many of the major vendors distribute their own free viewers. These aren’t considered freeware because you may not be able to freely distribute the programs. However, they are freely available to use:

Freeware applications include:

There are also several commercial GIS and mapping programs available. This is a short list with an approximate single-user license cost (U.S. dollars) based on Internet price lists.

Chapters 5 and 6 walked you through how to acquire sample data and review it using some simple tools. If you don’t already have the MapServer demonstration data and the FWTools downloaded and installed, please refer back to these sections in Chapter 6.

You should have two things: a sample MapServer application known as Workshop and a copy of OpenEV that comes with FWTools. To test that you have OpenEV installed, launch the program. Windows users will launch the OpenEV_FW desktop shortcut. This will open a command window and create some windows.

Linux users will launch the openev executable from the FWTools bin_safe folder.

    > ./install.sh

    > . /fwtools_env.sh

When starting, the main window titled “OpenEV: View 1” should appear with a black background. The Layers windows will also appear.

Starting from the default View 1 screen, you can add in sample data by selecting Open from the File menu, or by clicking on the folder icon on the left side of the main tool bar. The File Open window allows you to find a dataset on your filesystem and load it as a layer in OpenEV. All files are listed in the File Open window, whether or not they are spatial datafiles. OpenEV doesn’t attempt to guess what they are until you actually try to open one.

Windows users may get confused when trying to find data on a drive with a different drive letter. The drive letters are listed below all the folders in the File Open window. You must scroll down to find them.

Navigate using the File Open window to the location where the workshop/data folder has been unzipped. In the data folder, you will see dozens of files listed. Select airports.shp to load the airports shapefile. As shown in Figure 8-1, 12 small green crosses should appear in the view. Each point represents the location of an airport from the demonstration dataset.

OpenEV has other windows for different tasks. One of these is the Layers window. If it isn’t already showing, select Layers from the Edit menu, as shown in Figure 8-2. This window lists the layers that are currently loaded into OpenEV. A layer can be an image or, as in our case, vector data. Only the airports layer should be loaded at this point. You will see the full path to the airports.shp file. Beside this layer name is an eye icon. This says that the layer is currently set to be visible in the view. Try clicking it on and off.

Figure 8-1. Initial loading of airport shape file

The layers window allows you to change certain graphical display settings for your layers. Access these settings by right-clicking on the layer name. The airport layer name may be somewhat obscured if you have the file deep in subfolders, because the default name for the layer is the whole path to the file. The layer window can be resized to show the full name more clearly if necessary.

Right-click on the airports layer in the Layers window, you’ll see the Properties window for the airports layer, as shown in Figure 8-3.

There are three options on the General tab of the Properties window:

The other tab at the top of the airports Properties window is called Draw Styles. Switch to this tab to see the various draw settings, as shown in Figure 8-4. There are five different groups of settings on this tab.

Figure 8-4. Draw styles window

When all the settings are complete, simply close the properties window by clicking on the X symbol in the top-right corner of the window. As you change settings, they are updated automatically in the view. Close the properties window, and return to the View 1 window.

One of the benefits of software like OpenEV is the ability to add many layers of data and compare them with each other. With some work setting draw styles, a simple map can be produced. The workshop dataset includes more than just an airports layer.

Click on the folder icon in View 1 to add another layer of features. The data is located in the same folder as the airports. This time add the file called ctyrdln3.shp. This is a layer containing road line data for the same county as the airports.

From the Layers window, right-click on the ctyrdln3 layer to open the layer properties window. Change the name to something obvious, such as Roads. You should also change the road line colors so they aren’t the same as the airports. Notice that the road lines are being drawn on top of the airport symbols. The order of the layers is always important when creating a map, and, depending on your project, you may want to reorder the layers. This is done in the Layers window. Left-click on the layer name you want to change. The layer name will now be highlighted. Then select one of the up or down arrow buttons at the bottom of the Layers window. This moves the layer up or down in the draw order. The final product looks like Figure 8-5.

Figure 8-5. Road lines and airports loaded

One the first things you will want to do is zoom in to certain portions of your map. There are a couple ways to do this. The first is to use the plus and minus buttons on the toolbar of the view. The icons are a magnifying glass with a + and - symbol inside them. Clicking + zooms into the center of the screen, and clicking - zooms out from the center of the screen.

The more efficient way is to use the Zoom tool, which allows you to drag a rectangle on the screen and zoom in to that portion of the map. To enable the zoom tool, select the Edit Toolbar from the Edit menu, then choose Zoom from the list, as shown in Figure 8-6.

Figure 8-6. Activating the zoom tool

Now you can return to the view and click and hold the left mouse button to zoom in. You can also drag a rectangle around a portion of the screen and have it zoom in directly to that location. To do this, click and hold the left mouse button, then drag the mouse to another location. Watch as the rectangular zoom box appears, as in Figure 8-7. When the box covers the area you want, let go of the mouse button.

Zooming out can be done a few ways as well. As mentioned earlier, you can use the zoom-out magnifying glass button, but you can also hold the right mouse button down and slowly zoom out. Another method to use, if appropriate, is the Fit All Layers button on the main view tool bar. This button is a rectangle with four internal arrows pointing toward the corners of the rectangle, as shown in Figure 8-8. Clicking this button zooms out so far that all the data in all the layers can be seen.

Figure 8-7. Select an area with the zoom in tool

Figure 8-8. The OpenEV toolbar, pointing out the Fit All Layers button

Many desktop mapping programs have a feature called panning . This is a way of sliding or moving the map around so you can look at different portions without having to zoom out and then back in again. The scrollbars in the view play this role. If there is map data beyond the sides of a view, you can slide the scrollbar or click on either arrow at the ends of the scrollbars. This moves you to the area you are looking for without changing the scale or size of the map features.

You probably don’t always want to show all the features of a map layer using the same color. For example, the roads layer includes two different classes of roads. You may want to show each class in a different color, with a different road line thickness. Or you may not want to show one of the classes at all.

This road data includes an attribute that tells you what class each segment of line is. To use the values of this field to color the lines differently, you can use the Classify button on the tool bar, shown in Figure 8-9. It is a button with the letter C inside it.

Figure 8-9. OpenEV’s classify button

Click on this button, but remember to have the layer you want to classify (e.g., Roads) selected in the Layers window. The Layer Classification window appears (see Figure 8-10) and makes a basic set of classes for you.

Figure 8-10. Classifying a layer using a feature attribute

For the road data it uses the LENGTH attribute by default because it is the first attribute. Switch the drop-down list in the top-right corner of the window to another field and see how it recreates the classification on the fly. Change this setting to the attribute ROAD_CLASS. This yields several values in a list, as shown in Figure 8-11.

Figure 8-11. Classifying by road class

The default method for classifying these values isn’t appropriate because it uses a range of values. There are only two road classes: integer numbers 4 and 5. You can change the way the classifier works by selecting the reclassify button. Change the Type to Discrete Values and press OK. This gives each distinct value in the ROAD_CLASS field a different color, as shown in Figure 8-12.

Figure 8-12. Classifying roads into two road classes

Notice how there appear to be some primary roads (class 4) and secondary roads (class 5). You can change the colors for each class until you are satisfied. Hit the Apply button to draw the roads using these colors, as shown in Figure 8-13. Remember that if one of the colors is black, it won’t show against the black background in the view window.

Figure 8-13. Applying color-theming using the road class attribute

There are several other options available in the classifier. One that is handy is the default set of Color Ramps in the drop-down on the Layer Classification window, shown in Figure 8-14.

You can quickly classify, reclassify, and set various color themes. Just select an item from the Color Ramps dropdown list, and hit Apply. Don’t like it? Change it, and apply again. If you only have a couple values in your classification, these color ramps won’t be as valuable, but they are particularly useful for raster data. When you are happy with the results, press the OK button to close the classification window.

Figure 8-14. Selecting a color ramp to classify features

Adding a raster layer can often be easier than adding vector themes, because common raster formats are usually a single file with colors already assigned. The raster used in this example is a land cover dataset that covers the earth, but for this example it’s focused on Itasca County, Minnesota. You can download the image from this book’s O’Reilly web site at http://www.oreilly.com/catalog/webmapping.

This is a GeoTiff image, also known as a TIFF file . The .tif extension is the common filename suffix. Add the image to the OpenEV view by selecting File → Open and browsing your filesystem to find the landcover.tif file. Double-click on the filename or press the OK button. Notice that the layer is added to the list in the Layers window, but is currently not visible on the map (we’ll come back to this point). It automatically becomes the topmost layer. Select the layer from the list and use the down arrow at the bottom of the layer window. This will move that layer to the bottom so that the vector data (airport points) will show on top of the other layer when it is ready.

If you right-click on the layer in the layer list, there are some options to select and change, just as with vector data, but the options are very different. The General tab is the only similarity. Some tabs are for information only; others will alter how the raster is displayed.

Even if you press the Fit All Layers zoom button, you won’t see the land cover layer because the workshop dataset and the land cover dataset aren’t in the same map projection. This is a common problem when taking data designed for a county or region and using it in a global map.

In this case, the workshop datasets are in the UTM projection. The land cover raster isn’t projected and uses geographic coordinates, specifically latitudes and longitudes measured in degree units. More information about map projections is available in Appendix A.

OpenEV doesn’t itself have the ability to reproject data layers. The tools introduced in Chapters 3 and 7 can be used to reproject a layer so that OpenEV can display it the way you want.

In this example, ogr2ogr (introduced in Chapter 2) is used to reproject or transform the coordinates of the airport data from one spatial reference system to another:

    > ogr2ogr shp_geo airports.shp airports -t_srs "+proj=latlong" -s_srs "+proj=utm +zone=15"

There are four parts to this command. The first section is the parameter that specifies the output dataset name. In this case, it creates a folder called shp_geo to put the translated files into.

The next section specifies what the input data is going to be. ogr2ogr reads in the airports.shp dataset and, specifically, the airports layer in that shapefile.

The next part starting with -t_srs specifies what target (or output) spatial reference system (t_srs) to put the data into. Without going into detail, the projection is set by +proj=, to output the data into latlong coordinates.

The final section -s_srs defines what the source spatial reference system (s_srs) is. Because the airports.shp file doesn’t have projection information included in it, you have to know what it is and specify it here. This allows ogr2ogr to calculate what transformation to use. In this case, +proj=utm +zone=15, the projection is UTM, and the UTM zone is 15.

These are the most basic projection settings and will work for you, but you should be aware that to more accurately describe your data, you may need to specify more projection details such as datum, ellipsoid, or units.

    -s_srs "+init=EPSG:26915"

    -t_srs "+init=EPSG:4326"

Continue this conversion exercise for all the other workshop datasets (i.e., ctyrdln3.shp) so you can use them in your map. Just change the source and destination dataset/layer names in the ogr2ogr command example.

Add the newly created shp_geo/airports.shp file to the view. To quickly see their locations, remove the old UTM-based airports layer from the view, then click the Fit All Layers button to zoom out to the whole earth. Zoom in to the United States, and see where the airports fall. They are located around -93.54E, 47.53N degrees. You may need to resize or recolor the airport point symbols so that they are visible on top of the image, as in Figure 8-15. The locations are now shown to be on top of the land cover image, in northern Minnesota, because they are both in the same map projection. Figure 8-16 shows the map zoomed in to the area.

OpenEV can render simple 3D perspectives of data. This is done using two input layers. One image shows the elevation surface—this is often called a Digital Elevation Model or DEM—where dark to light colors represent low to high elevations, respectively. The other input layer is the image you would like draped over the DEM. This can be thought of as a sheet being draped over a basketball, where the ball represents the elevation model.

Preparing the Digital Elevation Model

The first image you need is a DEM. If you don’t have this kind of image, you can’t create a useful 3D perspective of your data. If your target application is the United States, a lot of DEM datasets are available. They can often be used in OpenEV without any data conversion.

Figure 8-15. Land cover image with general location of airports shown by a black star

Here are some sites that have elevation datasets available:

GTOPO: Global digital elevation model

http://edcdaac.usgs.gov/gtopo30/gtopo30.html

SRTM: Global coverage from Shuttle Radar Topography Mission

http://srtm.csi.cgiar.org/Index.asp

USGS DEM: Digital elevation models for the United States

http://edcsgs9.cr.usgs.gov/glis/hyper/guide/1_dgr_demfig/states.html

U.S. National Geophysical Data Center: Various types of data

http://www.ngdc.noaa.gov/mgg/bathymetry/relief.html

The image used in this example is called hibbing-w and was downloaded in the USGS DEM data format from http://edcsgs9.cr.usgs.gov/glis/hyper/guide/1_dgr_demfig/states/MN.html.

Figure 8-16. Zoomed in to the airports with the land cover image shown in the background

OpenEV and GDAL-based applications can read this image format. Add the image to a normal OpenEV view, and you will see that the image is grayscale—sometimes referred to as black and white (though that isn’t technically correct). When you switch into 3D mode, black represents the lowest elevations in your model, and white represents the highest elevations.

The hibbing-w image is a good example of a smooth progression of shades from black to white, as shown in Figure 8-17 (in normal 2D mode). This is ideal. A DEM that has a very limited color gradient, with sharp contrasts, produces a chunky and unrealistic-looking surface. It would ultimately be useless unless you wanted an unnatural appearance.

Figure 8-17. The DEM image for part of Minnesota, U.S.A.

Preparing the drape image

The other image you need is called the drape image. It’s overlaid or draped on top of the DEM. The DEM surface itself isn’t visible except by seeing the shapes and contours of the drape image laying on it.

Any image can be draped on the DEM, but it’s not as easy as it sounds. There are some strict requirements you need to follow to get meaningful results.

The drape and DEM image sizes or extents must match, or the coordinate systems must be identical and overlap each other. You can have a high-resolution DEM with a lower resolution drape image, but the drape image must fall on top of the DEM to be shown properly.

One way to ensure that your drape image is useful is to have OpenEV output snapshots of your DEM and drape image to new files. In this example, the drape and DEM images are created by turning on various layers and printing them into new TIFF images.

You start by loading OpenEV with the DEM image and some of the workshop data layers. Remember to use the data in lat/long coordinates described earlier so it matches the DEM projection.

Now, with all layers except the DEM turned off, zoom in to the image. To take a snapshot of this DEM, use the Print command under the File menu. In the Print window, set the following:

    Driver: TIFF
    Device: FILE
    File: 
                     <path to a local folder>
                  
                  /dem.tif
    Output Type:Greyscale
    Resolution: 1

Figure 8-18 shows how to put these values into the print window.

Figure 8-18. Printing the DEM map into an image file

When you press the Print button, OpenEV takes the contents of the View and outputs it to the new image file you specify. The same thing is done to create the drape image.

The main thing to remember when creating your drape image is not to move around in the view. Don’t zoom in or out but keep looking at the same location that was used to print the DEM image. Turn on different layers: water, roads and the land cover image for example, as shown in Figure 8-19. Then go through the same print process as earlier, changing the File setting to call the file drape.tif instead of dem.tif. Be sure to switch Output Type to color if applicable.

Figure 8-19. Using the print window to output a drape image

Initiating the 3D view

You are now ready to combine the DEM and drape images to create a 3D perspective. Select New View from the File menu to create a new working space without closing View 1. Then, in that new view, select Open 3D from the File menu. This displays a new window (see Figure 8-20), prompting you to select two different images: the DEM in the upper selection box and the Drape image in the lower one. Find the images you created earlier, and enter them into the filename selection boxes. Leave the rest of the options with their default settings, and press OK.

Figure 8-20. Creating a 3D view

OpenEV then creates the default perspective of your 3D view as shown in Figure 8-21.

The background is black, and the color drape image is shown with dips and bumps conforming to the DEM underneath. You can now navigate your way through the image and also raise or flatten the DEM further.

Navigating the 3D view

The controls for navigating in the 3D view aren’t always easy to use but are sufficient for getting a quick perspective of your data. Navigating the 3D view isn’t very

Figure 8-21. The default 3D view of a model

intuitive if you are new to the concept. Keep in mind that OpenEV is tracking several things about your 3D model and your location. The view acts like a camera, which requires you to look through a viewfinder. The camera is always looking at the subject, in this case the 3D model, from a certain location in space. By default, the view camera is positioned higher than the model and not right over it. A specific part of the model is in the center of the view, and the camera is tilted to a certain angle.

As in the normal 2D view, you zoom in to the model by holding down the left mouse button. Where the cursor is pointing is irrelevant. It always zooms in to the center of the view.

Moving the mouse while holding down the left mouse button the pivots the camera—both horizontally and vertically. This is where navigation can become a bit tricky. If you pause for a split second while pivoting your camera, OpenEV will start zooming again right away.

To drop the camera up and down or slide it left or right, hold down the control (CTRL) key while dragging with the left mouse button. Again, be aware that zooming will begin if you stop moving and continue to hold down the left mouse button.

There are some other keyboard controls that do the same tasks as the mouse commands. Page Up/Page Down zooms in/out. Pressing Shift while doing this makes it zoom faster. The keyboard arrow buttons move the camera up/down and left/right. The Home key returns you to the initial 3D view. This is especially useful if you get lost or are still learning to navigate.

It is possible to know the exact location of the camera and to change it manually by setting the camera coordinates. This is helpful if you want to recreate a scene at a later date. To do so, use the 3D Position options, found under the Edit menu. As seen in Figure 8-22, it lists the X,Y, and Z position of your camera as well as where the camera is looking on the model in the center of your view. These position values refer to pixel row and columns. You can change any of these values and the view will be updated. Simply change the value, and press Enter or Tab into the next field.

Every 3D model has a setting for a height or Z scaling factor. This is the amount that the DEM is stretched vertically, giving it the 3D appearance. Other applications and cartographic processes refer to this type of setting as vertical exaggeration . The default in OpenEV is 1.0 and is set in the Open 3D window before initiating your 3D view. If the setting is too low, your model will look flat; if too high, your model will look jagged or meaningless. This setting can be changed while viewing your 3D model using the plus + or minus - keys. Combining them with the Shift key allows you to rapidly increase or decrease the scaling factor. In Figure 8-22, the Z scaling factor is reduced to make the landscape look more realistic.

Figure 8-22. The 3D position window showing camera location and focus

The size and scale of the map you are making will affect various parts of your project. If you want a wall-size map covering your neighborhood, you will have very different requirements than someone planning a world map for a small book. You need to ensure that the data you create will work well with your intended map. Here are some questions to consider:

When creating new or customized data it helps to have a base map to start with. You need data in the correct scale, covering the right area. You can then draw features on top of the base to create custom data. The data itself is the goal of this chapter, not a final map product.

The base map gives you a reference to the real world. You may have an air photo you can scan or a topographic map image downloaded from the Internet. Your base data doesn’t necessarily need to look good if you are just using it as a reference for creating data. For example, highway data can be the reference for roughly locating towns. Since all highways won’t be visible at a country-wide map scale, they won’t end up on your final map.

When considering your base map requirements, keep in mind that global scale datasets are available but are often very coarse. There are a lot of detailed air photo and road line files available for the United States. You can probably even locate your house. Canada has a handful of satellite images available for most of the country but not to a scale you can use to locate a home. Other countries have varying levels of data available.

Chapter 5 has a list of data sources that can help you find useful base map data.

Once you’ve figured out your base map requirements, you need to find the appropriate data so, where do you go to get data? There are many options.

The satellite image used for this project covered a much broader area than was needed. Unnecessary portions of the image were clipped off, speeding up loading and making the image a more manageable size.

I used OpenEV to view the file and determine the area of interest. Figure 9-1 shows the whole image or scene.

The large lake in the bottom half of the image is Okanagan Lake. After zooming in to the general area of interest, the Draw Region Of Interest (ROI) tool is used to select a rectangle. The Draw ROI tool is on the Edit Toolbar, which can be found in the Edit menu. To use the ROI tool, select the tool and drag a rectangle over the area. It creates an orange rectangle and leaves it on the screen, as shown in Figure 9-2.

This area is then exported to a new file. To do this, use the File → Export tool. The Export window provides several options as shown in Figure 9-3. There is a small button near the bottom of the window that shows Advanced Options.

The filename of the image that will be created is entered into the Set Output box. This tool automatically exports the whole image to a new file, but only the selected region needs to be exported. To do this, select the Window Input File button. The four text entry boxes in the Input Window area show numbers that correspond to the pixel numbers of the image that will be exported. Only the pixels in the portion of the image identified as the ROI should be used.

Figure 9-1. Landsat image of the Kelowna, Canada area

When you press the Export button, it creates the image using only the region you specify.

Now the original image isn’t needed, and the new image can be loaded into OpenEV. Figure 9-4 shows the new image being displayed.

Now you have a more manageable image to work with, and it is nicely clipped to the area of interest. You can clearly see changes in vegetation cover and urban areas. The urban areas are gray, thicker forests are a darker green, brighter green are thinned forests, etc. The data is fairly low resolution, but if you zoom in to the city you can almost find your way around the main streets. The lower part of the image shows some hilly landforms; this is the area of Okanagan Mountain Park, where the fire began. The image shows this area before the fire occurred.

Figure 9-2. Defining a region of interest using the Draw ROI tool

This project will use a coordinate of a location from a GPS receiver. Because it is a single point, it is easy to just write down the coordinate off the receiver’s screen rather than exporting it to a file.

The point was recorded using latitude and longitude geographic coordinates. The image is in a different spatial reference system that uses the UTM projection. The coordinates can be converted into UTM, or the image can be transformed into geographic coordinates (e.g., decimal degrees). The latter can be easiest because you

Figure 9-3. Using the Export option in OpenEV

may end up using other data from global datasets, which are typically stored in decimal degrees.

Use the GDAL utility gdalwarp to transform the image. It is a Python script that can transform rasters between different coordinate systems, often referred to as reprojecting. The kelowna.tif image must be removed from OpenEV before reprojecting.

The options for this command are formed in a similar way to projection exercises elsewhere in this book (e.g., Chapter 7 and Appendix A). From the command line specify the command name, the target spatial reference system (-t_srs), and the source/target filenames.

    >gdalwarp -t_srs "EPSG:4326" kelowna.tif kelowna_ll.tif

    Creating output file that is 1489P x 992L.
    :0...10...20...30...40...50...60...70...80...90...100 - done.

Figure 9-4. Viewing the clipped image

The EPSG code system is a shorthand way of specifying a projection and other coordinate transformation parameters. The EPSG code 4326 represents the lat/long degrees coordinate system. Otherwise, you would have to use the projection name and ellipsoid:

    -t_srs "+proj=longlat +ellps=WGS84 +datum=WGS84"

The resulting image looks slightly warped. Instead of being in UTM meter coordinates, all points on the map are in latitude/longitude decimal degree coordinates. Figure 9-5 shows the new image. When you move your cursor over the image, the coordinates show in the status bar at the bottom of the View window.

This image is now ready to use as a base map for creating your own data.

Once the base map is ready to be used, you can start to create new map data. This following example results in a simple map showing a home in Kelowna and the driving path to the fire burning in a nearby park. This involves a few different types of data: a point location of the home, a road line, and the area encompassing the fire.

Mapping locations of interest (point data)

With OpenEV open and the satellite image as the background layer, you are almost ready to start drawing points (a.k.a. digitizing). First you need to create a new vector layer that will store the point locations. This is done by clicking the New Layer button in the Layers window. It is the bottom-left button that looks like a page, as shown in Figure 9-6.

When the new layer is created, it is given the default name UserShapes_1. This layer is saved as a shapefile. Shapefiles are limited to holding one type of data at a time including points, lines, or polygons. If you create a point, it only stores points. Right-click on the new layer, and rename it Home in the properties window. You may need to turn the layer off and back on for the title to change.

Next, open up the Edit Toolbar from the Edit menu. The tool called Point Edit allows you to draw points on the map and store them in the currently selected layer. In Figure 9-7, the tool was selected and then used to identify a location near downtown Kelowna. The location was based on the coordinate: 119.491°W, 49.882°N. To find this location, you move your pointer over the map and watch the coordinates in the status bar change. When you get to that coordinate, click the mouse button. The location is drawn as a green square, according to the default properties of the new layer.

Figure 9-5. Image of Kelowna transformed from UTM to geographic coordinates

To save the new location to a shapefile, make sure the layer is still selected or active in the Layers window. From the File menu, select Save Vector Layer. A dialog box pops up asking for the location and name of the file to create. Store the file in the same folder as the satellite image so they are easy to find. Call the layer home.shp. To test that the layer saved properly, turn off the new layer you have showing and use File → Open to open the shape file you just saved. To remove points or move existing points, use the Select tool, and click on the point. You can click and drag to move the point.

Figure 9-6. Creating a new layer for storing point locations

Warning

Don’t remove your new temporary working layer from the layer list yet. Loading in the saved shapefile is only a test to show you that saving works. In the next section, you will still need access to the new layer you create, not the saved shapefile.

Creating and saving tabular attributes

The geographic location isn’t the only thing you’ll want to save. Sometimes you will want to save an attribute to identify the point later on.

Tip

An attribute is often called a field or column and is stored in the .dbf file associated with a shapefile.

With the new layer selected, go to the Tools menu, and select Tabular Shapes Grid. This shows an empty attribute table for the layer. If you do this with another vector layer that already has attributes, it will show those values. Your point will have a number identifier (e.g., 0) but nothing else to describe what the point represents. You can create a new attribute by clicking inside the Tabular Shapes Attribute window. A menu pops up giving you the Edit Schema option, as shown in Figure 9-8.

Warning

You can only edit the schema of a new layer—one that hasn’t been saved yet. It is often best to set up your attributes before saving the vector layer to a file.

Figure 9-7. Using the Point Edit tool to draw a location on the map

The Schema window that appears allows you to create a new attribute. In Figure 9-9 a new attribute has been created, called Placename. This is done by typing the name of the new attribute into the Name box near the bottom of the window, then pressing the Add button (leaving the default type as string and width as 20). The description of the attribute is listed at the top of the window.

Close the Schema window, and you are brought back to the attribute listing. Now there is a new column, as in Figure 9-10. You can click inside that column and type in a value for the Placename attribute for the point created earlier. Try typing in My

Figure 9-8. Viewing the attributes of your shape

Place and then press Enter to save the change. This change is saved automatically, and no manual resaving of the file is required.

You can test out this attribute by using it to label your new point. To enable labels, right-click on the layer name in the Layers window. This brings up the properties of the layer. Now, select the Draw Styles tab. Near the bottom is an option called Label Field. You should be able to change this from disabled to Placename. As shown in Figure 9-11, your view window should now display the label for the point you created.

Mapping roads and transportation paths (linear datalinear data

Now that you have a point showing where the house is you’re ready to draw some more details about the transportation infrastructure. This is a bit more complex because line features are more than just a point. In fact, line features are a series of points strung together and often referred to as line strings. Mapping road lines involves drawing a series of points for each line and saving them to a new shapefile.

Figure 9-9. Adding a new attribute using the Schema editor

Figure 9-10. A new attribute added to the point

Figure 9-11. Labeling the new point using the attribute

Open the Layers window again, and click the New Layer button shown by the white-page icon. The typical new layer is created with a basic name such as UserShapes. Change the name to reflect the type of data being created, such as Roads.

From the Edit Toolbar (activated under the Edit menu), you will find a Draw Line tool. This is much like the Point Edit tool, but is made for lines, not points. In this project, a line is drawn showing the rough driving path from a park to the house (My Place). A base map of the area from a government web site helps show where the driving path should be drawn.

With the additional base map showing road lines, you can now draw on top of those lines, following the path to the park. Figure 9-12 shows the rough red line drawn as a path. Each point clicked becomes a vertex in the line. OpenEV shows these as squares. After the last vertex is created, press the right mouse button to finish drawing. That line is now complete. You can modify the settings for the Roads layer to draw the line a bit thicker, making it easier to see on top of the busy base map. Note that the base map image is fairly poor resolution. That doesn’t matter because it will be tossed away when finished drawing; it’s used here as a temporary reference.

Grabbing a Base Map Layer from a WMS

To get this base map you must use a WMS request through a URL (as discussed in Chapter 12), and feed it the extent coordinates of the kelowna_ll.tif file. You can get the coordinates by using the gdalinfo command and then create a World File for the image to geo-reference it. Here is the command used to grab the image (some layer names are removed and spaces added to try to keep it simple. It is all one line, with no spaces):

    > wget -O msrm_wms.jpg
    "http://libcwms.gov.bc.ca
    /wmsconnector/com.esri.wsit.WMSServlet
    /ogc_layer_service?request=GetMap
    &version=1.1.1&srs=EPSG:4326
    &format=image/jpeg
    &layers=NTS_BC_RIV_LAKE_WET_POLYS_125M,
    NTS_BC_CONTOUR_LINES_125M,
    NTS_BC_TRANSPORT_LINES_125M,
    NTS_BC_WATER_LINES_125M,
    NTS_BC_ANNO
    &bbox=-119.8232227,49.6477753,
    -119.3140010,49.9870285
    &width=745&height=496
    &styles"

Of course, if you want to use this data in a MapServer application, you don’t have to download the image and can have the image requested in real time from the WMS service. A WMS tool is currently being developed for OpenEV.

For more on world files and map projections see Appendix A. See Chapter 12 for using web services like WMS.

Now that you have a road line, you can save it to a shape file. As with the point data, just select that layer from the Layers window, and then use the Save Vector Layer option under the File menu to save it as roads.shp.

Mapping regions of interest (area/polygons data)

The third part of this mapping project is to draw the area of the forest fire. This won’t be a point or a line, but a polygon or area showing the extent of a feature. To help with this task, a few satellite images that were taken during or after the fire are used. Two main barriers come up, one of resolution and the other a lack of geo-referencing information. Both images and their shortcomings are presented to give you an idea of the thought process and the compromises that need to be made.

The first image is from http://rapidfire.sci.gsfc.nasa.gov/gallery/?2003245-0902/PacificNW.A2003245.2055.250m.jpg. An overview of this image, with the point from home.shp, can be seen in Figure 9-13.

Figure 9-12. Road line/path drawn on top of base map

Tip

The web site at http://rapidfire.sci.gsfc.nasa.gov/gallery/ is a great resource! It includes various scales of real-time imagery showing thousands of events from around the globe.

Figure 9-13. A real-time image of fires in the Pacific Northwest

The great thing about this image was that you can download the world file for the image too. This is the geo-referencing information needed to geographically position the image in OpenEV (and other GIS/mapping programs). The link to the world file is at the top of the page. Be sure to save it with the same filename prefix as the image. For these images, the filename suffix, or extension, is jgw. Be sure to save it with the proper name, or the image won’t find the geo-referencing information. The only problem with this image is that it’s very low resolution. My search for a better image led to:

It’s good and has much higher resolution, showing the fire very well, as seen in Figure 9-14.

This image isn’t geo-referenced. Because only the general extent of the fire is needed, it isn’t worth the trouble of geo-referencing. It is possible to do so using the gdal_translate utility with the -gcp option, but it can be very tedious.

Figure 9-14. A higher resolution image of the Okanagan Mountain Park fire

The final decision is to use the first image. It is lower resolution, but with little effort, it’s ready to work with OpenEV.

Add the fire image layer, and you will see that it overlaps the Kelowna Landsat image very well. Because the base data is no longer in UTM projection, it lines up with this image without any more effort. This image is fairly low resolution, but it does show the rough area of the fire as well as smoke from the eastern portion as it still burns.

Create a new layer to save the polygon data to, and call it Fire_Area. Then from the Edit Toolbar, select the Draw Area tool. Draw the outline of the burned area. Don’t be too worried about accuracy because the end product isn’t going to be a highly detailed map—just a general overview. Figure 9-15 shows the process of drawing the polygon.

Figure 9-15. An area drawn to shown the extent of the fire

Each vertex helps to define the outer edge of the area. When done, press the right mouse button to complete the drawing. Then use Save Vector Layer to put the Fire_Area layer into a shape file called fire_area.shp.

Tip

You may notice that the extent of the fire shown on this image is quite different from the image in Figure 9-14. This is because Figure 9-15 was taken at an earlier time.

These examples have produced a few different images and three vector data shapefiles. These can now be used in a MapServer-based interactive web map (Chapters 10 and 11), or the data can be made available to others through a web service (Chapter 12). Either way, you have made the basic map data and have the flexibility to use it in any program that supports these data formats.

A simple world map boundary dataset will be used for this example. This shapefile contains boundaries of the country borders for the world and are available from the FreeGIS (http://www.freegis.org) web site at http://ftp.intevation.de/freegis/worlddata/freegis_worlddata-0.1_simpl.tar.gz.

The first thing to do is check out the data. This is done using the ogrinfo tool as described in Chapter 6. This isn’t a MapServer utility but is a valuable tool for getting started, as shown in Example 10-1.

                  > ogrinfo countries_simpl.shp -al -summary
INFO: Open of 'countries_simpl.shp'
using driver 'ESRI Shapefile' successful.

Layer name: countries_simpl
Geometry: Polygon
Feature Count: 3901
Extent: (-179.999900, -89.999900) - (179.999900, 83.627357)
Layer SRS WKT:
(unknown)
gid: Integer (11.0)
cat: Integer (11.0)
fibs: String (2.0)
name: String (255.0)
f_code: String (255.0)
total: Integer (11.0)

male: Integer (11.0)
female: Integer (11.0)
ratio: Real (24.15)

This example shows several key pieces of information prior to building the MapServer map file.

    Geometry: Polygon

The shapefile holds polygon data. MapServer can shade the polygon areas or just draw the outline of the polygons. If the geometry was line or linestring, it wouldn’t be possible to fill the polygons with a color.

    Feature Count: 3901

The feature count shows that there are many (3,901 to be exact) polygons in this file. If it said there were no features, that would tell me there is something wrong with the file.

    Extent: (-179.999900, -89.999900) - (179.999900, 83.627357)

ogrinfo shows that the data covers almost the entire globe, using latitude and longitude coordinates. The first pair of numbers describes the most southwestern corner of the data. The second pair of numbers describes the most northeastern extent. Therefore when making a map file, set it up so that the map shows the entire globe from -180,-90 to 180,90 degrees.

    Layer SRS WKT:
    (unknown)

There is no spatial reference system (SRS) set for this shapefile. By looking at the fact that the extent is shown in decimal degrees, it is safe to say that this file contains unprojected geographic coordinates.

    gid: Integer (11.0)
    cat: Integer (11.0)
    fibs: String (2.0)
    name: String (255.0)
    f_code: String (255.0)
    total: Integer (11.0)
    male: Integer (11.0)
    female: Integer (11.0)

This is a list of the attributes (or fields) that are part of the file. This is helpful to know when adding a label to your map to show, for example, the name of the country. It also indicates that the field called name holds up to 255 characters. Therefore some of the names can be quite long, such as "Macedonia, The Former Yugo. Rep. of".

With this information you are ready to put together a basic map file.

    > ogrinfo countries_simpl.shp -al | grep name | sort | uniqLayer name: countries_simpl
      name: String (255.0)
      name (String) = Afghanistan
      name (String) = Albania
      name (String) = Algeria
      name (String) = American Samoa
    continued...

The map file is the core of MapServer applications. It configures how the map will look, what size it will be, and which layers to show. There are many different configuration settings. Map file reference documents on the MapServer web site are a necessary reference for learning about new features. You can find the documents at http://mapserver.gis.umn.edu/doc/mapfile-reference.html.

Map files are simple text files that use a hierarchical, or nested, object structure to define settings for the map. The map file is composed of objects (a.k.a. sections). Each object has a keyword to start and the word END to stop. Objects can have other subobjects within them where applicable. For example, a map layer definition will include objects that define how layers will be drawn or how labels are created for a layer. Example 10-2 shows the most basic possible definition of a map file, using only 15 lines of text.

MAP                         # Start of MAP object
  SIZE 600 300
  EXTENT -180 -90 180 90
  LAYER                     # Start of LAYER object
    NAME countries
    TYPE POLYGON
    STATUS DEFAULT
    DATA countries_simpl
    CLASS                   # Start of CLASS object
      STYLE                 # Start of STYLE object
        OUTLINECOLOR 100 100 100
      END                   # End of STYLE object
    END                     # End of CLASS object
  END                       # End of LAYER object
END                         # End of MAP object and map file

There are only four objects in this map file:

Figure 10-1 is a graphical representation of the nested hierarchy of objects and properties.

Figure 10-1. Some of the main objects used in a MapServer map file

These objects are nested within each other. Each object has different types of settings. The SIZE and EXTENT settings are part of the MAP object. The LAYER object has a NAME, TYPE, STATUS, and DATA setting. The CLASS object has no settings in this example, but holds the STYLE object, which defines what OUTLINECOLOR to draw the lines.

The DATA setting gives the name of the dataset used for drawing this layer. In these examples, the data is a shapefile called countries_simpl. The examples assume that the map file is saved in the same location that you are running the commands from. For more information on other data formats and how to use them in MapServer, see Appendix B.

Comments can be interspersed throughout the map file using the # symbol. Everything written after the symbol, and on the same line, is ignored by MapServer. Example 10-2 uses comments to show the start and end of the main objects.

Indenting lines is optional but recommended to make your map file more readable. This structure is treated hierarchically by indenting the start of an object and un-indenting the end of the object.

Keywords in the map file can be upper, lower, or mixed case. It is recommended to write object names (such as MAP) and other keywords (such as DATA, COLOR) in uppercase and any items that are values for settings in lowercase (such as filenames, layer names, and comments). This is personal preference, but the convention can make it easier to read.

The text of the map file must be saved into a file on your filesystem. The filename of a map file must have a map suffix. The map file in Example 10-2 was saved as a file named global.map.

Values needing quotations can use either single or double quotes. In many cases, quotes are optional. Filenames are a good example. They can be either unquoted, single quoted, or double quoted.

The MapServer command shp2img takes the settings in the map file and produces a map image. Example 10-3 and the later Example 10-4 show the syntax of the command as well as an example of how to run it with the global.map map file.

> shp2img
Syntax: shp2img -m [mapfile] -o [image] -e minx miny maxx maxy
                -t -l [layers] -i [format]
  -m mapfile: Map file to operate on - required.
  -i format: Override the IMAGETYPE value to pick output format.
  -t: enable transparency
  -o image: output filename (stdout if not provided)
  -e minx miny maxx maxy: extents to render - optional
  -l layers: layers to enable - optional
  -all_debug n: Set debug level for map and all layers.
  -map_debug n: Set map debug level.
  -layer_debug layer_name n: Set layer debug level.

Only the first two options (-m and -o) are used in the following example:

    > shp2img -m global.map -o mymap.png

This example produces a new file called mymap.png, shown in Figure 10-2.

Figure 10-2. Initial map image of country boundaries

When the image is created, you can view it with any image viewing software. Internet web browsers can usually view PNG, JPEG, GIF, and others.

Depending on where you got MapServer from or how you compiled it, the images you produce might not be PNG format by default. To explicitly request PNG output files, use the -i option, like:

    > shp2img -m global.map -o mymap.png -i PNG

If you get an error or an image that isn’t viewable, your copy of MapServer might not support PNG output. If so, try a JPEG or GIF format. Make sure you change the file extension of the output image to reflect the image format you choose, for example:

    > shp2img -m global.map -o mymap.jpg -i JPEG

For more assistance see the Setting Output Image Formats section at the end of this chapter.

The simple map outline used in the previous example is great for new users. With some simple additions to the map file, you can easily add labels to your map. Example 10-4 shows the additional lines required to do this.

MAP
  SIZE 600 300
  EXTENT -180 -90 180 90
  LAYER
    NAME countries
    TYPE POLYGON
    STATUS DEFAULT
    DATA countries_simpl
    LABELITEM 'NAME'
    CLASS
      STYLE
        OUTLINECOLOR 100 100 100
      END
      LABEL
                  MINFEATURESIZE 40
                  END
    END
  END
END

Four more lines were add to the country LAYER object.

               
    LABELITEM 'NAME'

This setting tells MapServer what attribute to use to label the polygons. Each country polygon has a set of attributes that can be used to create labels. The LABELITEM setting specifies which one is used. ogrinfo, discussed in Chapter 7, can output a list of the attributes available in the file.

The additional lines were very simple:

               
    LABEL
        MINFEATURESIZE 40
    END

The second line is optional but makes the map more readable. There are a lot of ways to control how labels are drawn by MapServer. The MINFEATURESIZE option allowed me to specify a minimum size (number of pixels wide) that a country has to be before it will have a label created for it. Therefore smaller countries don’t get labeled because they would be unreadable at this scale anyway. Playing around with the value used for MINFEATURESIZE will yield very different results; try changing it from 40 to 20 or even down to 10.

If the EXTENT line is changed to zoom in to a smaller part of the world, more labels will show because the size of the countries will be larger.

When you rerun the shp2img command as in Example 10-4, it now produces a world map with a few labels, as seen in Figure 10-3.

Figure 10-3. World map with country names as labels

The shp2img utility has several other options. One allows you to select a different map EXTENT to override what is defined in the map file. This is very handy because you don’t need to change the map file. Simply modify your command by adding the -e parameter and specify an extent as in the map file.

Before using the -e parameter you must choose an area to zoom in to. You can use the ogrinfo utility in concert with the ogr2ogr conversion tool. The ogrinfo command gives you only the overall extent of a given layer; it doesn’t report on the extent of a single feature. Therefore, you might want to extract only the features of interest and put them into a temporary shapefile. You can use the ogrinfo command on the new file and then throw the data away.

Example 10-5 shows an example of this utility assessing the extents of a country.

                  > ogr2ogr -where "name='Bulgaria'" bulgaria.shp countries_simpl.shp
                  > ogrinfo bulgaria.shp -al -summary

INFO: Open of 'bulgaria.shp'
using driver 'ESRI Shapefile' successful.

Layer name: bulgaria
Geometry: Polygon
Feature Count: 1
Extent: (22.371639, 41.242084) - (28.609278, 44.217640)
continued...

Using the -where option with ogr2ogr allows you to convert from one shapefile to a new one, but only transfer certain features, e.g., the boundary of Bulgaria. By running ogrinfo on that new file, you can see what Extent you should use in your map file to focus on that country. You can then use this extent in the shp2img command to create a map, as seen in Figure 10-4.

Figure 10-4. Zooming in to Bulgaria

Here is an example that uses this information with the -e option:

    > shp2img -m global.map -o mymap.png -e 22.371639 41.242084 28.609278 44.217640

This map shows Bulgaria and some of the surrounding countries.

If you want to zoom out further, decrease the minimum coordinates (the first pair of numbers) and increase the maximum coordinates (the second pair) by one or two degrees like this:

    > shp2img -m global.map -o mymap.png -e 19 39 31 46

The map in Figure 10-5 is zoomed out further, giving a better context for Bulgaria.

Figure 10-5. Zooming out of a map image by changing the extent in the shp2img command

With a few more lines in the map file, as shown in Example 10-6, you can create a better looking map. Here is a modified map file with a few lines added and a couple changed.

MAP
  SIZE 600 300
  EXTENT -180 -90 180 90
  IMAGECOLOR 180 180 250
  LAYER
    NAME countries
    TYPE POLYGON
    STATUS DEFAULT
    DATA countries_simpl
    LABELITEM 'NAME'
   CLASSITEM 'NAME'
    CLASS
      EXPRESSION 'Bulgaria'
      STYLE

        OUTLINECOLOR 100 100 100
        COLOR 255 255 150
      END
      LABEL
        SIZE LARGE
                  MINFEATURESIZE 40
      END
    END
    CLASS
      EXPRESSION ('[NAME]' ne 'Bulgaria')
      STYLE
        OUTLINECOLOR 100 100 100
        COLOR 200 200 200
      END
    END
  END
END

The shp2img command is the same as in the previous example, but produces a colored map showing Bulgaria more clearly. The command is:

    > shp2img -m global.map -o example6b.png -e 19 39 31 46

The extent given by the shp2img command is still zoomed in to Bulgaria. Remember that the -e option overrides the EXTENT setting in the map file.

The result of this map file is shown in Figure 10-6.

Figure 10-6. Simple color theming of countries, highlighting a particular polygon and setting a background color

A few things to notice are three different COLOR settings and the single label:

               
    IMAGECOLOR 180 180 250

This setting basically makes any place blue where there were no country polygons in the shapefile. IMAGECOLOR is the background color of the map image, which is white by default. In this case it makes an interesting background simulating water.

You may notice that in the map file there are two CLASS...END objects. One tells how to color and label Bulgaria. The other tells how to color all the other countries.

               
    CLASSITEM 'NAME'

This line sets you up to use multiple classes in your map file. In this case, it says that the NAME attribute is going to be used to filter out certain features on the map. This is done by specifying an EXPRESSION (more on expressions in the next section) for each class, like in the first class:

    CLASS
       EXPRESSION 'Bulgaria'
       STYLE
          OUTLINECOLOR 100 100 100
          COLOR 255 255 150
       END
       LABEL
          SIZE LARGE
       END
    END

When drawing this class, MapServer draws only the polygons that have a NAME attribute of 'Bulgaria'. All other polygons or countries aren’t drawn in this class. The COLOR setting tells MapServer to fill Bulgaria with a color, and not just draw the outline as before. The only other change in this class is that the label size has been explicitly set a bit larger than the default.

The second class tells how to draw all countries other than Bulgaria.

               
    CLASS
       EXPRESSION ('[NAME]' ne 'Bulgaria')
       STYLE
         OUTLINECOLOR 100 100 100
         COLOR 200 200 200
       END
    END

Notice that there is a more complex expression set for this class. This one ignores Bulgaria but draws all the other countries. The next section discusses expression concepts in more detail.

The FILTER and EXPRESSION keywords can use simple or complex expressions to define the set of features to draw. Example 10-6 showed the simple way to use EXPRESSION to define the features for a CLASS . In the example, a single text string is provided. It is quoted, but doesn’t need to be. MapServer will look for all occurrences of that string in whatever attribute is set by CLASSITEM .

Logical expressions can also be defined where more than one value in a single attribute needs to be evaluated. Ranges of values and combinations of attributes can be given. Table 10-1 gives a summary of the types of expressions that can be used.

There are some exceptions to this table’s above rules when using the FILTER option with some data sources, particularly with database connections such as PostGIS:

Creating expressions isn’t always easy. Here are a few rules to keep in mind:

An important part of any map is the legend describing what colors and symbols mean. MapServer can create legends in realtime when a map is produced, or as a separate image.

To add a legend to your map, you must add a LEGEND...END object to your MAP. Note that this isn’t part of a LAYER object. It is part of the overall map object settings. Example 10-7 shows the first few lines of the map file (for context) with a few legend-specific settings highlighted.

MAP
  SIZE 600 300
  EXTENT -180 -90 180 90
  IMAGECOLOR 180 180 250

  LEGEND
    STATUS EMBED
    POSITION LR
    TRANSPARENT TRUE
  END
...

The status setting can be set to ON, OFF, or EMBED. The EMBED option is a great way to add the legend directly to the map. If you don’t use EMBED, then you must create the legend as a separate image (as you will see in a moment). Setting the legend to have a transparent background is also a nice option. If you don’t want it to be transparent, then you can remove the TRANSPARENT TRUE line. A default white background will be drawn behind the legend.

One more change is required to make the legend draw. You must have NAME settings for each class. The name given will be the text shown in the legend next to the symbols for that class. For example, add NAME 'Bulgaria' to the first class and NAME 'All Countries' to the second class as in Example 10-8. Until you do so, no legend will be created.

...
    CLASS
      NAME 'Bulgaria'
      EXPRESSION 'Bulgaria'

      STYLE
        OUTLINECOLOR 100 100 100
        COLOR 255 255 150
      END
      LABEL
        SIZE LARGE
        MINFEATURESIZE 40
      END
    END
    CLASS
      NAME 'All Countries'
      EXPRESSION ('[NAME]' ne 'Bulgaria')
      STYLE
        OUTLINECOLOR 100 100 100
        COLOR 200 200 200
      END
    END
...

Rerunning the shp2img command as before creates the image shown in Figure 10-7.

Figure 10-7. An embedded legend on the map

The POSITION setting has a few basic options that tell MapServer where to place the legend on the map using a two-letter code for the relative position: lower-right (LR), upper-center (UC), etc.

The legends so far have been embedded in the map image, but you can also create a separate image file that just includes the legend. This is done with the legend command:

               
    > legend global.map legend.png

The legend command creates an image that has just the legend in it as shown in Figure 10-8. It takes two parameters after the command name: first, the map file name and then the output image filename to be created.

Figure 10-8. A legend image created by the legend command

The legend is created according to the settings in the LEGEND object of the map file. You can change certain settings, but the POSITION and EMBED options are effectively ignored. Those options are intended for use with shp2img or with the mapserv web application.

A scale bar is a graphic showing the relative distances on the map. It consists of lines or shading and text describing what distance a segment of line in the scale-bar represents. As with legends in the preceding examples, it is simple to add scale-bar settings to your map file. All the options for scale-bar settings are listed in the MapServer map file documentation, under the scale-bar object at http://mapserver.gis.umn.edu/doc/mapfile-reference.html#scalebar.

Example 10-9 highlights the eight lines added to the map file in previous examples.

MAP
  SIZE 600 300
  EXTENT -180 -90 180 90
  IMAGECOLOR 180 180 250

  UNITS DD

  SCALEBAR
    STATUS EMBED
    UNITS KILOMETERS
    INTERVALS 3
    TRANSPARENT TRUE
    OUTLINECOLOR 0 0 0
  END

  LEGEND
    STATUS EMBED
...

A scale bar converts the map distances (centimeters, inches, pixels) to real-world distances (kilometers, miles), as seen in the lower-left corner of Figure 10-9.

Figure 10-9. Map image with an embedded scale bar

The same method used in previous examples using shp2img created this map with the embedded scale bar:

    > shp2img -m global.map -o mymap.png -e 19 39 31 46

The first line added to the map file is the UNITS keyword. DD tells MapServer that the mapping data is represented in decimal degree coordinates/units. This setting affects the whole map file and isn’t just scale bar-specific, which is why it isn’t inside the SCALEBAR...END object.

The SCALEBAR object of the map file has several options. A few, but not all, of the options are used in this example. These are just enough to make a nice-looking scale bar without a lot of fuss. The STATUS EMBED option is just like the one used in the legend example earlier. It puts the graphic right on the map, rather than requiring you to create a separate graphic. The UNITS KILOMETERS specifies what measurement units are shown on the scale bar. In this case each segment of the scale bar is labeled in kilometers. This can be changed to inches, feet, meters, etc.

INTERVALS 3 makes three segments in the scale bar. The default is four segments. This is a handy option, allowing you to have control over how readable the resulting scale bar is. If you have too many segments crammed into a small area, the labels can become hard to read.

There is one important option not shown in the earlier example. SIZE x y is an option that explicitly sets the width (x) and height (y) of the scale bar. You can accept the default to keep it simple. Note that when specifying the number of segments using INTERVALS, it subdivides the width accordingly. If you want a large number of INTERVALS, you will probably need to increase the SIZE of the scale bar to make it readable.

The last two options in Example 10-9 are aesthetic. TRANSPARENT makes the background of the scale bar clear. OUTLINECOLOR creates a thin black outline around the scale bar segments.

If you don’t want to embed the scale bar in your map, change STATUS EMBED to STATUS ON and use the scalebar command-line utility to create a separate graphic image. It is used like the legend utility in previous examples. The following example shows how you use the command:

    > scalebar global.map scalebar.png

The command takes two parameters, a map filename and an output image name. Note that scalebar doesn’t have the same options as shp2img.

Figure 10-10 shows the image created by the command.

Figure 10-10. A simple scale bar graphic produced by a map file and the scalebar utility

Be sure not to scale the graphics if you are going to manually pull together the scale bar and map images for something like a publication or web page. If you change the size or scale of the scale bar and don’t adjust the map image accordingly, your scale bar will be inaccurate.

The final map file created for this example is shown in Example 10-10. The EXTENT value has been changed to reflect the extents used in the shp2img command in earlier examples.

MAP                         # Start of MAP object
  SIZE 600 300              # 600 by 300 pixel image output
  #EXTENT -180 -90 180 90   # Original extents ignored
  EXTENT 19 39 31 46        # Final extents
  IMAGECOLOR 180 180 250    # Sets background map color
  UNITS DD                  # Map units
  SCALEBAR                  # Start of SCALEBAR object
    STATUS EMBED            # Embed scalebar in map image
    UNITS KILOMETERS        # Draw scalebar in km units

    INTERVALS 3             # Draw a three piece scalebar
    TRANSPARENT TRUE        # Transparent background
    OUTLINECOLOR 0 0 0      # Black outline
  END                       # End of SCALEBAR object
  LEGEND                    # Start of LEGEND object
    STATUS EMBED            # Embed legend in map image
    POSITION LR             # Embed in lower-right corner
    TRANSPARENT TRUE        # Transparent background
  END                       # End of LEGEND object
  LAYER                     # Start of LAYER object
    NAME countries          # Name of LAYER
    TYPE POLYGON            # Type of features in LAYER
    STATUS DEFAULT          # Draw STATUS for LAYER
    DATA countries_simpl    # Source dataset
    LABELITEM 'NAME'        # Attribute for labels
    CLASSITEM 'NAME'        # Attribute for expressions
    CLASS                   # Start of CLASS object
      NAME 'Bulgaria'       # Name of CLASS
      EXPRESSION 'Bulgaria' # Draw these features in class
      STYLE                 # Start of STYLE object
        OUTLINECOLOR 100 100 100
                            # Color of outer boundary
        COLOR 255 255 150   # Polygon shade color
      END                   # End of STYLE object
      LABEL                 # Start of LABEL object
        SIZE LARGE          # Size of font in label
        MINFEATURESIZE 40   # Min. sized polygon to label
      END                   # End of LABEL object
    END                     # End of CLASS object
    CLASS                   # Start of CLASS object
      NAME 'All Countries'  # Name of CLASS
      EXPRESSION ('[NAME]' ne 'Bulgaria')
                            # Draw features in class
      STYLE                 # Start of STYLE object
        OUTLINECOLOR 100 100 100
                            # Color of outer boundary
        COLOR 200 200 200   # Polygon shade color
      END                   # End of STYLE object
    END                     # End of CLASS object
  END                       # End of LAYER object
END                         # End of MAP object and map file

Chapter 4 described how to access and install the MS4W package. You might want to look at the MS4W portion of that chapter and review how to start the web server. A custom application will be built later in this chapter, but first you need to understand how MapServer works in the MS4W environment.

MS4W comes with a version of the Apache HTTP web server. The MapServer program is stored in Apache’s cgi-bin folder, the main location for many web programs. If you were compiling your own mapserv.exe file, you install it by copying it into the cgi-bin folder. By default, this folder is located in the \ms4w\Apache\cgi-bin folder on the drive MS4W is installed on (e.g., C: orD:). There may be several versions of MapServer located there. For example, mapserv_36.exe is MapServer Version 3.6 (very out of date) and mapserv_44.exe is the most recent Version 4.4. Usually the more recent version will just be called mapserv.exe.

Preparing MapServer on Linux is also described in Chapter 4. Installing the MapServer CGI program is similar to how you do so for MS4W. The mapserv executable is simply copied (or linked) to Apache’s cgi-bin folder. For example, on SuSE Linux, the web server’s cgi-bin folder is located at /srv/www/cgi-bin. The mapserv application must be copied into this folder so it is accessible to the web server. These instructions also apply to non-MS4W installations of Apache on other platforms.

Configuring Apache to use MapServer doesn’t have to be complicated. If you put the mapserv/mapserv.exe program into the web server’s default cgi-bin location, there may not be much more to do to get the program running. The next section gives a couple of example tests to see if it is running properly.

There are other settings you will need in order to access maps produced by MapServer. When MapServer runs, it needs a temporary area to create the images for maps, legends, scale bars, etc. This temporary folder must also be accessible to the web so that users can view the images created by MapServer.

> chown wwwrun.www /srv/www/htdocs/ms_tmp

You can run a few tests to check that the MapServer program is properly set up. The set up of MS4W and Linux running Apache is very similar, but there are some differences worth mentioning.

No query information to decode. QUERY_STRING is set, but empty.

No query information to decode. QUERY_STRING is set, but empty.

To test that MapServer can actually create maps, you will build on the demonstration map files used with the command-line tools in Chapter 10.

The countries_simpl shapefile dataset can be downloaded as a compressed archive file from http://ftp.intevation.de/freegis/worlddata/freegis_worlddata-0.1_simpl.tar.gz.

The map file example from Chapter 10 will be customized further and made into a web-based application. To do so, there are three files involved:

Figure 11-1 illustrates how the basic application begins, with a start page sending settings to the CGI to produce a map.

Figure 11-1. The start page initializes MapServer by passing it a map file and an HTML template document

Example 11-1 takes the demonstration map file global.map, used in the previous chapter, and adds the settings required to make it a web map. The additional settings are highlighted.

MAP
  SIZE 600 300
  EXTENT -180 -90 180 90
  IMAGECOLOR 180 180 250

  UNITS DD

  SCALEBAR
    STATUS EMBED
    UNITS KILOMETERS
    INTERVALS 3
    TRANSPARENT TRUE
    OUTLINECOLOR 0 0 0
  END

  LEGEND
    STATUS EMBED
    POSITION LR
    TRANSPARENT TRUE
  END

  WEB
    TEMPLATE global.html
    IMAGEPATH "/srv/www/htdocs/tmp/"
    IMAGEURL "/tmp/"
 END

  LAYER
    NAME countries
    TYPE POLYGON
    STATUS DEFAULT
    DATA countries_simpl
    LABELITEM 'NAME'
   LABELMAXSCALE 50000000
    CLASSITEM 'NAME'
    CLASS
      NAME 'Bulgaria'
      EXPRESSION 'Bulgaria'
      OUTLINECOLOR 100 100 100
      COLOR 255 255 150
      LABEL
        SIZE LARGE
        OUTLINECOLOR 255 255 255
        MINFEATURESIZE 40
      END
    END
    CLASS
      NAME 'All Countries'
      EXPRESSION ('[NAME]' ne 'Bulgaria')
      OUTLINECOLOR 100 100 100
      COLOR 200 200 200
    END
  END
END

Only a few lines were added to make the map file work with the web server instead of command-line tools.

WEB
TEMPLATE global.html
IMAGEPATH "/ms4w/tmp/ms_tmp/"
IMAGEURL "/ms_tmp/"
END

A whole new object called WEB was added. There are three parts to the web object:

LABELMAXSCALE 50000000 was also added to the countries layer. This sets the map to show labels only when zoomed in to a certain map scale. The scale of the initial map is so small that Bulgaria is barely visible. Having a label on top of the country makes it harder to see; instead, as you zoom in to a more readable scale, the labels will appear.

With these map file settings in place, you can set up an initialization page. This page will be called index.html and its contents are listed in Example 11-2. The page can be called whatever you want.

<HTML>
<HEAD><TITLE>MapServer Test</TITLE></HEAD>
<CENTER><H2>MapServer Test</H2>

<FORM method=GET action="/cgi-bin/mapserv">
  <INPUT type="hidden" name="map" value="/srv/www/htdocs/global.map">
  <INPUT type="hidden" name="layer" value="countries">

  <INPUT type="hidden" name="zoomdir" value=1>
  <INPUT type="hidden" name="zoomsize" value=2>

  <INPUT type="hidden" name="program" value="/cgi-bin/mapserv">

  <INPUT type="submit" value="Start MapServer">
</FORM></CENTER></BODY></HTML>

This example is almost as stripped down as it can be. There is a title and heading on the page. Other than that, the rest of the HTML code is for starting MapServer. This page can be completely customized as long as the form and its variables are maintained.

All this page shows is a single button: Start MapServer. Behind the page are a bunch of hidden settings that are passed to MapServer when the form is submitted. This starts the first map. After the application is started, the index.html page isn’t used.

The MapServer CGI application sends the viewer a new web page. The URL to that web page contains several variables (like the ones defined in index.html). When a user requests a change to the map, it then sends those variables back to the CGI for reprocessing. The purpose of the index.html page is to get the whole process started without forcing you to have a complex-looking initial URL.

As you saw in Example 11-1, a template file called global.html is specified in the map file. This template file is also a web page written in HTML. MapServer takes this page and populates portions of it before sending it back to the user’s web browser. Example 11-3 shows my global.html code.

<HTML>
<HEAD><TITLE>MapServer Test</TITLE></HEAD>
<CENTER><H2>MapServer Test</H2>
<HR>

<FORM method=GET action="/cgi-bin/mapserv">
  <INPUT NAME="img" TYPE="image" SRC="[img]" width=600 height=300 border=0
               ALT="Map Image">

  <INPUT type=hidden name=zoomdir value=1 [zoomdir_1_check] >
  <INPUT type=hidden name=zoomsize size=4 value=[zoomsize]>

  <INPUT type="hidden" name="imgxy" value="[center_x] [center_y]">
  <INPUT type="hidden" name="imgext" value="[mapext]">
  <INPUT type="hidden" name="map" value="[map]">
  <INPUT type="hidden" name="savequery" value="true">
  <INPUT type="hidden" name="mapext" value="shapes">

</FORM></CENTER></BODY></HTML>

If you are familiar with HTML forms and tags, you may notice that the only objects visible on this page are the heading and title and an image. The image source (SRC) is filled in by MapServer in real time when the page is generated.

When MapServer populates global.html, it checks for any MapServer-specific variables, such as [img]. MapServer replaces this text with the URL to the map image on the web site. This is the temporary map image that MapServer created.

Figure 11-2 shows the output web page created by the global.html.

The map will look exactly like some of the map output from the command-line tools in Chapter 10. The only difference is that this map is being created by MapServer when requested, and automatically embedded into a web page.

The basic global.html template has virtually no controls, or at least none that are apparent. Controls refers to the buttons and check boxes you see on many web maps. These were deliberately left out so that this example would be simple to implement, and the HTML code wouldn’t be more confusing than necessary.

To interact with this map, just click on the map, and it will zoom in towards that location. Click once on the map, and then wait for the map to update. Once the image is updated, click again. Notice that if you zoom in toward Bulgaria, the label starts to appear. The results of clicking twice on the map are shown in Figure 11-3.

Because the number of controls has been kept to a minimum, there are no zoom-out buttons. In a web-mapping application this simple, the only way to zoom out is for

Figure 11-2. The basic global web map example

Figure 11-3. Zooming in to Bulgaria by clicking two times on the map

the user to go back in the web browser. This actually works reasonably intuitively because web page users are used to going back to previous pages.

If you’ve made it this far with your application, MapServer is set up and running well. Of course there are many other options and settings you can use. Some of these are covered in the next section when you start to make further customizations to the global map example.

In Chapter 10 you learned how to change the extents of the map when using the shp2img command-line utility. With an interactive map the extents can be changed by zooming in, just like the test example with the global map application. The initial map shown by that application covers the whole world. If you are interested only in a map covering a certain area, you will want to change the initial extent of the map to suit your area of interest.

You will continue to build on the previous examples in this chapter, including the global.map file. The EXTENT line in the map file specifies what the initial extent of the map will be when MapServer starts up. This was set to:

EXTENT -180 -90 180 90

which covers the whole world. Now you will set this to zoom in to a new area, to make a map of Canada. You will do so by continuing to use the countries_simpl.shp shapefile, and also use the ogr2ogr and ogrinfo tools to assess what extent you need. Please see the procedures for using ogr2ogr and ogrinfo in Chapter 10. Example 10-5 shows the same methodology for determining the extent of Bulgaria.

These command-line programs aren’t part of MapServer. They are part of the GDAL/OGR package described in Chapter 3. The ogr2ogr utility extracts the shapes of Canada and saves them in to a new shapefile. ogrinfo is then run to see what the coordinate extents of Canada are.

The new shapefile is used only as a temporary means of determining the coordinates of the area of interest. These coordinates are then set in global.map so that MapServer focuses on Canada.

The extent of Canada, as returned from ogrinfo, is:

Extent: (-141.000000, 41.675980) - (-52.636291, 83.110458)

You can put this extent into the global.map file and see how things look. Simply copy/paste this text right into the map file and then clean it up, removing brackets and commas. Example 11-4 shows how the first few lines of the changed application look.

MAP
  SIZE 600 300
  EXTENT -141 42 -52 83
...
    CLASS
      NAME 'Canada'
      EXPRESSION 'Canada'
      OUTLINECOLOR 100 100 100
      COLOR 255 255 150
    END
...

In this example, exact coordinates aren’t required. You can round them off or drop the decimals. Note the changes to the LAYER object. The class that highlighted Bulgaria now highlights Canada instead. The LABEL object has been removed from the CLASS object. Figure 11-4 shows the initial map produced by using these new extent settings.

The extents of this map are so tight that it is hard to really get the context of the map. It is zoomed in so tightly to Canada that it’s difficult to see any of the neighboring countries.

To make the map look a little nicer, increase the extent settings by five degrees. Here are the the initial and final extents:

Figure 11-4. The initial map with Canada’s extents specified in the map file

The values of the new extent aren’t just all increased or decreased. The minimum values (the first two numbers) are decreased because I want more of the south and west of the map to be shown. The maximum values (the last two numbers) are increased to show more of the north and east parts of the map. Increased here means made more positive, not just increasing the absolute value. This holds true for the western hemisphere north of the equator, and when using latitudes and longitudes. Figure 11-5 shows where the extents are on a map. Figure 11-6 shows the resulting map that uses the final extent.

If no PROJECTION objects are set for the map or the layers, MapServer assumes they are all in the same coordinate system. Therefore, no reprojection is required. For data in decimal degrees, MapServer uses a default map projection (a.k.a. Plate Caree). This default projection isn’t the best way to display this map because it distorts several properties of the map. A large part of Canada is in the polar region, which this projection specifically distorts.

Figure 11-5. Map of showing the initial and final extents used for a map of Canada

Figure 11-6. The map with slight changes to the extent to show Canada more clearly

...
  UNITS DD

  PROJECTION
                     "proj=latlong"
                     "ellps=WGS84"
  END

  SCALEBAR
  ...
  LAYER
    NAME countries
    TYPE POLYGON
    ...
    CLASS
      NAME 'All Countries'
      OUTLINECOLOR 100 100 100
      COLOR 200 200 200
    END
    PROJECTION
                     "proj=latlong"
                     "ellps=WGS84"
    END
  END
END

PROJECTION
  "init=epsg:42304"
END

PROJECTION
  "proj=lcc"
  "ellps=GRS80"
  "lat_0=49"
  "lon_0=-95"
  "lat_1=49"
  "lat_2=77"
  "datum=NAD83"
  "units=m"
  "no_defs"
END

<42304> +proj=lcc +ellps=GRS80 +lat_0=49 +lon_0=-95 +lat_1=49 +lat_2=77 +datum=NAD83 +units=m no_defs <>

Modifying the map extent

Just changing the map projection won’t give you a working map. You still need to change the extent settings for the map. These need to be set in meter units because the projection in the example uses meter units (units=m) rather than decimal degrees. How do you choose what extent to use? This is where it helps to know a bit about map projections, although some simple guessing and testing of extent values is perfectly valid too.

Here is one way to help determine what extent you want to have. The extents will be set in meter units, relative to the latitude of origin and central meridian of the projection. These details are listed in Example 11-6. The central meridian is -95° longitude, and the latitude of origin is 49° north. When the extent of the map is set, the southwest and northeast corners will be the distance, in meters, from the central point: -95°, 49°. For example

EXTENT -3000000 -1000000 3000000 1000000

sets the extent to start at 3,000 km west and 1,000 km south of the central point, and extend to 3,000 km east and 1,000 km north. If you go back to Figure 11-5, you can use the map grid to help determine where the center point is. It is centrally located but south of the center of the country, along the U.S. border. Now you can decide how wide and tall you want your extent to be. Figure 11-6 is a good map to give you an idea of distances. The scale bar provides a reference for the width of Canada. Setting an extent that is 6,000 km wide isn’t unreasonable. Figure 11-7 shows the resulting map using the above extents.

Figure 11-7. An initial guess for setting the map extents using an LCC projection of Canada

The initial guess wasn’t too bad, though you can see that the map is shifted too far south and not far enough east. Through a process of tweaks and changes, you can determine an optimal extent to use. For example, you can decrease the minimum y and increase the maximum y values in the extent. Test out a few variations. Here is one extent that works well:

EXTENT -2400000 -900000 3100000 4000000

With these extents, MapServer produced the map shown in Figure 11-8. Grid lines were added to the map to show the difference in the shape of features that the projection change makes. Compare it to the regular rectangles in Figure 11-6.

Figure 11-8. Final map extents set for a map of Canada

There is a lot of extra space on the left and right sides of the map in Figure 11-8. This can be easily fixed by changing the size of the map image.

This mapping application was originally set up to show the whole world using a global project, which works great assuming the world map is twice as wide as it is tall. The map SIZE setting has been 600×300 throughout these exercises. That’s a width to height ratio of 2 to 1. The previous map shows that Canada is roughly square using that LCC map projection. You can change the size of your map to be roughly 1 to 1, and the map will fit much better to the extents of Canada. Change the size setting to something like 400×400 or 600×600, and see how it looks. This is done by changing the SIZE setting near the beginning of the map file: SIZE 600 600.

The resulting map is shown in Figure 11-9. Notice how much better Canada fits into the map image.

Before you can start mapping this, you need to change the image dimensions used in the HTML template file, global.html. The image width and height was hardcoded. To make the map more flexible, you can replace the hardcoded image dimensions with MapServer variables. This allows the HTML template to dynamically set the image dimensions based on the settings in the map file.

To use the MapServer variables instead, change line 7 in global.html. Replace the width and height numbers with the [mapwidth] and [mapheight] variables. It should look like this:

<INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]" border=0 ALT="Map Image">

Figure 11-9. Map of Canada with a map SIZE setting ratio of 1:1

Likewise, you need to change the imgxy variable to automatically use the center of the image instead of the hardcoded center pixel value:

  <INPUT type="hidden" name="imgxy" value="[mapcentroidx] [mapcentroidy]">

So far, the application has only one real tool. You can point and click to zoom in to an area. You haven’t been able to zoom out (other than by hitting the Back button in your web browser) or move the map sideways to recenter your view. Now you’ll add add three options to the web page, one for zooming in, another for zooming out and one to recenter the map on a new location.

If you are already familiar with HTML forms, this will be a snap. All you’re doing is adding an HTML form control that passes another CGI variable to the MapServer program. In the application so far, zooming was hardcoded. Instead, you will make a three-way option using three radio buttons.

Radio buttons are different from check boxes and normal buttons. When multiple radio buttons have the same name, only one can be selected at a time. This works perfectly for the task of selecting a single tool or option.

Example 11-7 shows the modified HTML template file, global.html, and Figure 11-10 shows the resulting web page from the exercise.

Figure 11-10. Adding some basic map controls to the web page

<HTML>
<HEAD><TITLE>MapServer Test</TITLE></HEAD>
<CENTER><H2>MapServer Test</H2>
<hr>

<FORM method=GET action="/cgi-bin/mapserv">
  <INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]"
               border=0 ALT="Map Image">
  <BR>

  Zoom In
  <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >

  Re-center
  <INPUT type=radio name=zoomdir value=0 [zoomdir_0_check] >

  Zoom Out
  <INPUT type=radio name=zoomdir value=-1 [zoomdir_-1_check] >

  Zoom Size
  <INPUT type=text name=zoomsize size=4 value=[zoomsize]>

  <!-- Remove the following three lines
  <INPUT type=hidden name=zoomdir value=1 [zoomdir_1_check] >
  <INPUT type=hidden name=zoomsize size=4 value=[zoomsize]>
  -->

  <INPUT type="hidden" name="imgxy" value="[center_x] [center_y]">
  <INPUT type="hidden" name="imgext" value="[mapext]">
  <INPUT type="hidden" name="map" value="[map]">
  <INPUT type="hidden" name="savequery" value="true">
  <INPUT type="hidden" name="mapext" value="shapes">

</FORM></CENTER></BODY></HTML>

First, the radio button settings were added to the form. These are spaced out in the code example to try to show them more clearly. All three are very similar. Text will be shown beside the button, and the form code defines what each button does. The first two changed lines are formatting and labeling of the button:

<BR>
Zoom In

The <BR> tag acts as a new line, so that the tools are displayed underneath the map image. The words Zoom In start on a new line and are next to the radio button itself. The radio button is defined by the tag:

  <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >

The <INPUT...> tag is part of the CGI form on this page. It has three settings:

The final piece of text in the INPUT tag is: [zoomdir_1_check]. This is a piece of text that is replaced by MapServer when the HTML page is created. This is similar to the [img] variable used to draw the map in the page. MapServer replaces these placeholders with values after creating the map. In this case, it replaces the text with the word checked beside the button that was pressed last. If you click on Zoom In, then click on the map, it should zoom in to where you clicked on the map. At that point the Zoom In tool will still be selected. That is because it is now marked as checked. You can see this in the HTML behind the page showing the map:

<INPUT type=radio name=zoomdir value=1 checked >

If you select the Re-center button, it marks the second radio button with the checked setting:

<INPUT type=radio name=zoomdir value=0 checked >

This allows the web browser to maintain the options you selected when it draws a new map or refreshes the page.

The only other line added was to enable the box to enter in a Zoom Size:

               Zoom Size
  <INPUT type=text name=zoomsize size=4 value=[zoomsize]>

This setting tells MapServer how much to zoom in (or out) when a user clicks on the map. For example, a zoom size of 2 doubles the scale and makes features on the map appear twice as large. This was hardcoded into a hidden variable before adding the controls. These lines can now be removed from the HTML template. The zoomdir setting was also hardcoded to value=1, so that any time a user clicked on the map it only zooms in. With the new controls just added, these lines are no longer required:

               <INPUT type=hidden name=zoomdir value=1 [zoomdir_1_check] >
  <INPUT type=hidden name=zoomsize size=4 value=[zoomsize]>

One change is also required in index.html. In the earlier examples, the default action was to zoom in. You had to set the hidden zoomdir variable to value=1, which MapServer interprets as zoom in. By changing this to value=0 (zero), it makes the default action be recenter instead of zoom. This will become more important by the end of this chapter when we study the redraw button. If you hit redraw, and zoom in is selected by default, the map will not only redraws, but also zooms in. Here is the changed line in index.html:

<INPUT type="hidden" name="zoomdir" value=0>

Zoom and recenter features are critical for most web mapping applications. Many users also like the ability to control what layers they see. Those using the application will need some level of control. Being able to turn layers on and off is a key part of many MapServer applications. Try to give users as much freedom to explore their maps as possible, but also try to prevent them from making major mistakes. For example, if you give complete control and allow them to turn off every layer, the map will be empty. They got what they asked for but may think that your application is broken. You will have to decide how important complete control is versus having things a bit more restrictive but predictable.

Before you get into setting up layer selection options, you need to create a new layer in the global mapping application. You could find some images to include or another shapefile showing the locations of places of interest. To keep it simple, the following example is going to create a layer that shows text labels for the countries. You can do this using the same countries_simpl shapefile dataset that is already being used in the application. Example 11-8 shows the new layer created in global.map. The new layer is called country_labels. Instead of drawing polygons or lines, tell it to only draw labels by setting TYPE ANNOTATION.

  LAYER
    NAME country_labels
    TYPE ANNOTATION
    STATUS DEFAULT
    DATA countries_simpl
    LABELITEM 'NAME'
    CLASS
      LABEL
        COLOR 255 255 255      
        OUTLINECOLOR 0 0 0
        POSITION CC
        MINFEATURESIZE 100
      END
    END
    PROJECTION
      "proj=latlong"
      "proj=WGS84"
    END
  END

With MapServer, you can set layers to be drawn two ways. One way is to force the map to always draw the layer. This is done by setting the layer to STATUS DEFAULT. The other way is to have it turned on only when requested. In this case you can set it to STATUS OFF. If a layer is set to OFF in the map file, it doesn’t mean it will never be drawn. If the layer is requested to be drawn by the web page, then it will be.

Right now there are two layers in the map file: countries and country_labels. To have the country boundaries always shown, leave the countries layer STATUS set to DEFAULT. But for country_labels, set it to STATUS OFF. This allows the user to turn off the labels.

The next place you make changes is in the index.html page. The settings in this page tell MapServer which layers to draw when drawing the first map. This is different from setting the layer to be on by default in the map file. Instead, the index.html page will pass a list of layers to draw through to the MapServer program. If the layers are available in the map file, it will request to see them. You will see the names of the layers embedded in the URL as CGI values (e.g., &layers=countries). MapServer uses these parameters to determine which layers to draw.

Back in Example 11-2 you saw the initial settings for index.html. That included this line:

  <input type="hidden" name="layer" value="countries">

Having this line as part of the initialization form meant that MapServer would be requested to draw the countries layer when the first map is drawn. Considering that the layer is already set to draw by default, this setting becomes redundant. countries will be drawn all the time anyway, and the user won’t be able to turn it off. However, keep this line, and copy it for use with the new layer that shows the labels:

  <input type="hidden" name="layer" value="country_labels">

Now when the map starts up, both layers will be drawn. If you don’t want any layers other than those set with STATUS DEFAULT to be drawn, just remove any of the lines in index.html, where name="layer".

The third place to set up layer options is in the HTML template file (global.html). MapServer puts the map image into this HTML page and displays any of the controls you want to have in your application, including a list of layers to choose from. This is the most labor-intensive part of the exercise, but it is important. This is where the user will actually see some options. The settings in global.map and index.html are hidden from the user (except in the URL) but anything shown in the HTML template page will be for the user to see.

The HTML template page already has a form defined on it. All you need to do is add in a few more controls, also known as select options. To have these displayed on the right side of the map, put the code right after the <INPUT...> tag that draws the map. Make sure there are no line breaks <BR> between the select controls and the map if you want them to be side by side. Make sure that a <BR> tag follows the select list so that the zoom/recenter controls are below everything else. Example 11-9 shows the first few lines of HTML, including the start of the SELECT tag which is needed for the layer list.

...
<FORM method=GET action="/cgi-bin/mapserv">
  <BR> <INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="
  [mapheight]" border=0 ALT="Map Image">
  <SELECT multiple name="layer" size=3>
  <!--the list of layers to chose from will go here -->
  </SELECT>
  <BR>
    Zoom In <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >
...

So far the list won’t do anything. Next you need to add an entry for the country_labels layer. You should also add some text that will be displayed near the list to describe what the list is showing. Each layer that you want to show in the list needs an <OPTION...> tag like this:

<OPTION value="country_labels" [country_labels_select]> Country Names</OPTION>

The pieces specific to the application have been highlighted. The first setting, value="country_labels", is the name of the layer that will be drawn when this entry is selected from the list.

The second setting [country_labels_select] is necessary for the web page to highlight layers you have selected on previous maps. This is similar to the checked settings used when creating the radio buttons for zoom/recenter. This setting should be the same as the value setting, but with _select added to it.

The third item added is the text Country Names. This is outside of the <OPTION...> tag and is text to be written on the web page. The text put here can be whatever you want it to be. It will be used as a label for this layer in the select list on the web page. With all these changes, the new web page looks like Figure 11-11.

The complete global.html file looks like Example 11-10. In the final global.html, some text describing how to use the list and what it is for has been added. A few of the tags are moved around to make the page a bit more structured.

Figure 11-11. The layer select list added to the map page

<HTML>
<HEAD><TITLE>MapServer Test</TITLE></HEAD>
<CENTER><H2>MapServer Test</H2>
<HR>

<FORM method=GET action="/cgi-bin/mapserv">
    Zoom In <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >
    Re-center <INPUT type=radio name=zoomdir value=0 [zoomdir_0_check] >
    Zoom Out <INPUT type=radio name=zoomdir value=-1 [zoomdir_-1_check] >
    Zoom Size <INPUT type=text name=zoomsize size=4 value=[zoomsize]><BR>
  <INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]"
  border=0 ALT="Map Image"><BR>
  <B>Select Layers to Display: </B><BR>
	  Press "CTRL" and Click to select more than one<BR>
  <SELECT multiple name="layer" size=3>
    <OPTION value="country_labels" [country_labels_select]> Country Names</OPTION>
    <OPTION value="countries" [countries_select]> Country Boundaries</OPTION>
  </SELECT>

  <INPUT type="hidden" name="imgxy" value="[center_x] [center_y]">
  <INPUT type="hidden" name="imgext" value="[mapext]">
  <INPUT type="hidden" name="map" value="[map]">
  <INPUT type="hidden" name="savequery" value="true">
  <INPUT type="hidden" name="mapext" value="shapes">

</FORM></CENTER></BODY></HTML>

The natural next question is, how do you make the map redraw after choosing new layers? You can use the zoom or recenter tools, and it will update the map, reflecting this change, but this is hardly intuitive. The easiest way is to add a button to the page that requests a new map. HTML forms have a submit button you can use. Add this code to global.html, right after the end of the select list </SELECT>:

<BR><INPUT type="submit" value="Redraw/Update">

Now a button will appear right under the select list, as shown in Figure 11-12. You can select or deselect a layer, press the button, and see the change on the new map.

Figure 11-12. Adding a submit button to the web page to request a new map

Congratulations. You have created your own interactive web mapping applications. There is a lot more to learn but you know the basics of creating interactive maps. The rest of the chapter provides a few more tweaks and tips for further developing your application.

A legend is another key component of web mapping application and is very simple to add. It only takes a minute to modify your code to add a legend graphic to the page. The legend is a small graphic showing what colors and styles are being used to draw the map layers. So far in this example application you’ve used an embedded legend that is part of the map image. Now you will pull that legend out of the map image and have it drawn separately on the page. This requires two changes: one modification of the global.map file to remove the embedded legend and an addition to the global.html file to draw the legend on the page.

# Original legend
  LEGEND
    STATUS EMBED
    POSITION LR
    TRANSPARENT TRUE
  END
#-------------------
# Modified legend
  LEGEND
    STATUS ON
  END

<BR><HR>
<B>Legend</B><BR>
<IMG src="[legend]" alt="Map Legend"><HR>

<A HREF="[legend]" TARGET="_blank"><B>View Legend</B></A>

Scale bar images are created through the same process as legend images. When the scale bar isn’t used as an embedded image, it is created as a separate image. MapServer then inserts it into the HTML template wherever it finds the [scalebar] variable.

To global.html add one simple line, just like with the legend. Place it below the map image so that it is near enough to be useful for measuring. This is shown in Example 11-13.

Figure 11-13. Legend graphic added as a separate entity on the web page

Figure 11-14. Creating a link to the legend graphic

<INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]"
             border=0 ALT="Map Image"><BR>

<IMG src="[scalebar]" alt="Map scale bar"><BR>

<B>Select Layers to Display: </B><BR>

In the SCALEBAR object of the global.map file, change STATUS EMBED to STATUS ON so that the scale bar is no longer shown on the map image itself.

The final outcome looks like Figure 11-15.

Figure 11-15. A scale bar graphic added to the web page

Just like a legend and scale bar, a reference map image can be created at the same time as a map and added to your application. This requires a bit more forethought and some preparation. You need to keep in mind the purpose of your reference map. Typically, it is used for two purposes.

The primary purpose is showing where you are zoomed in to, relative to the original extent of the map. For example, Figure 11-16 shows a MapServer-based web site (http://www.gommap.org) that uses a reference map to orient users to their current view of the map.

Figure 11-16. Gulf of Maine web mapping application showing reference map

Reference maps can also be used to recenter the main map. If you want to view a different area, just click on the reference map, and the main map will recenter on that location. This feature is particularly helpful when you want to maintain the scale of your map but move to another location. Rather than using the recenter tool on the main map over and over again, just one click in the reference map takes you there.

Adding a reference map to your application follows a similar process to adding a legend or scale bar. You add a REFERENCE object to your map file and some code to the HTML template (e.g., global.html). The only other requirement is an image file to use for the reference map. It isn’t generated with a map file or layers but is a static background map image.

You can download a small world map image in PNG or GIF format from:

The image is shown in Figure 11-17.

Figure 11-17. A reference map image

Now, save the image in the same folder as the global.map map file. Add the code highlighted in Example 11-14 to the map file. I recommend you do so somewhere near the beginning. In this example, it is shown between the LEGEND and PROJECTION objects.

...
  LEGEND
    STATUS EMBED
    POSITION LR
    TRANSPARENT TRUE
  END

  REFERENCE
    STATUS ON
    IMAGE keymap.png  # This could be keymap.gif instead
    EXTENT -180 -90 180 90
    SIZE 241 121
    COLOR -1 -1 -1
    OUTLINECOLOR 255 0 0
  END

  PROJECTION
    "proj=latlong"
...

The reference image file doesn’t have geographic coordinates saved in the file. Instead, you must specify what the extent coordinates are using the EXTENT setting. This tells MapServer that the keymap.png image covers the globe. The SIZE setting tells how wide and tall the image is (in pixels). These two settings allow MapServer to find a specific coordinate location on the reference map image. If your reference map doesn’t seem to work properly, one of these two settings may be incorrect.

When the reference map is used, it draws a rectangle on top of the keymap.png image. The COLOR setting sets what color that rectangle will be. It is red by default. COLOR -1 -1 -1 tells MapServer to not color the rectangle, but to make it transparent. The OUTLINECOLOR setting gives the rectangle a red outline.

The REFERENCE object doesn’t have projection settings. This means that the EXTENT is always specified in the same units as the output map projection. This example really only works with a map that is displayed in the lat/long projection used at the beginning of this chapter. Also, the extents will not be specified in meter units for the LCC projection used earlier. Instead, the units must be set to UNITS DD for this example to work. The map EXTENT will need to be in decimal degrees.

The global.html template file needs to be modified as well. There are two ways to do this. The first is to include another <IMG> tag, like <IMG SRC="[ref"]>. This creates a simple reference map. The other way to add the reference map lets you click on the reference map to recenter your map. Use this code instead of the previous:

<INPUT name="ref" TYPE="image" SRC="[ref]" width="241" height="121" ALT="Reference map">

This shows the image and also sets it up to take a click and change the main map image. If you add it right after the main map image, you will have a web page that looks similar to Figure 11-18. All the layer controls have been removed, and the legend and scale bar were switched back to embed.

There are various reasons for sharing and accessing map data using web services. A government or large corporation may make map data available so that other divisions or departments don’t need to store their data locally. Consider the cost savings often touted for centralizing data storage. If data is centralized, the users still need to access it. Web services for mapping make the data available.

Perhaps someone is willing to share data with you but can’t allow you to have a complete copy, for whatever reason. A web service can facilitate that. Some map data, such as hurricane locations, is constantly changing. Downloading that data might not be possible or timely. Integrating a layer in your map that accesses a web service in realtime might be the answer. Some data repositories are so large that it would be unrealistic to copy them to your location. Web services can make that data available for you at the time you need it. This helps reduce the need for continual data storage upgrades. Figure 12-1 illustrates the basic function of a MapServer application accessing remote data through a web services request.

Whether sharing or accessing, it is all about making the most of our time and resources. Continually changing an application to point to new data can be inefficient. Storing large amounts of data locally may also be an unreasonable option.

Some service providers sharing data will never use the information internally. For example, think of a government agency that makes mapping data available to the public. The public benefits by having free and open access to mapping information. The government benefits by successfully fulfilling their mandate. Providing web services for mapping data can require a serious commitment to openness and support for clients.

On the other end of the spectrum, a company might share data internally and never share it with the public. Web services don’t require that the data be publicly accessible. Services can be securely guarded like any other web page or internal application. Large corporations may use services internally to make data broadly accessible