Envinsa. Version 4.1 PRESENTATION SERVICE REFERENCE

Transcription

1 Envinsa Version 4.1 PRESENTATION SERVICE REFERENCE

2 Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of MapInfo Corporation, One Global View, Troy, New York MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of MapInfo Corporation and/or its affiliates. MapInfo Corporate Headquarters: Phone: Fax: Sales: Government Sales: Technical Support: MapInfo UK and EMEA Headquarters: Phone: Fax: Technical Support: MapInfo Asia Pacific Headquarters: Phone: Fax: Technical Support: Contact information for all MapInfo offices is located at: Copyright 2006 The Legion Of The Bouncy Castle Copyright IPDR Organization All Rights Reserved Copyright 2006, International Business Machines Corporation and others. All Rights Reserved. Copyright 2006 Open GIS Consortium, Inc., All Rights Reserved. Copyright 2006 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This product includes software developed by the Apache Software Foundation ( Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Adobe Acrobat is a registered trademark of Adobe Systems Incorporated in the United States. Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark. February 8, 2007

3 Table of Contents Chapter 1: Introduction What is the Presentation Service? Presentation Service Functionality Chapter 2: Creating and Modifying Maps Describing the Service Capabilities Describing the Available Resources Rendering Preference (Anti-aliasing) Returning a Simple Basemap Simple Zooming by Changing Map Bounds Panning and Zooming by Screen Context Changing the Output Format (SVG Support) Creating a 3D Map (VRML Controls) Adding Scale Bars to your Map Creating a WBMP Map Chapter 3: Overlaying Features Overlaying Points of Interests Overlaying a Route Geometry Overlaying a Geometry Overlaying and Stylize a Polyline Overlaying Two Maps Chapter 4: Thematic Mapping Capabilities Thematic Mapping Concepts Feature Versus Label Themes Planning for Thematic Mapping Override Feature Theme Override Theme Label Control Ranged Feature Theme Ranged Label Theme Individual Value Theme Adding Theme Legends Adding Cartographic Legends

4 Chapter 5: Layer and Label Control Capabilities Layer Concept Map Features as Layers Static Layers Defining Named Layers Defining Analysis Layers (Charts) Bar Chart Layers Pie Chart Layers Defining Raster Layers (WMS Layer) Setting the Layer Order Defining Content Layers and Filters in the Request Adding Custom Styles to Your Layers Setting the Display Range of Your Layers Labeling Your Map Layers Chapter 6: Presentation Service Fundamentals Mapping Concepts Maps Tables Layers Features Labels and Legends Themes Hints and Tips Service Standards Compliance Functionality Limitations Chapter 7: Presentation Service Configuration Payload Constraints Rendition Preferences Setup Preferences Dynamic Layer Preference Static Layer Preferences Envinsa 4.1

5 Introduction 1 Welcome to the MapInfo Envinsa Platform Web Services. This guide provides descriptions and examples for the developer who is writing applications that will access the Presentation Service. The Presentation Service renders geographic information for display on a mobile terminal or desktop station. In this section: What is the Presentation Service? Presentation Service Functionality

6 What is the Presentation Service? The Presentation Service provides the capability of creating mapping images from geographic data. The data can be stored in MapInfo TAB files, in an RDBMS, or in an OGC Geographic Meta Language format. Multiple image formats (for example, GIF, JPEG, PNG, SVG, BMP, and WBMP) are supported. A map image may be returned as a Base64 encoded document in the response or created and deposited into an image repository and then referenced via a URL. Any OpenLS application may call upon this service to obtain a map of a desired area, with or without map overlays that depict one or more OpenLS ADTs, such as route geometry, point of interest, area of interest, location, position, and/or address. The service may also be employed to render route instructions, Content Manger data (CMLayer), or a WMS image. The Presentation Service also has additional functionality regarding icons or symbols. A request can include a list of icon definitions. This enables the map image returned to have features at each specified location. An icon can be a point such as a pin marker, or a polygon, to represent a route. The Presentation Service domain, named resources, and data is separated into several data components. The named resource JNDI root and sample data is separated into three individual components: NamedResource, SampleMapData, and MapDisplay3D. New Functionality in Envinsa 4.0 In the Envinsa 4.0 Presentation Service, the following new functionality has been implemented: Creation of Bar Charts and Pie Charts as Analysis layers. Allows for query of layer properties in a get capabilities request. Allows you to specify rendering preferences (speed or quality). Creation of 3D maps, allowing for fly-by and fly-through of your data. Anti aliasing support, for improved look of maps. Extended the overlay capabilities to allow WMS (raster) and polyline overlays. Allows for filter definitions (template and inline) on your Content Manager data. Allows for the creation of maps using WBMP and BMP mime types. Allows remote named resources management through the new Map Manager utility. Managing Your Named Resources Included with the Envinsa deployment is the Map Manager utility. The Map Manager is a graphical user interface that allows you to manage various aspects of your map resources and styles. The Map Manager is run as an application, either locally or remotely. The Named Resources section is the location for managing resources that have been given a unique name, or alias. Here you can create named maps and named layers, and access your customized named renditions (styles). These named resources are most often used in Envinsa. Named maps and styles allow you to define map display, map overlays, and thematic renditions in the Presentation Service. 6 Envinsa 4.1

7 Chapter 1: Introduction Presentation Service Functionality The Presentation Service offers a wide range of mapping functionality. This guide explains a subset of the full capability list of the Presentation Service. For more information on this services capabilities and a full list of functionality, see the Java Doc and NDoc API documentation or the Envinsa schema included in the SDKs. Get Capabilities and Resource Metadata The Presentation Service allows you to determine the services supported spatial reference systems, available layers for a particular basemap, available image formats, available styles (brush, pen, fonts), and all of the other available basemaps, named layers, grid layers, dynamic layers, spatial contents and their boundaries. Once you have listed the services resources, you can perform queries to return metadata (column names and types), default layer labeling configuration (text expressions, font information, and position), bounds, and rendering options. Listing and querying the services resources is valuable for determining the available filters for a content, listing the available styles to customize your map, and listing all of your available layers and rendering options to create the best maps possible. The following sections highlight potential ways to apply these capabilities: Describing the Service Capabilities in Chapter 2 on page 12. Describing the Available Resources in Chapter 2 on page 14. Rendering Preference (Anti-aliasing) Anti-aliasing has been added to the Presentation Service. This enables you to specify anti-aliasing (rendering preference) for map rendering in Presentation Service requests by specifying quality of the map or speed of map creation. In addition to a service request, you can set anti-aliasing in the Presentation Service configuration. The following sections highlight potential ways to apply this capability: Rendering Preference (Anti-aliasing) in Chapter 2 on page 17 Payload Constraints in Chapter 7 on page 133 Basemaps and Adding Layers The building blocks for any map are the basemap and the layers that you add to that map. The basemap consists of a predefined set of layers and features. You can control the basemap by determining the layers that are to be included or excluded from the basemap in the request. In addition to the basemap you can add various types of layers and control the style and display of those layers. The following sections highlight potential ways to apply these capabilities: Returning a Simple Basemap in Chapter 2 on page 18. Defining Named Layers in Chapter 5 on page 89. Setting the Layer Order in Chapter 5 on page 107. Setting the Display Range of Your Layers in Chapter 5 on page 117. Presentation Service Reference 7

8 Presentation Service Functionality Adding Custom Styles to Your Layers in Chapter 5 on page 116. Labeling Your Map Layers in Chapter 5 on page 118. Pan and Zoom There are numerous ways to pan and zoom a map. Panning is the process of re-centering the existing map, while zooming is the process of displaying a defined area of a map at a given distance or within a given bounds. The following sections highlight potential ways to apply these capabilities: Simple Zooming by Changing Map Bounds in Chapter 2 on page 20. Panning and Zooming by Screen Context in Chapter 2 on page 23. Analysis Layers (Pie and Bar Charts) Both pie and bar charts are particularly useful for analyzing demographic data. For example, you have a dataset of demographic information for the world. Your dataset shows the populations of several major demographic groups. Using pie charts, you can show the population of each demographic group, and see what fraction of the pie it makes up. The following section highlights a potential way to apply this capability: Defining Analysis Layers (Charts) in Chapter 5 on page 91. WMS Support The Presentation Service allows you to consume the output from a WMS GetMap response in two forms: an overlay or a raster layer. These capabilities are very useful to display satellite images, important features, or weather map from the WMS response. The following sections highlight potential ways to apply these capabilities: Overlaying Two Maps in Chapter 3 on page 50. Defining Raster Layers (WMS Layer) in Chapter 5 on page 104. Overlays The Presentation Service supports the four basic types of OpenLS overlays: route geometry, position, point of interest, and maps. In addition to these four types, the Presentation Service has extended the position overlay to allow polylines or linestrings to be used as overlays. Overlays are very useful to render and stylize features not defined within the generic map display. Here you can add a WMS image, a route geometry, a point of interest, or a polyline and define custom styles and display settings for each. The following sections highlight potential ways to apply these capabilities: Overlaying Points of Interests in Chapter 3 on page 42. Overlaying a Route Geometry in Chapter 3 on page 43. Overlaying a Geometry in Chapter 3 on page 44. Overlaying and Stylize a Polyline in Chapter 3 on page Envinsa 4.1

9 Chapter 1: Introduction Overlaying Two Maps in Chapter 3 on page 50. WBMP and SVG Image Support The Presentation Service supports both WBMP and SVG image formats, in addition to GIF, JPG, PNG, and BMP. By giving you the ability to control your image output format, you can create maps, legends, and scale bars to be displayed for a wide range of custom applications. The Presentation Service output can be used for wireless phones or handheld devices, desktop applications, or used for documents. The following sections highlight potential ways to apply these capabilities: Changing the Output Format (SVG Support) in Chapter 2 on page 29. Creating a WBMP Map in Chapter 2 on page 37. Filters and Content Layer Support The Presentation Service can access and render Content Manager spatial data. The CMLayer provides content accessibility and visualization, exposing a set of powerful spatial and attribute query interfaces. These capabilities allow access and mapping of your data through various filter constructs that are previously defined in the Content Manager or allow you to define a custom filter in the request. The following section highlights a potential way to apply this capability: Defining Content Layers and Filters in the Request in Chapter 5 on page D Mapping The Presentation Service allows you to create 3D maps and view your map data in an interactive 3D environment with fly-through, pan, and zoom functionality. Using your elevation data to create the 3D map, all of your 2D named layers can be draped, providing a valuable visual analysis capability. The following section highlights a potential way to apply this capability: Creating a 3D Map (VRML Controls) in Chapter 2 on page 30. Thematic Mapping The Presentation Service allows you to display and stylize your data based on a theme. Thematic This theme is usually based on some piece or pieces of geographic data, such as population density or population levels. Thematic mapping can help you sort through all of your company s information, and using geographic components in your data, display your results on a map. This type of mapping lets you see patterns and relationships in the mass of information quickly and easily without having to pore over your database. The following sections highlight potential ways to apply these capabilities: Override Feature Theme in Chapter 4 on page 56. Override Theme Label Control in Chapter 4 on page 58. Ranged Feature Theme in Chapter 4 on page 61. Ranged Label Theme in Chapter 4 on page 69. Presentation Service Reference 9

10 Presentation Service Functionality Individual Value Theme in Chapter 4 on page 73. Adding Theme Legends in Chapter 4 on page 77. Legends and Scale Bars The Presentation Service allows you to create legends and scale bars independently of your maps. This means you can create these objects as their own images and use them to customize your maps presentation. Both legends and scale bars are important components of maps, allowing users to identify features, themes, and labels, or analyze distances. The following sections highlight potential ways to apply these capabilities: Adding Cartographic Legends in Chapter 4 on page 82. Adding Scale Bars to your Map in Chapter 2 on page Envinsa 4.1

11 Creating and Modifying Maps 2 This chapter shows you how to perform the basic Presentation Service mapping capabilities, allowing you to query, create maps, pan and zoom, customize your output, and stylize your maps to best represent your data. In this section: Describing the Service Capabilities Describing the Available Resources Rendering Preference (Anti-aliasing) Returning a Simple Basemap Simple Zooming by Changing Map Bounds Panning and Zooming by Screen Context Changing the Output Format (SVG Support) Creating a 3D Map (VRML Controls) Adding Scale Bars to your Map Creating a WBMP Map

12 Describing the Service Capabilities The Presentation Service is able to describe its capabilities (GetCapabilities). In this implementation of the service, the capabilities of a Presentation Service include the supported spatial reference systems, available layers for a particular basemap, available image formats, available styles (brush, pen, fonts), and all of the other available basemaps, named layers, grid layers, dynamic layers, spatial contents and their boundaries (not all contents have map bounds). Note: In a standard get capabilities request, a default named map (for example, MapDisplay/high) will be implicitly used for the available layers. To query the available layers for a specific named map, you must use the get capabilities extension (for example, GetPortrayMapCapabilitiesRequestEx). Inputs and Behaviors A GetCapabilities request takes the following inputs: Input Required Description Portray Map Capability Yes You must specify that this is a Portray Map Capability request. If you only specify the capability and no additional fields, all available spatial reference systems, layers, formats (mime types) and styles will be returned. Basemap Name No To return the available layers for a basemap, set the basemap name to that particular basemap. If you do not specify a basemap the default basemap will be used. Return Bounds No If set to true, the list map boundaries for the available basemaps, available named layers, and available spatial contents (rendering related information of the Content Manager content including full name, dynamic filter, and bounds) will be returned. The default is false. Return Fonts No If set to true, the list of available font families will be returned. The default is false. Return Extended Layers Return Country Info No No If set to true, the list of available named layers, available grid layers, available dynamic layers (CMLayers), and available spatial contents are returned. The default is false. If set to true, the Presentation Service will return a list of available countries that may be rendered. This list will return the default country supported, as well as a list of ISO country codes for the other supported countries. The default is false. 12 Envinsa 4.1

13 Chapter 2: Creating and Modifying Maps Java Code Sample The following code sample shows a Get Capabilities request that returns all available spatial reference systems, layers, formats (mime types), and styles. GetPortrayMapCapabilitiesRequest capabilitiesrequest = new GetPortrayMapCapabilitiesRequest( perform, 4.0, ID ); The following code sample shows an Extended Get Capabilities request that returns all fonts, extended layers, and information on the world basemap, in addition to all available spatial reference systems, layers, formats (mime types), and styles GetPortrayMapCapabilitiesRequestEx capabilitiesrequest = new GetPortrayMapCapabilitiesRequestEx( perform, 1.5, ID ); capabilitiesrequest.setreturnfonts(true); capabilitiesrequest.setreturnextendedlayers(true); capabilitiesrequest.setreturnbounds(false); capabilitiesrequest.setbasemapname( world );.NET Code Sample The following code sample shows an Extended Get Capabilities request that return all fonts and map bounds, in addition to all available spatial reference systems, layers, formats (mime types), and styles GetPortrayMapCapabilitiesRequest pr = new GetPortrayMapCapabilitiesRequest(); //return boundaries pr.returnbounds = true; //do not return extended layers pr.returnextendedlayers = false; //return fonts pr.returnfonts = true; XML Sample The following code sample shows a Get Capabilities request that returns all available spatial reference systems, layers, formats (mime types), and styles. <_RequestParameters xsi:type= GetPortrayMapCapabilitiesRequestType /> The following code sample shows an Extended Get Capabilities request that returns all fonts, map bounds, and information on the world basemap, in addition to all available spatial reference systems, layers, formats (mime types), and styles <_RequestParameters xsi:type= ns3:getportraymapcapabilitiesrequesttypeex basemap= world returnbounds= true returnextendedlayers= false returnfonts= true xmlns:ns3= /> Presentation Service Reference 13

14 Describing the Available Resources Describing the Available Resources The Resource Info request allows you to query specific information on your available resources. You now have the option to query your basemaps, named layers, Content Manager content (spatial content), and grid layers to return metadata (column names and types), default layer labeling configuration (text expressions, font information, position), bounds, and rendering options. Inputs and Behaviors A Resource Info request takes the following inputs: Input Required Description Resource Info Request Yes You must specify that this is a Resource Info Capability request. Basemap No To query a basemap you must specify the name of the basemap. You have the option to disable return bounds and return metadata (both default to true). When a query is performed on a basemap, the full list of layers that make up the basemap are returned. For each layer the following information can be returned: name autolabel (on or off) enabled (true or false) rasterlayer (true or false) spatial reference system name label properties display range metadata (column names and type) bounding box 14 Envinsa 4.1

15 Chapter 2: Creating and Modifying Maps Input Required Description Named Layer No To query a named layer you must specify the name of the layer. You have the option to disable return bounds and return metadata (both default to true). When a query is performed on a named layer, the following information can be returned: name autolabel (on or off) enabled (true or false) rasterlayer (true or false) spatial reference system name label properties display range metadata (column names and type) bounding box Spatial Content No To query content (data content from Content Manager) you must specify the name of the content. You have the option to disable return bounds and return metadata (both default to true). When a query is performed on a spatial content, the following information can be returned: content path (name) spatial reference system name list of filters metadata (column names and type) bounding box runtime parameters Grid Layer No To query a grid layer you must specify the name of the layer. You have the option to disable return bounds (default to true). Both the layer name and bounds will be returned. Java Code Sample The following code sample shows a Resource Info request that returns all metadata and bounds for the MapDisplay/High basemap, WorldCounties named layer, SanFranciscoE gird layer, and the Canadian POIs spatial content. GetResourceInfoRequest inforequest = new GetResourceInfoRequest( perform, 4.0, ID ); //set a base map ResourceName basemap=new ResourceName( MapDisplay/high ); basemap.setreturnbounds(true); basemap.setreturnmetadata(true); Presentation Service Reference 15

16 Describing the Available Resources inforequest.setbasemaps(new ResourceName[]{basemap}); //set a named layer ResourceName layer=new ResourceName( WorldCountries ); layer.setreturnbounds(true); layer.setreturnmetadata(true); inforequest.setnamelayers(new ResourceName[]{layer}); //set a grid layer ResourceName grid=new ResourceName( Grid/SanFranciscoE ); grid.setreturnbounds(true); inforequest.setgridlayers(new ResourceName[]{grid}); //set a content ResourceName con=new ResourceName( Canadian POIs ); con.setreturnbounds(true); con.setreturnmetadata(true); inforequest.setspatialcontents(new ResourceName[]{con});.NET Code Sample The following code sample shows a Resource Info request that returns all metadata and bounds for the MapDisplay/High basemap, WorldCounties named layer, SanFranciscoE gird layer, and the Canadian POIs spatial content. GetResourceInfoRequest inforequest = new GetResourceInfoRequest(); //set a base map MapName basemap=new MapName( MapDisplay/high ); basemap.returnbounds = true; basemap.returnmetadata = true; inforequest.basemap = new MapName[]{basemap}; //set a named layer LayerName layer=new LayerName( WorldCountries ); layer.returnbounds = true; layer.returnmetadata = true; inforequest.namedlayer = new LayerName[]{layer}; //set a grid layer GridName grid = new GridName( Grid/SanFranciscoE ); grid.returnbounds = true; inforequest.gridlayer = new GridName[]{grid}; //set a content 16 Envinsa 4.1

17 ContentName con = new ContentName( Canadian POIs ); con.returnbounds = true; con.returnmetadata = true; inforequest.spatialcontent = new ContentName[]{con}; Chapter 2: Creating and Modifying Maps XML Sample The following code sample shows a Resource Info request that returns all metadata and bounds for the MapDisplay/High basemap, WorldCounties named layer, SanFranciscoE gird layer, and the Canadian POIs spatial content. <_RequestParameters xsi:type= ns3:getresourceinforequesttype xmlns:ns3= > <ns3:basemap name= MapDisplay/high returnbounds= true returnmetadata= true /> <ns3:namedlayer name= WorldCountries returnbounds= true returnmetadata= true /> <ns3:spatialcontent name= Canadian POIs returnbounds= true returnmetadata= true /> <ns3:gridlayer name= Grid/SanFranciscoE returnbounds= true /> </_RequestParameters> Rendering Preference (Anti-aliasing) Anti-aliasing (rendering preference) for map rendering in Presentation Service requests by specifying quality of the map or speed of map creation. In addition to a service request, you can set anti-aliasing in the Presentation Service configuration. The anti-aliasing effect helps graphic edges appear smoother and less jagged, resulting in better looking maps. Inputs and Behaviors When setting the rendering preference in the request, you need to specify the type of rending output. The rendering preference can be set to one of three options: Presentation Service Reference 17

18 Returning a Simple Basemap Input Required Description Rendering Preference Yes Determines the rendering preference as either Default, Speed, or Quality. Default Specifies that the server-side setting will be used when rendering maps. Maps will be rendered with or without anti-aliasing according to the server-side setting. See Payload Constraints on page 133 for instructions on how to set the defaultantialiasing parameter in the service configuration. Speed Specifies that speed is preferred when rendering maps. Maps will be rendered without anti-aliasing. Quality Specifies that quality is preferred when rendering maps. Maps will be rendered with anti-aliasing. Java Sample Code To specify anti-aliasing in the request, add the rendering preference to the extended output class, and specify the anti-aliasing criteria as either RENDERING_DEFAULT, RENDERING_SPEED, or RENDERING_QUALITY. OutputEx output = new OutputEx(500, 500, "image/png"); output.setrenderingpreference(outputex.rendering_quality);.net Sample Code To specify anti-aliasing in the request, add the rendering preference to the output method, and specify the anti-aliasing criteria as either Default, Speed, or Quality. Output output1 = new Output(); output1.renderingpreference = RenderingPreference.Default; Returning a Simple Basemap The simplest map to return is the basemap. The basemap consists of a predefined set of layers and features. You can control the basemap by determining the layers that are to be included or excluded from the basemap in the request, and may be made up of the following: Layers The list of layers of interest. Filter Determines if the layers are included or excluded. Give me only the following layers or Give me all layers but the following. Custom Style This is either a named-style or a user-defined style. If a style is not specified it is up to the Implementation to use a default. 18 Envinsa 4.1

19 Chapter 2: Creating and Modifying Maps Inputs and Behaviors When returning the basemap (or any map), you need to specify output parameters. These define what the size and encoding of the portrayed map should be using the following criteria: Input Required Description Width Yes The width of the map in screen pixels units. Height Yes The height of the map in screen pixels units. Format Yes Parameter that specifies what the encoding of the map should be. This is specified as a mime-type. The supported mime-types are GIF, JPEG, and PNG (for example, image/png or image/jpeg). Transparency No Boolean that defines the opacity of the background of the map. The default is false (not transparent) Background Color No Background Color of the map. The default is #FFFFFF (hex number or White (name color). For both XML and.net SDK requests you must specify the color in RGB hex format (for example, #FFFFFF), for the Java SDK you must specify the color in name format (for example, White). You can use the color.decode method in the Sun Java SDK to transform a hex number to a color name. Content No Specifies what type of content will be returned, either as URL or data (base64 encoded image). The default is URL. Java Sample Code The following code sample shows a Basemap request that returns the default basemap specified in the configuration. The image is 500 by 500 pixels, in PNG format, and returned as data in the response. No layers are excluded from the basemap. //create portray map request PortrayMapRequest maprequest = new PortrayMapRequest(METHOD_NAME,VERSION, R1 ); //specify the width, height and mime image format in the map output Output output = new Output(500, 500, image/png ); //return embedded image data. output.setpresentationcontent(output.content_base64);// Data maprequest.addoutput(output); //suppose that all layers should be visible, set nothing to exclude. Basemap basemap = new Basemap(Basemap.FILTER_EXCLUDE); maprequest.setbasemap(basemap); Presentation Service Reference 19

20 Simple Zooming by Changing Map Bounds.NET Sample Code The following code sample shows a Basemap request that returns the default basemap specified in the configuration. The image is 500 by 500 pixels, in PNG format, and returned as data in the response. No layers are excluded from the basemap. private static Request newbasicmaprequest() { PortrayMapRequest pr = new PortrayMapRequest(); pr.requestid = "R1"; //Set map outputs //output1: define the map format, size and context Output output1 = new Output(); output1.width = 500; output1.height = 500; output1.format = "image/gif"; Output[] outs = {output1}; pr.output = outs; //assume that all layers should be visible, set nothing to exclude. Basemap basemap = new Basemap(LayerTypeFilter.Exclude); pr.basemap = basemap; return pr; } XML Sample The following code sample shows a Basemap request that returns the default basemap specified in the configuration. The image is 500 by 500 pixels, in PNG format, and returned as a URL in the response. No layers are excluded from the basemap. <_RequestParameters xsi:type= ns2:portraymaprequesttype > <Output BGcolor= #ffffff content= URL format= image/png height= 500 transparent= true width= 500 > </Output> <Basemap filter= Exclude /> </_RequestParameters> Simple Zooming by Changing Map Bounds There are two ways to zoom an existing map using the map boundaries: change the radius of the map being shown maintaining the size of the map; or change the bounding box of the map maintaining the radius of the map. 20 Envinsa 4.1

21 Chapter 2: Creating and Modifying Maps Inputs and Behaviors When zooming by changing the map bounds, you can define the following information: Input Required Description Bounding Box No Defines the new map bounds in screen coordinates of based on the existing map. If you specify a box that is smaller than the original map, then you will zoom in. If you specify a box that is larger than the original map, then you will zoom out. The bounding box for the screen coordinates is defined using defined from the lower left corner to the upper right corner. This creates new map bounds and essentially zooms to this area of the original map, and pans to the center of the new area. Radius No Using the map center defined in screen coordinates and changing the radius (in user units) related to the original map display. (i.e.: Use the bounding box (map extent in world coordinates) to define the map as returned in previous map display, and screen context: the center point (map center in screen coordinates) and radius (with unit)). Radius Unit No/Yes The units of measure for the radius. The radius unit must be specified when changing the zoom by map bounds. The radius can be specified in kilometers (KM), miles (MI), or meters (M). Radius Type No There are two types of radius calculations for creating the new map bounds: Cross and Inner. The default radius type is Inner. Inner type creates the new map bounds by using the specified radius as the distance from the center to the top of the map bounds. Cross type creates the new map bounds by using the specified radius as the distance from the center to the edge (side width) of the map bounds. Java Sample Code Bounding Box The following sample code shows a request that zooms a map by changing the bounding box of the map. //specify the bounds, width, height and mime image format in the map output Envelope box = GeometryUtils.newEnvelope( , , , , EPSG:4326 ); Output output2 = new Output(box, 300, 300, image/png ); output2.setpresentationcontent(output.content_base64);// Data maprequest.addoutput(output2); Presentation Service Reference 21

22 Simple Zooming by Changing Map Bounds Radius The following sample code shows a request that zooms a map by changing the radius of the map. //Create an OutputEx object and add it to the PortrayMapRequestEx //Create the CenterContext object Distance distance = new Distance(20, DistanceUnit.KM); CenterContext centercontext = new CenterContext( , , EPSG:4326, distance); OutputEx output = new OutputEx(centerContext, 1200, 800, model/vrml ); output.setpresentationcontent(outputex.content_url);.net Sample Code Radius The following sample code shows a request that zooms a map by changing the radius of the map. CenterContext ctrctx = new CenterContext(); ctrctx.centerpoint = GeometryUtils.newPoint( , , EPSG:4326 ); ctrctx.radius = new Distance(20, DistanceUnitType.KM); output1.centercontext = ctrctx; XML Sample Bounding Box The following sample code shows a request that zooms a map by changing the bounding box of the map. <Output BGcolor= #ffffff content= URL format= image/png height= 300 transparent= true width= 300 > <BBoxContext srsname= EPSG:4326 > <ns4:pos dimension= 2 xmlns:ns4= > </ns4:pos> <ns5:pos dimension= 2 xmlns:ns5= > </ns5:pos> </BBoxContext> </Output> Radius The following sample code shows a request that zooms a map by changing the radius of the map. <CenterContext SRS= EPSG:4326 azimuth= 0 > <CenterPoint srsname= EPSG:4326 > <ns4:pos dimension= 2 xmlns:ns4= > </ns4:pos> </CenterPoint> <Radius unit= KM >20</Radius> </CenterContext> 22 Envinsa 4.1

23 Panning and Zooming by Screen Context Chapter 2: Creating and Modifying Maps There are numerous ways to pan and zoom an existing map using the screen coordinates from the original map. Panning is really the process of re-centering the existing map. In the world of mapping, a center value is typically a (longitude, latitude) 2-tuple value that defines an exact coordinate over which a map image should be centered. For example, if there is a rectangular map image whose middle coordinate is (cx,cy), then (cx,cy) is the center of that map. The notion of a zoom value represents the distance away from something. For example, when using a camera with a zoom lens, a user adjust its zoom setting to be nearer to (or farther away from) some particular object, where the object in question is simply the item which is about to be photographed. This paradigm changes in the world of mapping. The zoom is actually the distance across a map's surface, and not the distance away from the ground (or surface of the earth) over which a user's map image is looking. Another equally important notion is that of aspect ratio (bounding box or map size). An aspect ratio is merely the ratio of a quadrilateral's width to its height. Mathematically speaking, if given a quadrilateral (a rectangle or square) having width = 9 and height = 3, then its aspect ratio is simply the fraction 9/3. The Presentation Service uses the above notions of center, zoom, and aspect ratio to its advantage, allowing users to procure a map image whose zoom and center values define an exact circular area (or logical circle) that is centered within a rectangular region whose aspect ratio is exactly the same as the pixel dimensions of the requested image. Input and Behaviors When panning and zooming by screen context, you can define the following information: Input Required Description Center Point No Defines the center point of the map. Zoom Factor No Specifies a number to multiply the existing map zoom. When defining the zoom factor, a value less than one will zoom-in a value of greater than one will zoom out, and a value equal to one will perform a pan. The default zoom factor is one. Radius No Using the map center defined in screen coordinates and changing the radius (in user units) related to the original map display. (i.e.: Use the bounding box (map extent in world coordinates) to define the map as returned in previous map display, and screen context: the center point (map center in screen coordinates) and radius (with unit)). Radius Unit No/Yes The units of measure for the radius. The radius unit must be specified when changing the zoom by map bounds. The radius can be specified in kilometers (KM), miles (MI), or meters (M). Presentation Service Reference 23

24 Panning and Zooming by Screen Context Input Required Description Bounding Box No Defines the new map bounds in screen coordinates of based on the existing map. If you specify a box that is smaller than the original map, then you will zoom in. If you specify a box that is larger than the original map, then you will zoom out. The bounding box for the screen coordinates is defined using defined from the lower left corner to the upper right corner. This creates new map bounds and essentially zooms to this area of the original map, and pans to the center of the new area. Radius Type No There are two types of radius calculations for creating the new map bounds: Cross and Inner. The default radius type is Inner. Inner type creates the new map bounds by using the specified radius as the distance from the center to the top of the map bounds. Cross type creates the new map bounds by using the specified radius as the distance from the center to the edge (side width) of the map bounds. Output The following example illustrates how the Presentation Service uses the center and zoom approach when rendering maps: 1. The center setting is read from the center context, such that the center point of the view will be identified. 24 Envinsa 4.1

25 Chapter 2: Creating and Modifying Maps 2. The zoom setting is read from the radius and/or zoom factor that is contained within the center and screen context, such that it defines the radius to use when defining the logical circle. 3. The aspect ratio of the final map image is calculated, which is accomplished by using the map image width and height values that are defined for the output. For example, if the pixel dimensions of the desired map image are 800 (width) x 400 (height), then the aspect ratio is 800/ 400 = 2/1. Based on an aspect ratio of 2/1, the surface area of the map's coordinate system that is to be captured and returned in a map image should be exactly two (2) times as wide as it is high. The map image must be centered over the target center point, or in other words, centered over the center of the logical circle. 4. Essentially, the following steps are performed: The zoom and center values are used to define a logic circle in the map's coordinate system. The smallest rectangle that completely encompasses this logic circle is determined, such that the rectangle has the same aspect ratio as the map image to be returned. The returned image would simply be as follows: Presentation Service Reference 25

26 Panning and Zooming by Screen Context Java Sample Code The following code sample shows how to set the original center screen context by a position and set the zoom level by specifying a radial distance of one kilometer. //This is a simple map with the center point: //create a center context for this map with the point and radius CenterContext center = new CenterContext( , , EPSG:4326, new Distance(1, DistanceUnit.KM)); //specify the center, width, height and mime image format in the map output OutputEx output = new OutputEx(300, 300, image/png ); output.setbgcolor(color.decode( # )); //output.setbgcolor(color.getcolor( # )); output.settransparent(false); output.setpresentationcontent(output.content_base64);// Data output.setcentercontext(center); maprequest.addoutput(output); The following code sample shows how to pan by screen coordinates and zoom out based on the existing map using the zoom factor. The request creates a new 300 by 300 pixel map, panning to 10 pixels in the x direction and 100 pixels in the y direction (from the lower left corner) of the original map. This request is also zooms out of the map by a factor of 4 (multiplies the existing zoom factor by 4). //Zoom out the map using screen coordinates with the specified radius. OutputEx outputex = new OutputEx(300, 300, image/png ); outputex.setscreencentercontext(new ScreenCenterContext(10, 100, 4)); outputex.setpresentationcontent(output.content_base64);// Data outputex.setcentercontext(center); maprequest.addoutput(outputex); The following code sample shows how to pan by screen coordinates and zoom out based on the existing map by setting the radial distance. The request creates a new 300 by 300 pixel map, panning to 200 pixels in the x direction and 100 pixels in the y direction (from the lower left corner) of the original map. This request also sets a new zoom level by defining a radial distance of one kilometer. //Pan the map using screen coordinates with the specifed distance. outputex = new OutputEx(300, 300, image/png ); outputex.setscreencentercontext(new ScreenCenterContext(200, 100, new Distance(1, DistanceUnit.KM))); outputex.setpresentationcontent(output.content_base64);// Data outputex.setcentercontext(center); maprequest.addoutput(outputex); 26 Envinsa 4.1

27 Chapter 2: Creating and Modifying Maps The following code sample shows how to pan and zoom based on the existing map screen coordinates by setting a new bounding box and output size. The request creates a new 300 by 300 pixel map, containing the information that was located in the defined bounding box from the original map (the bounds are defined by (x1, y1, x2, y2) from the lower left corner to the upper right corner. This creates new map bounds and essentially zooms to this area of the original map, and pans to the center of the new area. //Pan the map using screen coordinates with the specifed distance. outputex = new OutputEx(300, 300, image/png ); outputex.setscreenbboxcontext(0, 0, 150, 150); outputex.setpresentationcontent(output.content_base64);// Data outputex.setcentercontext(center); maprequest.addoutput(outputex);.net Sample Code The following code sample shows how to pan by screen coordinates and zoom out based on the existing map using the zoom factor. The request creates a new 300 by 300 pixel map, panning to 250 pixels in the x direction and 250 pixels in the y direction (from the lower left corner) of the original map. This request also zooms out of the map by a factor of 4 (multiplies the existing zoom factor by 4). //output3: zoom out the map using screen coordinates with the specified radius. Output output3 = new Output( 500, 500, image/gif ); ScreenCenterContext scrctx1 = new ScreenCenterContext(GeometryUtils.newPoint(250,250),4); output3.screencentercontext = scrctx1; The following code sample shows how to pan by screen coordinates and change the existing zoom level of the map by setting the radial distance. The request creates a new 500 by 500 pixel map, panning to 100 pixels in the x direction and 100 pixels in the y direction (from the lower left corner) of the original map. This map also sets the new zoom level to a one kilometer radius. //output2: pan the map using screen coordinates with the specifed distance Output output2 = new Output(500, 500, image/gif ); ScreenCenterContext scrctx = new ScreenCenterContext(GeometryUtils.newPoint(100,100),new Distance(1, DistanceUnitType.KM) ) ; output2.screencentercontext = scrctx; XML Sample The following code sample shows how to set the original center screen context by a position and set the zoom level by specifying a radial distance of one kilometer. <Output xsi:type= ns3:outputtypeex BGcolor= # content= URL format= image/png height= 300 returnzoomlevel= on transparent= false width= 300 > <BBoxContext xsi:nil= true /> <CenterContext SRS= EPSG:4326 azimuth= 0 > Presentation Service Reference 27

28 Panning and Zooming by Screen Context <CenterPoint srsname= EPSG:4326 > <ns4:pos dimension= 2 xmlns:ns4= > </ns4:pos> </CenterPoint> <Radius unit= KM >1</Radius> </CenterContext> </Output> The following code sample shows how to pan by screen coordinates and zoom out based on the existing map using the zoom factor. The request creates a new 300 by 300 pixel map, panning to 10 pixels in the x direction and 100 pixels in the y direction (from the lower left corner) of the original map. This request is also zooms out of the map by a factor of 4 (multiplies the existing zoom factor by 4). <Output xsi:type= ns3:outputtypeex BGcolor= #ffffff content= URL format= image/png height= 300 returnzoomlevel= on transparent= true width= 300 > <BBoxContext xsi:nil= true /> <CenterContext SRS= EPSG:4326 azimuth= 0 > <CenterPoint srsname= EPSG:4326 > <ns5:pos dimension= 2 xmlns:ns5= > </ns5:pos> </CenterPoint> <Radius unit= KM >1</Radius> </CenterContext> <ns3:screencontext> <ns3:screencentercontext> <ns3:centerpoint> <ns6:pos dimension= 2 xmlns:ns6= > </ns6:pos> </ns3:centerpoint> <ns3:zoomfactor>4.0</ns3:zoomfactor> </ns3:screencentercontext> </ns3:screencontext> </Output> The following code sample shows how to pan by screen coordinates and maintains the existing zoom level of the map by setting the radial distance equal to the existing distance. The request creates a new 300 by 300 pixel map, panning to 200 pixels in the x direction and 100 pixels in the y direction (from the lower left corner) of the original map. <Output xsi:type= ns3:outputtypeex BGcolor= #ffffff content= URL format= image/png height= 300 returnzoomlevel= on transparent= true width= 300 > <CenterContext SRS= EPSG:4326 azimuth= 0 > <CenterPoint srsname= EPSG:4326 > <ns7:pos dimension= 2 xmlns:ns7= > </ns7:pos> </CenterPoint> <Radius unit= KM >1</Radius> </CenterContext> <ns3:screencontext> 28 Envinsa 4.1

29 Chapter 2: Creating and Modifying Maps <ns3:screencentercontext> <ns3:centerpoint> <ns8:pos dimension= 2 xmlns:ns8= > </ns8:pos> </ns3:centerpoint> <ns3:radius unit= KM >1</ns3:Radius> </ns3:screencentercontext> </ns3:screencontext> </Output> The following code sample shows how to pan and zoom based on the existing map screen coordinates by setting a new bounding box. The request creates a new 300 by 300 pixel map, containing the information that was located in the defined bounding box from the original map (the bounds are defined from the lower left corner (x, y) to the upper right corner (x, y). This creates new map bounds and essentially zooms to this area of the original map, and pans to the center of the new area. <Output xsi:type= ns3:outputtypeex BGcolor= #ffffff content= URL format= image/png height= 300 returnzoomlevel= on transparent= true width= 300 > <CenterContext SRS= EPSG:4326 azimuth= 0 > <CenterPoint srsname= EPSG:4326 > <ns9:pos dimension= 2 xmlns:ns9= > </ns9:pos> </CenterPoint> <Radius unit= KM >1</Radius> </CenterContext> <ns3:screencontext> <ns3:bboxcontext> <ns10:pos dimension= 2 xmlns:ns10= > </ns10:pos> <ns11:pos dimension= 2 xmlns:ns11= > </ns11:pos> </ns3:bboxcontext> <ns3:screencentercontext xsi:nil= true /> </ns3:screencontext> </Output> Changing the Output Format (SVG Support) The Presentation Service supports the SVG mime type image/svg+xml. SVG (Scalable Vector Graphics) is a language for describing two-dimensional graphics in XML. SVG allows for three types of graphic objects: vector graphic shapes (for example, paths consisting of straight lines and curves), images, and text. Graphical objects can be grouped, styled, transformed, and compounded into previously rendered objects. The feature set includes nested transformations, clipping paths, alpha masks, filter effects, and template objects. Note: Legends and scale bars do not support the SVG mime type at this time. Presentation Service Reference 29

30 Creating a 3D Map (VRML Controls) To returns a map in SVG format, simply specify the output type as image/svg+xml. Java Code Sample The following sample code shows a request that specifies the map output type to SVG. //create portray map request PortrayMapRequest maprequest = new PortrayMapRequest(METHOD_NAME, VERSION, R1 ); //specify the width, height and svg mime format in the map output Output output = new Output(500, 500, image/svg+xml ); //return embedded image data. output.setpresentationcontent(output.content_url); maprequest.addoutput(output); //suppose that all layers should be visible, set nothing to exclude. Basemap basemap = new Basemap(Basemap.FILTER_EXCLUDE); maprequest.setbasemap(basemap);.net Code Sample The following sample code shows a request that specifies the map output type to SVG. //output1: define the map format, size and context Output output1 = new Output(); output1.width = 500; output1.height = 500; output1.format = image/svg+xml ; Output[] outs = {output1}; pr.output = outs; //suppose that all layers should be visible, set nothing to exclude. Basemap basemap = new Basemap(LayerTypeFilter.Exclude); pr.basemap = basemap; XML Sample The following sample code shows a request that specifies the map output type to SVG. <Output BGcolor= #ffffff content= URL format= image/svg+xml height= 500 transparent= true width= 500 > </Output> Creating a 3D Map (VRML Controls) The 3D mapping capability enables you to view your map data in an interactive 3D environment. Once the 3D VRML context and valid elevation Grid files have been defined in the request, your 2D named layers can be draped, providing a valuable visual analysis capability. You may want to drape 30 Envinsa 4.1

31 Chapter 2: Creating and Modifying Maps a satellite image or point of interest layer. To do this your image or layer must be defined in a named layer and then added to the map request. For more information on creating named layers, see the Map Management Guide. The Presentation Service outputs the 3D map as a WRL file conforming to the GeoVRML1.1 specification. 3D viewing can be shown in a web browser with a GeoVRML viewer plug-in. The VRML viewer allows rotation and 360 degree viewing. Note: When creating a 3D map, there are many parameters to control the map generation. Since the WRL file is returned in the text format, you can modify those parameters after the 3D map is generated by editing the WRL file. Getting the Plug-In You are required to install two plug-ins to the client machine where you viewing the 3D rendered maps. To setup the GeoVRML1.1 viewing: 1. Install the Cortona VRML plug-in from 2. Install the GeoVRML 1.1 plug-in from Inputs and Behaviors To request a 3D map you can specify the following inputs: Input Required Description Output Format Yes Specifies the encoding of the 3D maps. This is specified as a mime type. You must define the mime type as model/vrml. Image Texture Format No Defines the surface texture format in the WRL file for the map image. This is specified as a mime type. The default is image/gif. View Point No The position is used to define the x.y,z coordinate that locates the viewpoint, you can specify the spatial reference system and orientation. The default view point is (x y z radians). The orientation (string) defines a relative orientation from the local orientation frame that is defined by a position field. By default, the orientation of the viewpoint will always be aligned such that the +Y axis is the up vector for the local area (the normal to the tangent plane on the ellipsoid), -Z points towards the north pole, and +X is east. Therefore, if a GeoViewpoint that always looks straight down is to be created, no matter where on the planet the viewer may be looking, an orientation value of should be specified. Presentation Service Reference 31

32 Creating a 3D Map (VRML Controls) Input Required Description Elevation Scale No Defines the value used to produce a vertical exaggeration of the data when displayed. By default, this value is 1.0 (no exaggeration). If you set this value greater than 1.0, all heights will appear larger than they actually are. If you set this value to be greater than 1.0 (for example, 0.5), all heights will appear smaller than they actually are. Modifying the scale can be useful for emphasizing elevation change. Crease Angle No Defines how default normals (vectors that make up the 3D representation) are generated by specifying a degree in radians. The default crease angle is 1.0. If the angle between the geometric normals of two adjacent faces is less than the crease angle, normals shall be calculated so that the faces are smooth-shaded across the edge; otherwise, normals shall be calculated so that a lighting discontinuity across the edge is produced. For example, a crease angle of 0.5 radians means that an edge between two adjacent polygonal faces will be smooth shaded if the geometric normals of the two faces form an angle that is less than 0.5 radians. Crease angles must be greater than or equal to 0.0. Resolution No Defines the resolution for the Grid layer. The resolution is the number of elevation point from the Grid file to form one normal plain. The default resolution is Grid Layer No Defines the Grid layer used for rendering the 3D map. The Grid layer (or elevation layer) must be a named layer (referenced by its name) and a Vertical Mapper Grid file. The Presentation Service will search for specified Grid file in your enterprise named resources. If the specified Grid file is not found, the Presentation Service looks for fallback valid Grid files overlapping the requested map bounds. If you do not have an enterprise, or Grid files are not found in your enterprise, the Presentation Service will look for the specified Grid file (or other valid Grid files) in the PUBLIC named resources. If no Grid file is found the 3D map is rendered with a flat backdrop (zero elevation). If multiple fallback Grid files are found in your enterprise, the Presentation Service will use the first file listed alphabetically. Java Code Sample The following code sample requests a 3D map. //Create a PortrayMapRequestEx 32 Envinsa 4.1

33 Chapter 2: Creating and Modifying Maps PortrayMapRequestEx maprequest = new PortrayMapRequestEx(METHOD_NAME, VERSION, R1 ); //Create an OutputEx object and add it to the PortrayMapRequestEx //Create the CenterContext object Distance distance = new Distance(1, DistanceUnit.KM); CenterContext centercontext = new CenterContext( , , EPSG:4326, distance); OutputEx output = new OutputEx(centerContext, 1200, 800, model/vrml ); output.setpresentationcontent(outputex.content_url); //Create an ElevationGrid that will be added to the OutputEx ElevationGrid elevationgrid = new ElevationGrid(3); elevationgrid.setcreaseangle(3); //Create a GridLayer GridLayer gridlayer = new GridLayer( grid/sanfranciscoe, 1000); //Set ElevationGrid s GridLayer elevationgrid.setgridlayer(gridlayer); //Add the VRMLContext to the OutputEx output.setvrmlelevation(elevationgrid); //Add the OutputEx to the PortrayMapRequestEx maprequest.addoutput(output); //Create a Basemap that contains one layer BasemapEx basemap = new BasemapEx(); basemap.setname( MapDisplay/high ); basemap.setorder(0); //Add the BasemapEx to the PortrayMapRequestEx maprequest.setbasemap(basemap);.net Code Sample The following code sample requests a 3D map. PortrayMapRequest pr = new PortrayMapRequest(); pr.requestid = R1 ; //Set map outputs //output1: define the map format, size and context Output output1 = new Output(); output1.width = 1200; output1.height = 800; output1.format = model/vrml ; CenterContext ctrctx = new CenterContext(); ctrctx.centerpoint = GeometryUtils.newPoint( , , EPSG:4326 ); Presentation Service Reference 33

34 Creating a 3D Map (VRML Controls) ctrctx.radius = new Distance(1, DistanceUnitType.KM); output1.centercontext = ctrctx; //Create an ElevationGrid that will be added to the Output object ElevationGrid elevationgrid = new ElevationGrid(); elevationgrid.creaseangle = 3; //Set GridLayer for eleveation grid GridLayer gridlayer = new GridLayer( grid/sanfranciscoe, 1000); elevationgrid.gridlayer = gridlayer; //set the flag indicating the request contains VRML information output1.hasvrmlcontext = true; output1.vrmlelevation = elevationgrid; Output[] outs = {output1}; pr.output = outs; //Create a Basemap that contains one layer Basemap basemap = new Basemap( MapDisplay/high ); pr.basemap = basemap; XML Sample The following code sample requests a 3D map. <_RequestParameters xsi:type= ns3:portraymaprequesttypeex xmlns:ns3= > <Output xsi:type= ns3:outputtypeex BGcolor= #ffffff content= URL format= model/vrml height= 800 returnzoomlevel= on transparent= true width= 1200 > <CenterContext SRS= EPSG:4326 azimuth= 0 > <CenterPoint srsname= EPSG:4326 > <ns4:pos dimension= 2 xmlns:ns4= > </ns4:pos> </CenterPoint> <Radius unit= KM >1</Radius> </CenterContext> <ns3:vrmlcontext imagetextureformat= image/gif spec= GeoVRML11 > <ns3:elevationgrid creaseangle= 3.0 elevationscale= 3.0 > <ns3:gridlayer resolution= 1000 >san_francisco-e</ns3:gridlayer> </ns3:elevationgrid> <ns3:geometryoverlay/> </ns3:vrmlcontext> </Output> <Basemap xsi:type= ns3:layertypeex filter= Exclude name= MapDisplay/ high order= 0 /> </_RequestParameters> 34 Envinsa 4.1

35 Chapter 2: Creating and Modifying Maps Adding Scale Bars to your Map Scale bars are created and returned as separate entities from the map. A scale bar can be returned as a URL linking to the scale bar image or as base64 encoded data in the response. Inputs and Behaviors When defining a scale in the request, it is recommended that you do not customize the width, height, or intervals. The Presentation Service calculates, by default, an even interval, well sized scale bar (usually between 100 and 200 pixels wide) based on the default or custom font option specified. You can define the following information: Input Required Description Width No The width of the scale bar in pixels. Height No The height of the scale bar in pixels. Format No Specifies what the encoding of the scale bar should be. This is specified as a mime type. The supported mime-types are GIF, JPEG, and PNG (for example, image/png or image/jpeg). Background Color No Background Color of the scale bar. The default is #FFFFFF (hex number or WHITE (name color). Note: For both XML and.net SDK requests you must specify the color in RGB hex format (for example, #FFFFFF), for the Java SDK you must specify the color in name format (for example, White). You can use the color.decode method in the Sun Java SDK to transform a hex number to a color name. Transparent No Boolean value that defines the opacity of the map. The default is false (not transparent). Content No Defines the type of output for the scale bar. The scale bar can be returned as a map image referenced by a URL or created as Data (base64 encoded image). Default is URL Unit No Defines the unit of measure you wish the scale bar to represent on the map. The default is M (meters). Presentation Service Reference 35

36 Adding Scale Bars to your Map Input Required Description Interval No Defines the intervals for the scale bar in pixels. Note: It is not recommended to define the intervals for the scale bar. By defining intervals, unwanted results might be calculated for those interval values (for example, miles). If setting the interval and width of the scale bar, you should define a value that is divisible into the width (for example, if your width is defined as 200, a value of 50 for the interval is recommended). Font Options No Allows you to set font options to display the scale bar text. The available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Java Code Sample The following code sample returns a base64 encoded data scale bar in PNG format. The scale bar is transparent and some font options have been set (Arial size 10). //Create a ScaleBar and add it to the OutputEx ScaleBar scalebar = new ScaleBar( image/png, Legend.CONTENT_BASE64);// Data scalebar.settransparent(true); //Add a Font to the ScaleBar Font font = new Font( Arial, 10); scalebar.setfont(font); //Add the ScaleBar to the OutputEx output.setscalebar(scalebar);.net Code Sample The following code sample returns the URL for the scale bar image in PNG format. There has been custom formatting done to modify the size and intervals of the scale bar. The scale bar has some font options have been set (Arial size 20). ScaleBar scalebar = new ScaleBar(500, 100, image/png, presentationcontenttype.url ); scalebar.font = new Font( Arial, 20); output.scalebar = scalebar; 36 Envinsa 4.1

37 Chapter 2: Creating and Modifying Maps XML Sample The following code sample returns a base64 encoded data scale bar in PNG format. There have been custom formatting done to modify the size and intervals of the scale bar. The scale bar is transparent and some font options have been set (Arial size 10). <ns3:scalebar content= Data format= image/png height= 50 interval= 50 transparent= true width= 200 > <ns3:font bold= false family= Arial italic= false size= 10 underline= false /> </ns3:scalebar> Creating a WBMP Map The Presentation Service provides support for exporting map images in WBMP, a graphics format for use in handheld devices such as wireless phones and PDAs. WBMP support in Envinsa includes two modes of output: thresholding for fast map display, or dithering which results in a nicer, but slower map display than thresholding. Each is explained below. Threshold Method for WBMP Output Thresholding is a rudimentary technique whereby each color pixel in the map is converted to grayscale and then compared to a set threshold, yielding a 0 (black) or 1 (white) representation (blank and white image). The algorithm used to determine if a particular pixel is translated into a 0 or 1 is as follows: The color is converted to grayscale (R+B+G/3), whereby R, B, and G represent the color values of the pixel in red, green, and blue (0, 255). If the value is greater than the threshold value, the pixel is set to 1 (white). If the value is less than or equal to the threshold value, the pixel color is 0 (black). The default threshold value is 127. By default, the Presentation Service performs a threshold conversion of the map automatically when you specify the mime type as image/vnd.wap.wbmp. Dithering Method for WBMP Output Dithering the map image will yield a higher quality map display than thresholding; however, it will take longer to render. Dithering takes into account the color of the pixel that is converted and creates a dithered pattern that is applied to the area where the color is used. Dithering is a process that adjusts adjacent pixels of different colors to give the illusion of a color that is not in the current color palette for the browser. The current dithering routine in the Presentation Service is the Floyd-Steinberg Error Diffusion routine. This method distributes the error during pixel quantization (color reduction) among neighboring pixels. This increases the apparent color resolution of the image that dithering alone does not do. Presentation Service Reference 37

38 Creating a WBMP Map Inputs and Behaviors When requesting a WBMP image, you can specify the following inputs: Input Required Description Output Mime Type Type of WBMP Yes No You must specify the mime type in the output. The mime type for WBMP is image/vnd.wap.wbmp. The WBMP format is a black and white format. There are two way to monochromatize a color image: dither or threshold (DITHERFS or THRESHOLD). The Default is to produce a dither image. Threshold No When the type of WBMP image is set to threshold, you can modify the default threshold. For XML, you define the value as an integer from 0 (zero) to 255. If the value is greater than the threshold value, the pixel is set to 1 (white). If the value is less than or equal to the threshold value, the pixel color is 0 (black). The default threshold value is 127. For the Java SDK you must specify the color in name format (for example, WHITE). The RGB value is converted to grayscale, the three values are added and divided by three (R+B+G/3) to get the 0 (zero) to 255 number value. You can use the color.decode method in the Sun Java SDK to transform a known hex number to a color name. For the.net SDK you must specify the color in RGB hex format (for example, #FFFFFF). The RGB number is then converted the same way as in the Java SDK (R+B+G/3) to get the 0 (zero) to 255 number value. Output The result of a threshold WBMP image will produce a black and white image based on the numeric value of the threshold: 38 Envinsa 4.1

39 Chapter 2: Creating and Modifying Maps The result of a dither WBMP image will produce a grayscale image based on the Floyd-Steinberg Error Diffusion routine: Presentation Service Reference 39

40 Creating a WBMP Map Java Code Sample The following Java sample creates a WBMP image where the color has been set to dither the monochrome image (true). The color value WHITE will be ignored. If creating a threshold WBMP image you can define your own threshold by defining the color. //specify the width, height and WBMP mime format in the map output OutputEx output = new OutputEx(100, 100, image/vnd.wap.wbmp ); output.setwbmpcontext(true, Color.WHITE); //return embedded image data. output.setpresentationcontent(output.content_url); maprequest.addoutput(output); //suppose that all layers should be visible, set nothing to exclude. Basemap basemap = new Basemap(Basemap.FILTER_EXCLUDE); maprequest.setbasemap(basemap);.net Code Sample The following sample creates a dither WBMP image. //specify the width, height and WBMP mime format in the map output Output output = new Output(100,100, image/vnd.wap.wbmp ); output.contenttype = presentationcontenttype.url; WBMPContext wbmp = new WBMPContext(); wbmp.type = WBMPType.DITHERFS; wbmp.threshold = #ffffff ; output.wbmpcontext = wbmp; maprequest.output = new Output[]{output}; //suppose that all layers should be visible, set nothing to exclude. Basemap basemap = new Basemap(LayerTypeFilter.Exclude); maprequest.basemap = basemap; XML Sample The following sample creates a dither WBMP image. <Output BGcolor= #ffffff content= URL format= image/vnd.wap.wbmp height= 500 returnzoomlevel= on transparent= true width= 500 xsi:type= ns3:outputtypeex xmlns:ns3= > <ns3:wbmpcontext type= DITHERFS /> </Output> 40 Envinsa 4.1

41 Overlaying Features 3 An important part of creating custom maps is the ability to render and stylize features not defined within the map display. The Presentation Service overlay capability allows you to overlay four types of features: RouteGeometry, Position, POI, and Map Objects. The Position overlay type has also been extended to overlay a Polyline on your maps. This allows you to set the style of the start point, the end point, and the polyline. In this section: Overlaying Points of Interests Overlaying a Route Geometry Overlaying a Geometry Overlaying and Stylize a Polyline Overlaying Two Maps

42 Overlaying Points of Interests The Presentation Service allows you to overlay a point of interest (POI) on your maps. This POI can be rendered with custom labeling and style. The default behavior of Envinsa is to display all labels above all features on a map. However, if you want to add an additional label or point of interest, you want to make sure that this point is labeled on top of all others. This can be done by using composite rendering, where the labels and features for the base map will get rendered below the feature in the overlay. The effect is to have the POI above any labels on the basemap or named layers. Note: The POI used in the overlay is usually a candidated from a Directory Service response. This response will include both the POI ID and point needed to populate the Presentation Service POI overlay request. Inputs and Behaviors Overlaying a point of interest requires you to specify the following information: Input Required Description Z Order No Determines the order which the overlays are rendered. If more that one overlay is being rendered you can control the order. A zorder=0 (zero) will be the top overlay followed by zorder=1, and so on. Composite Rendering Yes Allows the overlay to overlap the lower layers regardless of the order set for those layers. By default this is false (no overlap). If composite rendering is set to true for an overlay, it will override a composite rendering set for a layer. If more than one overlay has composite rendering set to true, the layers will be rendered in the order specified. POI ID Yes Defines the ID for the POI overlay. You must specify a unique ID for the POI. Point No Defines the point used for the position of the POI overlay. See the Client Developer Guide for more information on defining the various types of geometries. Overlay Style No Defines the style for the overlay. For a POI overlay this style defines the point style used for the POI. If no custom style is defined, the defaultpoistyle set in the Presentation Service configuration is used. Java Code Sample The following code sample shows a request that overlays POIs on a map. //display POI on the map Point poi = GeometryUtils.newPoint( , , EPSG:4326 ); PointOfInterestOverlay poioverlay = new PointOfInterestOverlay( poiid ); poioverlay.setpoint(poi); maprequest.addoverlay(poioverlay); 42 Envinsa 4.1

43 Chapter 3: Overlaying Features XML Sample The following code sample shows a request that overlays POIs on a map. <Overlay> <POI ID= poiid > <ns7:point srsname= EPSG:4326 xmlns:ns7= > <ns7:pos dimension= 2 > </ns7:pos> </ns7:point> </POI> </Overlay> Overlaying a Route Geometry The route geometry returned from a Route Service response can be overlaid on a map. The route geometry is rendered as a linestring with two pushpin styles at the start and end points by default. In addition, you can define custom named style for the linestring allowing more style control. Inputs and Behaviors A request to overlay a route geometry can take the following inputs: Input Required Description Z Order No Determines the order which the overlays are rendered. If more that one overlay is being rendered you can control the order. A zorder=0 (zero) will be the top overlay followed by zorder=1, and so on. Composite Rendering Yes Allows the overlay to overlap the lower layers regardless of the order set for those layers. By default this is false (no overlap). If composite rendering is set to true for an overlay, it will override a composite rendering set for a layer. If more than one overlay has composite rendering set to true, the layers will be rendered in the order specified. Route Geometry Yes Defines the route geometry used for the overlay. The linestring from the Route Service response can be directly used in the Presentation Service request. Overlay Style No Defines the style for the overlay. For a geometry overlay this style defines the point, line, or fills used for the geometry. If no custom style is defined, the routestartpointstyle, routeendpointstyle, and routelinestyle set in the Presentation Service configuration are used. Presentation Service Reference 43

44 Overlaying a Geometry Java Code Sample The following code sample shows where to insert the linestring from the Route Service response, then add the linestring to the route geometry overlay. RouteGeometry routegeo; // get routegeo from a route service response... //create a overlay with the route geometry RouteGeometryOverlay rgoverlay = new RouteGeometryOverlay(routeGeo.getLineString()); //Add the Overlay to the PortrayMapRequest maprequest.addoverlay(rgoverlay); XML Sample The following code sample shows how the linestring from the Route Service response can be used as a route geometry overlay in the Presentation Service, and styled with a custom pen. <Overlay xsi:type="ns3:overlaytypeex" compositerendering="false"> <RouteGeometry xsi:type="ns2:routegeometrytype"> <ns4:linestring srsname="epsg:4326" xsi:type="ns4:linestringtype" xmlns:ns4=" <ns4:pos xsi:type="ns4:directpositiontype"> </ ns4:pos> <ns4:pos xsi:type="ns4:directpositiontype"> </ns4:pos> <ns4:pos xsi:type="ns4:directpositiontype"> </ ns4:pos> <ns4:pos xsi:type="ns4:directpositiontype"> </ ns4:pos> <ns4:pos xsi:type="ns4:directpositiontype"> </ ns4:pos> <ns4:pos xsi:type="ns4:directpositiontype"> </ ns4:pos> </ns4:linestring> </RouteGeometry> <Style> <Name>WidePurplePen</Name> </Style> </Overlay> Overlaying a Geometry The geometry overlay allows you to define and overlay numerous GML and MapInfo geometries. You can overlay the following geometry types: Point 44 Envinsa 4.1

45 Chapter 3: Overlaying Features CircleByCenterPoint CircularArc Ellipse Polygon MultiPolygon In addition, you can define custom named styles for the geometry point, line, or fill. Inputs and Behaviors A request to overlay a geometry can take the following inputs: Input Required Description Z Order No Determines the order which the overlays are rendered. If more that one overlay is being rendered you can control the order. A zorder=0 (zero) will be the top overlay followed by zorder=1, and so on. Composite Rendering Position (Geometry) Yes Yes Allows the overlay to overlap the lower layers regardless of the order set for those layers. By default this is false (no overlap). If composite rendering is set to true for an overlay, it will override a composite rendering set for a layer. If more than one overlay has composite rendering set to true, the layers will be rendered in the order specified. Defines the geometry used for the overlay. See the Client Developer Guide for more information on defining the various types of geometries. Overlay Style No Defines the style for the overlay. For a geometry overlay this style defines the point, line, or fills used for the geometry. Java Code Sample The following code sample shows a request to overlay a polygon and add a named style to color the line of the polygon purple. //Create a GeometryOverlay GeometryOverlay geometryoverlay = new GeometryOverlay(); //Create the Polygon that will overlay the basemap try{ DirectPosition[] directposition = new DirectPosition[5]; directposition[0] = GeometryUtils.getXLSGMLFactory().newDirectPosition( , ); directposition[1] = GeometryUtils.getXLSGMLFactory().newDirectPosition( , ); directposition[2] = GeometryUtils.getXLSGMLFactory().newDirectPosition( , ); Presentation Service Reference 45

46 Overlaying a Geometry directposition[3] = GeometryUtils.getXLSGMLFactory().newDirectPosition( , ); directposition[4] = GeometryUtils.getXLSGMLFactory().newDirectPosition( , ); LinearRing linearring = GeometryUtils.getXLSGMLFactory().newLinearRing(directPosition); linearring.setsrs( EPSG:26910 ); Polygon polygon = GeometryUtils.getXLSGMLFactory().newPolygon(linearRing); geometryoverlay.setpolygon(polygon); } catch(exception ex){ ex.printstacktrace(); } //Add a Style to the overlay geometryoverlay.setstyle(new Style( WidePurplePen ));.NET Code Sample The following code sample shows a request to overlay two polygons //Geometry overlay Overlay overlay1 = new PositionOverlay (); double [,] ext = new double[,]{ { , }, { , }, { , }, { , }, { , } }; Polygon polygon = GeometryUtils.newPolygon(ext,null); ((PositionOverlay)overlay1).Polygon = polygon; Overlay overlay2 = new PositionOverlay (); double [,] ext2 = new double[,]{{ , }, { , }, { , }, { , }, { , } }; Polygon polygon2 = GeometryUtils.newPolygon(ext2,null); ((PositionOverlay)overlay2).Polygon = polygon2; Overlay [] overlays = {overlay1, overlay2}; pr.overlay = overlays; 46 Envinsa 4.1

47 Chapter 3: Overlaying Features XML Sample The following code sample shows a request to overlay a polygon and add a named style to color the line of the polygon purple. <Overlay xsi:type= ns3:overlaytypeex compositerendering= false > <Position> <ns7:polygon xmlns:ns7= > <ns7:exterior> <ns7:_ring xsi:type= ns7:linearringtype srsname= EPSG:26910 > <ns7:pos dimension= 2 > </ ns7:pos> <ns7:pos dimension= 2 > </ ns7:pos> <ns7:pos dimension= 2 > </ ns7:pos> <ns7:pos dimension= 2 > </ ns7:pos> <ns7:pos dimension= 2 > </ ns7:pos> </ns7:_ring> </ns7:exterior> </ns7:polygon> </Position> <Style> <Name>WidePurplePen</Name> </Style> </Overlay> Overlaying and Stylize a Polyline Similar to the route geometry is the polyline. However a route geometry is rendered as a polyline with two pushpin styles at the start and end points by default. The polyline overlay allows you to define and overlay a pure polyline. In addition, you can define custom named styles for the start points, end points, and linestrings for your polylines, allowing more style control than the route geometry overlay (for example number the points). Inputs and Behaviors A request to overlay a polyline can take the following inputs: Presentation Service Reference 47

48 Overlaying and Stylize a Polyline Input Required Description Z Order No Determines the order which the overlays are rendered. If more that one overlay is being rendered you can control the order. A zorder=0 (zero) will be the top overlay followed by zorder=1, and so on. Composite Rendering Yes Allows the overlay to overlap the lower layers regardless of the order set for those layers. By default this is false (no overlap). If composite rendering is set to true for an overlay, it will override a composite rendering set for a layer. If more than one overlay has composite rendering set to true, the layers will be rendered in the order specified. Polyline Yes Defines the polyline by adding one or more linestrings (draws a line between two points). Overlay Style No Defines the style for the overlay. For a polyline overlay this style defines the line style. Start Point Style No Defines the style used for the start point of the polyline. This must be defined by a named style. End Point Style No Defines the style used for the end point of the polyline. This must be defined by a named style. Java Code Sample The following example shows a polyline overlay made up of two lines. The start point of the first line has a style ViaPoint1 (the number one), the end point style of the first line has a style ViaPoint2. Since the second lines start point is the same as the first lines end point, there is no need to style this point, hence only the end point style is defined (ViaPoint3). xlsgmlfactory gmlfactory = GeometryUtils.getXLSGMLFactory(); Vector ls = new Vector(); ls.add(gmlfactory.newdirectposition( , )); ls.add(gmlfactory.newdirectposition( , )); LineString linestring1 = null; linestring1 = gmlfactory.newlinestring(ls); Polyline line1 = new Polyline(lineString1); line1.setstartpointstyle( ViaPoint1 ); line1.setendpointstyle( ViaPoint2 ); //created 2nd line gmlfactory = GeometryUtils.getXLSGMLFactory(); ls = new Vector(); ls.add(gmlfactory.newdirectposition( , )); ls.add(gmlfactory.newdirectposition( , )); LineString linestring2 = null; 48 Envinsa 4.1

49 Chapter 3: Overlaying Features linestring2 = gmlfactory.newlinestring(ls); Polyline line2 = new Polyline(lineString2); line2.setendpointstyle( ViaPoint3 ); PositionOverlayEx overlay=new PositionOverlayEx(); //overlay.set overlay.setpolylines(new Polyline[]{line1,line2}); //Add the Overlay to the PortrayMapRequestEx maprequest.addoverlay(overlay);.net Code Sample The following example shows a polyline overlay made up of two lines. The start point of the first line has a style ViaPoint1 (the number one), the end point style of the first line has a style ViaPoint2. Since the second lines start point is the same as the first lines end point, there is no need to style this point, hence only the end point style is defined (ViaPoint3). PortrayMapRequest maprequest = new PortrayMapRequest(); LineStringOverlay[] linestr = new LineStringOverlay[2]; Point[] vertex = new Point[2]; vertex[0] = GeometryUtils.newPoint( , ); vertex[1] = GeometryUtils.newPoint( , ); linestr[0] = new LineStringOverlay(GeometryUtils.newLineString(vertex,"")); linestr[0].startpointstyle = new Style("ViaPoint1"); linestr[0].endpointstyle = new Style("ViaPoint2"); Point[] vertex2 = new Point[2]; vertex2[0] = GeometryUtils.newPoint( , ); vertex2[1] = GeometryUtils.newPoint( , ); linestr[1] = new LineStringOverlay(GeometryUtils.newLineString(vertex2,"")); linestr[1].endpointstyle = new Style("ViaPoint3"); PositionOverlay posoverlay = new PositionOverlay(); posoverlay.iscompositerendering = false; posoverlay.polylines = linestr; //Add the Overlay to the PortrayMapRequestEx maprequest.overlay = new PositionOverlay[] {posoverlay}; XML Sample The following example shows a polyline overlay made up of two lines. The start point of the first line has a style ViaPoint1, the end point style of the first line has a style ViaPoint2. Since the second lines start point is the same as the first line s end point, there is no need to style this point, hence only the end point style is defined (ViaPoint3). <Overlay compositerendering= false xsi:type= ns3:overlaytypeex > Presentation Service Reference 49

50 Overlaying Two Maps <Position xsi:type= ns3:positionoverlaytypeex > <ns4:point xsi:type= ns4:pointtype xmlns:ns4= > <ns4:pos dimension= 2 xsi:type= ns4:directpositiontype > </ns4:pos> </ns4:point> <ns3:polyline> <ns5:linestring xsi:type= ns5:linestringtype xmlns:ns5= / > <ns5:pos dimension= 2 xsi:type= ns5:directpositiontype > </ns5:pos> <ns5:pos dimension= 2 xsi:type= ns5:directpositiontype > </ns5:pos> </ns5:linestring> <ns3:startpointstyle> <Name>ViaPoint1</Name> </ns3:startpointstyle> <ns3:endpointstyle> <Name>ViaPoint2</Name> </ns3:endpointstyle> </ns3:polyline> <ns3:polyline> <ns6:linestring xsi:type= ns6:linestringtype xmlns:ns6= / > <ns6:pos dimension= 2 xsi:type= ns6:directpositiontype > </ns6:pos> <ns6:pos dimension= 2 xsi:type= ns6:directpositiontype > </ns6:pos> </ns6:linestring> <ns3:endpointstyle> <Name>ViaPoint3</Name> </ns3:endpointstyle> </ns3:polyline> </Position> </Overlay> Overlaying Two Maps The Presentation Service can overlay one map on top of another map. There are many applications for this capability: displaying a local detailed map on top of a regional map or partially overlaying two maps for comparison reasons. However, the most commonly used application of this overlay type is displaying the output from a Web Mapping Service (WMS). The map overlay capability allows you to display a WMS image from a GetMap response. You can use the WMS response to show a satellite image, important features, or a weather map, and overlay these on top of your map. It is important that you keep in mind the format and transparency of the map or image that you are overlaying. For example, if you are overlaying a regional weather map on a political boundary map, you are going to want the weather map to have a transparent background to show the information on the boundary map. 50 Envinsa 4.1

51 Chapter 3: Overlaying Features Inputs and Behaviors A request to overlay a map takes the following inputs: Input Required Description Z Order No Determines the order which the overlays are rendered. If more that one overlay is being rendered you can control the order. A zorder=0 (zero) will be the top overlay followed by zorder=1, and so on. Composite Rendering Yes Allows the overlay to overlap the lower layers regardless of the order set for those layers. By default this is false (no overlap). If composite rendering is set to true for an overlay, it will override a composite rendering set for a layer. If more than one overlay has composite rendering set to true, the layers will be rendered in the order specified. Format Yes Specifies the image format (mime type) of the overlay map. Width Yes Specifies the width of the overlay map in pixel units. Height Yes Specifies the height of the overlay map in pixel units. Overlay Map Yes Defines the overlay map either by URL or encoded base64 data. Bounding Box No Defines the new map bounds based on the existing map. The bounding box for the coordinates is defined from the lower left corner to the upper right corner. Java Code Sample The following code sample shows how to create a map overlay from a WMS GetMap response. //Create a Map Overlay //specify the bounds, width, height and mime image format in the map output Envelope box = GeometryUtils.newEnvelope(-187,18,-66,71, EPSG:4326 ); String url= miwms?request=getmap&srs=epsg:4326&bbox=-187,18,- 66,71&WIDTH=400&HEIGHT=300&LAYERS=Demographic_Data/USA/Ranged_Themes/ race/demofin_st&styles=&format=image/png&transparent=true ; Overlay mapoverlay=new MapOverlay(box,400,300, image/png,url); //Add the Overlay to the PortrayMapRequestEx maprequest.addoverlay(mapoverlay); Presentation Service Reference 51

52 Overlaying Two Maps.NET Code Sample The following code sample shows how to create a map overlay from a WMS GetMap response. //specify the bounds, width, height and mime image format in the map output Point[] vertex = new Point[2]; vertex[0] = GeometryUtils.newPoint(-187,18); vertex[1] = GeometryUtils.newPoint(-66,71); Envelope box = GeometryUtils.newEnvelope(vertex, "EPSG:4326"); String url=" miwms?request=getmap&srs=epsg:4326&bbox=-187,18,- 66,71&WIDTH=400&HEIGHT=300&LAYERS=Demographic_Data/USA/Ranged_Themes/ race/demofin_st&styles=&format=image/png&transparent=true"; MapOverlay mapoverlay = new MapOverlay(); mapoverlay.bboxcontext = box; mapoverlay.width = 400; mapoverlay.height = 300; mapoverlay.url = url; mapoverlay.format = "image/png"; //Add the Overlay to the PortrayMapRequestEx maprequest.overlay = new MapOverlay[]{mapOverlay}; XML Sample The following code sample shows how to create a map overlay from a WMS GetMap response. <Overlay compositerendering= false xsi:type= ns3:overlaytypeex > <Map xsi:type= ns2:maptype > <Content format= image/png height= 300 width= 400 > <URL> miwms?request=getmap&srs=epsg:4326&bbox=-187,18,- 66,71&WIDTH=400&HEIGHT=300&LAYERS=Demographic_Data/USA/ Ranged_Themes/race/DemoFin_ST&STYLES=&FORMAT=image/ png&transparent=true</url> </Content> <BBoxContext srsname= EPSG:4326 > <ns5:pos dimension= 2 xsi:type= ns5:directpositiontype xmlns:ns5= > </ns5:pos> <ns6:pos dimension= 2 xsi:type= ns6:directpositiontype xmlns:ns6= > </ns6:pos> </BBoxContext> </Map> </Overlay> 52 Envinsa 4.1

53 Thematic Mapping Capabilities 4 This chapter discusses thematic mapping within the Presentation Service. Thematic mapping is a powerful way to analyze and visualize your data. In this section: Thematic Mapping Concepts Override Feature Theme Override Theme Label Control Ranged Feature Theme Ranged Label Theme Individual Value Theme Adding Theme Legends Adding Cartographic Legends

54 Thematic Mapping Concepts Huge quantities of information are available today, far more than ever before. Data abounds in spreadsheets, sales records, and marketing files. Paper and disks store masses of information on customers, stores, personnel, equipment, and resources. Nearly all of it has a geographic component. An estimated 85 percent of all databases contain some sort of geographic information such as street addresses, cities, states, postal codes, or even telephone numbers with area codes and exchange numbers. Thematic mapping can help you sort through all of this information, and using the geographic components in your data, display your results on a map. This type of mapping lets you see patterns and relationships in the mass of information quickly and easily without having to pore over your database. Thematic mapping is the process of shading your map according to a particular theme. This theme is usually based on some piece or pieces of geographic data, such as population density or population levels. The most commonly known example of a thematic map is a weather map. When you see red, you know it is hot (high number of degrees); where you see blue, it is cold (low number of degrees). Themes represent your data with shades of color, fill patterns, symbols, or labels. There are many uses for thematic maps to display your data. You create different thematic maps by assigning these colors, patterns, symbols, or labels to certain map features according to specific values in your data. The process of thematic mapping allows you to visualize and highlight trends in your data that would be difficult to see through tabular display. The Presentation Service offers three types of thematic maps. Each type has two variations: feature and label theme OverrideTheme Changes the rendition of an entire layer. Ranged Theme Groups data into ranges and shading based on range value. Individual Value Theme Shades groups of features which share a specific attribute value. The Presentation Service can generate legends for ranged and individual value themes. The information in the legend is tied directly to the theme. The legend is updated when the theme is changed. For information on creating theme legends, see Adding Theme Legends on page 77. Feature Versus Label Themes You thematically shade a map using layers from your data. When discussing themes, in general there are two types of layer information that make up a thematic map: features and labels. For more information on layers, please see Layer Concept in Chapter 5 on page 88. Feature Layers Feature thematics allow you to add themes to your map renditions, which use a layer dataset and modifies the layer s feature display characteristics. For example; region, point, and line styles. Regions Closed geometries that cover a given area. These include polygons, ellipses, circles, and circular arcs. For example, country boundaries, postal code boundaries, sales territories. Points Represent single locations of data. For example, customer locations, restaurants, parking meters. 54 Envinsa 4.1

55 Chapter 4: Thematic Mapping Capabilities Lines Open geometries that cover a given distance. These include lines, polylines, and arcs. Examples are streets, rivers, power lines. Label Layers Label thematics allow you to add themes to your map renditions, which use a layer dataset and modifies the layer s label display characteristics (text objects). Text objects Text that describes a map or another object, such as labels, titles, and symbols. For example, graduated symbol maps use symbols to represent different values. You can use graduated symbols regardless of the type of data with which you are working. For instance, use graduated symbols to show sales orders across states. With a graduated symbols theme, the Presentation Service can vary the size of each symbol according to the value in the sales order field. Planning for Thematic Mapping Before you create a thematic map, it is important know about the elements that make up a thematic map and how they are put together. This section will discuss thematic variables, where you can obtain your data, particularly using data from another table, and the arrangement and display of thematic layers. Know your variables The data that you display on your thematic map is called the thematic variable. Depending on the type of thematic analysis you are performing, your map can show one or more thematic variables. Ranges of values, grid shading, graduated symbols, dot density, and individual values maps all examine one variable. You can also create bivariate thematic maps, where one map object, such as a symbol, represents two different pieces of data. The symbol color, for example, can represent one thematic variable, and the symbol size can represent another. Know your data sources Before you begin your thematic map, you need to decide what information you want to display and locate where that information resides. The data you use to create themes may come from different types of data sources, have different column names, and have different values. Know which theme will display your data the best Each type of thematic map has its own purpose and unique attributes. For example, using a Ranged Theme, you could thematically shade a map of the world according to population density. You could shade the countries with graduated shades of red, the darkest red representing the most densely populated countries, and the palest red representing the least densely populated countries. At a glance you can see the distribution of the world s population. You are not limited to representing numeric values with thematic mapping. Nominal values also may be shaded thematically. For example, you have a dataset of underground cables. Those cables that haven t been serviced in the past six months are labeled priority status. Using a Individual Value Theme, you can shade the cables according to their repair status. All records with the same value will be shaded the same color. Presentation Service Reference 55

56 Override Feature Theme A good legend can go a long way Legends are an important part of making your map understandable to your audience. Using the Presentation Service, you can create two kinds of legends: cartographic and theme legends. Theme legends are those associated with thematic maps. Cartographic legends enable you to create a legend for any map layer(s). The combination of the two types makes it possible to provide cartographic data for all of your map layers. A pre-defined legend can be pickup by the given ImageName. You can define a legend on the fly by the given LegendContent. Override Feature Theme An override feature theme on the features of a layer (named layer, dynamic layer, grid layer) can be used to modify the existing look of how the fill, line, and point styles for that layer is displayed. For example, if you wanted all of the world countries to display with a red fill pattern and green line color, you would use an override feature theme. Inputs and Behaviors When creating an override feature theme, you can specify the following information: Input Required Description Feature Theme Yes Specifies that the type of override is for features. Style Yes Defines the new style used to override the existing layer style. All styles are defined using named styles. For more information on creating named styles, see the Map Management Guide. Java Code Sample The following code sample creates a simple override feature theme request, and overrides the World Countries named layer. The override changes the default fill style for all of the countries to the SolidRed named style. //create portray map request PortrayMapRequestEx maprequest = new PortrayMapRequestEx(METHOD_NAME, VERSION, R1 ); //create an OutputEx object OutputEx output = new OutputEx(400, 220, image/png ); output.setpresentationcontent(outputex.content_base64);// Data output.settransparent(false); output.setbgcolor(color.decode( # )); //Add the OutputEx to the PortrayMapRequestEx maprequest.addoutput(output); //Create a BaseMapEx 56 Envinsa 4.1

57 Chapter 4: Thematic Mapping Capabilities BasemapEx basemapex = new BasemapEx(BasemapEx.FILTER_INCLUDE); basemapex.setname( world ); //Set Layers for the BaseMapEx LayerContent[] layers = new LayerContent[2]; layers[0] = new LayerContent( World Countries ); //Set an OverrideTheme for the first Layer OverrideTheme overridetheme = new OverrideTheme(); //Set a Style to the OverrideTheme Style style = new Style( SolidRed ); ThemeStyle themestyle = new ThemeStyle(style); overridetheme.setthemestyle(themestyle); layers[0].setfeaturetheme(overridetheme); layers[1] = new LayerContent( Ocean (Robinson) ); //Add the Layers to the BaseMapEx basemapex.setlayercontent(layers); //Add the Basemap to the PortrayMapRequestEx maprequest.setbasemap(basemapex);.net Code Sample The following code sample creates a simple override feature theme request, and overrides the World Countries named layer. The override changes the default fill style for all of the countries to the SolidRed named style. PortrayMapRequest pr = new PortrayMapRequest(); pr.requestid = R1 ; //Set map outputs //output1: define the map format, size and context Output output1 = new Output(); output1.width = 800; output1.height = 600; output1.format = image/gif ; output1.contenttype = presentationcontenttype.url; Output[] outs = {output1}; pr.output = outs; //Create a BaseMap Basemap basemap = new Basemap(LayerTypeFilter.Include); basemap.name = world ;basemap.order = 1 ; //Add a Layer to the BaseMap LayerExtension layer0 = new LayerExtension( World Countries ); //Set an OverrideTheme for the first Layer OverrideTheme overridetheme = new OverrideTheme(); overridetheme.themestyle = new ThemeStyle( new Style( SolidRed )); Presentation Service Reference 57

58 Override Theme Label Control layer0.featuretheme = overridetheme; LayerExtension layer1 = new LayerExtension( Ocean (Robinson) ); GenericLayer [] layers = {layer0,layer1}; basemap.layerextension = layers; pr.basemap = basemap; XML Sample The following code sample creates a simple override feature theme on the World Countries named layer. The override changes the default fill style for all of the countries to the SolidRed named style. <ns3:layerex name= World Countries > <ns3:featuretheme> <ns3:overridetheme> <ns3:style> <Name>SolidRed</Name> </ns3:style> </ns3:overridetheme> </ns3:featuretheme> </ns3:layerex> Override Theme Label Control An override theme on the labels of a layer (named layer, dynamic layer, grid layer) can be used to modify the existing look of how the text for that layer is displayed. For example, if you want a particular country text larger than another country, you can override the label properties for the country layer, making the font larger. Inputs and Behaviors When creating an override label theme, you must specify the following information: Input Required Description Label Theme Yes Specifies that the type of override is for labels. Font Yes Modifies all of the available font style used for the layer. The available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. 58 Envinsa 4.1

59 Chapter 4: Thematic Mapping Capabilities Java Code Sample The following code sample creates a simple override label theme request, portraying all of the world countries, overriding the default label fonts for the named layer, making them 10 point Arial. //create portray map request PortrayMapRequestEx maprequest = new PortrayMapRequestEx(METHOD_NAME, VERSION, R1 ); //create an OutputEx object OutputEx output = new OutputEx(400, 220, image/png ); output.setpresentationcontent(outputex.content_base64);// Data output.settransparent(false); output.setbgcolor(color.decode( # )); //Add the OutputEx to the PortrayMapRequestEx maprequest.addoutput(output); //Create a BaseMapEx BasemapEx basemapex = new BasemapEx(BasemapEx.FILTER_INCLUDE); basemapex.setname( world ); basemapex.setorder(1); //Add a Layer to the BaseMapEx basemapex.addlayercontent(new LayerContent( Ocean (Robinson) )); //Add the Basemap to the PortrayMapRequestEx maprequest.setbasemap(basemapex); //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); namedlayer.setorder(0); //Create a DisplayRange for the NamedLayer namedlayer.setdisplayrange(new DisplayRange(1, , DistanceUnit.KM)); //turn on the label namedlayer.setautolabel(namedlayer.layer_autolabel_on); //Create a LabelTheme(OverrideTheme) for the NamedLayer OverrideTheme overridetheme = new OverrideTheme(); overridetheme.setthemestyle(new ThemeStyle(new Font( Arial, 10))); namedlayer.setlabeltheme(overridetheme); //Set NamedLayer LabelProperties autolabel namedlayer.setlabelproperties(new LabelProperties()); //Add the NamedLayer to the PortrayMapRequestEx maprequest.addnamedlayer(namedlayer); Presentation Service Reference 59

60 Override Theme Label Control.NET Code Sample The following code sample creates a simple override label theme request, portraying all of the world countries, overriding the default label fonts for the named layer, making them 10 point Arial. PortrayMapRequest pr = new PortrayMapRequest(); pr.requestid = R1 ; //Set map outputs //output1: define the map format, size and context Output output1 = new Output(); output1.width = 800; output1.height = 600; output1.format = image/gif ; output1.contenttype = presentationcontenttype.url; Output[] outs = {output1}; pr.output = outs; //Create a BaseMap Basemap basemap = new Basemap(LayerTypeFilter.Include); basemap.name = world ;basemap.order = 1 ; //Add a Layer to the BaseMap LayerExtension layer = new LayerExtension( Ocean (Robinson) ); GenericLayer [] layers = {layer}; basemap.layerextension = layers; pr.basemap = basemap; NamedLayer namedlayer = new NamedLayer( WorldCountries ); namedlayer.autolabel = on ; DisplayRange disprange = new DisplayRange(1, , DistanceUnitType.KM); namedlayer.displayrange = disprange; //Create a LabelTheme(OverrideTheme) for the NamedLayer OverrideTheme overridetheme = new OverrideTheme(); overridetheme.themestyle = new ThemeStyle(new Font( Arial, 10)); namedlayer.labeltheme = overridetheme; NamedLayer [] namedlayers = {namedlayer}; pr.namedlayer = namedlayers; XML Sample The following code sample creates a simple override label theme on the WorldCountries named layer. The override changes the default font settings for the layer to 10 point Arial. <ns3:namedlayer autolabel= on compositerendering= false name= WorldCountries order= 0 > <ns3:label duplicate= false overlap= false /> <ns3:displayrange maxzoom= minzoom= 1.0 unit= KM /> <ns3:labeltheme> <ns3:overridetheme> <ns3:font bold= false family= Arial italic= false size= 10 underline= false /> 60 Envinsa 4.1

61 Chapter 4: Thematic Mapping Capabilities </ns3:overridetheme> </ns3:labeltheme> </ns3:namedlayer> Ranged Feature Theme A ranged theme is a more complex type of thematic map. When you create a ranged thematic map, all features are grouped into ranges and each assigned a rendition for its corresponding range. For example, on a table of weather stations for your television viewing area, you can shade the locations according to their reported snowfall amounts. With the ranged map feature, the Presentation Service groups the snowfall amounts into ranges. For instance, all weather stations that received between zero and five inches of snowfall in the past month are grouped into one range. Stations receiving between five and ten inches are in a separate range. Sites that received between 10 and 15 inches are in a third range, while those stations reporting greater than 15-inch snowfall amounts are in a fourth range. Each range is referred to as a Bin. Each Bin has an upper-bound cut-off value. All records in the layer are assigned to a range and then assigned a rendition based on that range. For instance the weather stations reporting 15 plus inches of snow are shaded red. The other ranges are shaded in lighter shades of red with the last range in gray (default colors). When you display the map, the colors make it readily apparent which locations received the most and least snow accumulation. When you create a ranged thematic map, the Presentation Service groups all dataset rows into ranges and assigns each row s object the color, symbol, or line for its corresponding range. For example, you have a dataset of weather stations for your television viewing area, and you want to shade the locations according to their reported snowfall amounts. With the ranged map feature, the Presentation Service groups the snowfall amounts into ranges. For instance all weather stations that received between zero and five inches of snowfall in the past month are grouped into one range. Stations receiving between five and 10 inches are in a separate range. Sites that received between 10 and 15 inches are in a third range, while those stations reporting greater than 15 inch snowfall amounts are in a fourth range. All records in the dataset are assigned to a range and then assigned a color based on that range. For instance the weather stations reporting the 15 plus inches of snow are shaded red. The other ranges are shaded in lighter shades of red with the last range in gray (default colors). When you display the map, the colors make it readily apparent which locations received the most and least snow accumulation. Ranges are also useful when the size of the region is not directly related to the magnitude of the data values. Types of Ranged Themes The Presentation Service can create ranges using two methods: break point and gradation. The break point method allows you to define where you want to have the ranged breaks in your data and define the style associated with each break. The gradation method allows the Presentation Service Presentation Service Reference 61

62 Ranged Feature Theme to calculate the ranged breaks in your data and allows you to define the styles associated with the breaks. The gradation method has four ways of calculating the breaks: equal count, equal ranges, natural break, and standard deviation. Equal Count Equal Count has approximately the same number of records in each range. If you want to group 100 records into four ranges using equal count, it computes the ranges so that approximately 25 records fall into each range, depending on the rounding factor you set. When using Equal Count (or any other range method), it s important to watch out for any extreme data values that might affect your thematic map (in statistics, these values are referred to as outliers). For example, if you tell the Presentation Service to shade according to Equal Count with this dataset: John 5000 Andrea 7000 Penny 6000 Kyle 5500 Miguel 4500 Angela 7500 Linda 5000 Elroy 6000 Ben 100 Mark 7000 Ben and Miguel are grouped in the same range (since they have the two lowest values). This may not produce the results you want since the value for Ben is so much lower than any of the other values. Equal Ranges Equal Ranges divides records across ranges of equal size. For example, you have a field in your table with data values ranging from 1 to 100. You want to create a thematic map with four equal size ranges. The Bucketer produces ranges 1 25, 26 50, 51 75, and Keep in mind that the Presentation Service may create ranges with no data records, depending on the distribution of your data. For example, if you tell the Presentation Service to shade the following database according to Equal Ranges: John 100 Andrea 90 Penny 6 Kyle 1 Miguel 4 Angela 92 Linda 95 Elroy 89 Ben 10 Mark Envinsa 4.1

63 Chapter 4: Thematic Mapping Capabilities The Presentation Service creates four ranges (1 25, 25 50, 50 75, and ). Notice, however, that only two of those ranges (1 25 and ) actually contain records. Using the Natural Break theme is one way to show data that is not evenly distributed. Natural Break Natural Break creates ranges according to an algorithm that uses the average of each range to distribute the data more evenly across the ranges. It distributes the values so that the average of each range is as close as possible to each of the range values in that range. This ensures that the ranges are well-represented by their averages, and that data values within each of the ranges are fairly close together. Standard Deviation Standard Deviation breaks at the middle range of the mean of your values, and the ranges above and below the middle range are one standard deviation above or below the mean. Inputs and Behaviors for Gradation When defining a gradation ranged feature theme, you must specify the following information: Input Required Description Feature Ranged Theme Yes Specifies that the type of ranged theme is for features. Column Yes Defines the column in the layer used to create the thematic groupings of your data. Number Yes Defines the number of thematic groupings you want the Presentation Service to use for the gradation calculations. Begin Style Yes Defines the style used for the first thematic grouping of your data. All styles are defined using named styles. For more information on creating named styles, see the Map Management Guide. End Style Yes Defines the style used for the last thematic grouping of your data. All styles are defined using named styles. For more information on creating named styles, see the Map Management Guide. Type Yes Defines the type of thematic calculation performed by the Presentation Service to display your data. The available types are EqualCount, EqualRanges, StandardDeviation, and NaturalBreak. See Types of Ranged Themes on page 61 for a description of these types. Presentation Service Reference 63

64 Ranged Feature Theme Inputs and Behaviors for Break Point When defining a break point ranged feature theme, you can specify the following information: Input Required Description Feature Ranged Theme Yes Specifies that the type of ranged theme is for features. Column Yes Defines the column in the layer used to create the thematic groupings of your data. Individual Value Yes Specifies the values used to group the data. You must specify a value for each of the break points. When creating break point ranged themes you must have a thorough knowledge of your data. This allows you to create break points in your data at divisions that represent meaningful groupings. If you do not know the maximum value in your data, you can specify an empty value for the last break point (and assign a style). The Presentation Service will calculate this grouping from the last specified value to the highest known value in your data. Note: You should use a two character format when specifying alphabetical break points in your data. For example, if you want to group a listing of names, you could define your break points as Fz, Mz, Tz, and Zz. Using z as the second character assures that all of the names starting with the first character are placed in that grouping. Description No Defines the text used to describe your break points when displayed in a legend. Since you are defining your break points using a single character or number, these would have little meaning if displayed in a legend. By defining a description of the break points you can add meaningful text to display in your legend. For example, a break point set to Fz might have a description A to F. Style Yes Defines the style used for the thematic grouping of your data. You must specify a style for each of the break points. All styles are defined using named styles. For more information on creating named styles, see the Map Management Guide. 64 Envinsa 4.1

65 Chapter 4: Thematic Mapping Capabilities Java Code Sample Gradation The following sample shows how to define a gradation ranged theme, where the Presentation Service will calculate the groupings. This example will create ten groupings and the type of gradation theme is defined as TYPE_EQUAL_COUNT. The first grouping will have the SolidYellow style and the last grouping will have the SolidRed style. All other intermediate grouping styles will be calculated by the Presentation Service. layers[0] = new LayerContent( World Countries ); //Set the FeatureTheme for the first layer. The FeatureTheme is represented as a RangedTheme that //display the world countries in different styles based on the specified gradation //Create the Gradation object Gradation gradationstyle = new Gradation(10); //Set the Gradation type gradationstyle.settype(gradation.type_equal_count); //Set the Gradation BeginStyle gradationstyle.setbeginstyle(new ThemeStyle(new Style( SolidYellow ))); //Set the Gradation EndStyle gradationstyle.setendstyle(new ThemeStyle(new Style( SolidRed ))); RangedTheme rangedthemestyle = new RangedTheme( Pop_1994, gradationstyle); layers[0].setfeaturetheme(rangedthemestyle); Break Point The following sample shows how to define ranged break point thematic groupings for the Pop_1994 column in the World Countries layer. There are four break points defined, each with an associated value. //Create a PortrayMapRequestEx PortrayMapRequestEx maprequest = new PortrayMapRequestEx(METHOD_NAME, VERSION, R1 ); //Create an OutputEx object and add it to the PortrayMapRequestEx OutputEx output = new OutputEx(400, 220, image/png ); output.setbgcolor(color.decode( # )); output.settransparent(false); output.setpresentationcontent(outputex.content_base64);// Data //Add the OutputEx to the PortrayMapRequestEx maprequest.addoutput(output); //Create a Basemap that contains two Layers. One Layer(World Countries) contains a RangedTheme that //display the world countries in different styles based on the specified breakpoints Presentation Service Reference 65

66 Ranged Feature Theme BasemapEx basemap = null; //Create the Layers that will compose the Basemap LayerContent[] layers = new LayerContent[2]; layers[0] = new LayerContent( World Countries ); //Set the FeatureTheme for the first Layer. The FeatureTheme is represented as a RangedTheme //Create the BreakPoints that will set the range for the RangedTheme IndividualValueStyle[] breakpoints = new IndividualValueStyle[4]; breakpoints[0] = new IndividualValueStyle( , new Style( SolidBlue )); breakpoints[1] = new IndividualValueStyle( , new Style( SolidYellow )); breakpoints[2] = new IndividualValueStyle( , new Style( SolidRed )); breakpoints[3] = new IndividualValueStyle( , new Style( SolidGreen )); RangedTheme rangedtheme = new RangedTheme( Pop_1994, breakpoints); layers[0].setfeaturetheme(rangedtheme); //Create the second layer of the Basemap layers[1] = new LayerContent( Ocean (Robinson) ); basemap = new BasemapEx(layers, BasemapEx.FILTER_INCLUDE); //set the name of the Basemap basemap.setname( world ); //Add the BasemapEx to the PortrayMapRequestEx maprequest.setbasemap(basemap);.net Code Sample Break Point The following sample shows how to define ranged break point thematic groupings for the Pop_1994 column in the WorldCountries named layer. There are four break points defined, each with an associated value. Basemap basemap = new Basemap(LayerTypeFilter.Include); basemap.name = world ; pr.basemap = basemap; NamedLayer namedlayer = new NamedLayer( WorldCountries ); namedlayer.autolabel = on ; //Set the FeatureTheme for the first Layer. The FeatureTheme is represented as a RangedTheme //Create the BreakPoints that will set the range for the RangedTheme 66 Envinsa 4.1

67 Chapter 4: Thematic Mapping Capabilities IndividualStyle individualstyle1 = new IndividualStyle( , new Style( SolidBlue )); IndividualStyle individualstyle2 = new IndividualStyle( , new Style( SolidYellow )); IndividualStyle individualstyle3 = new IndividualStyle( , new Style( SolidRed )); IndividualStyle individualstyle4 = new IndividualStyle( , new Style( SolidGreen )); IndividualStyle[] breakpoints = {individualstyle1, individualstyle2, individualstyle3, individualstyle4}; //add individual styles RangedTheme rangedthemestyle = new RangedTheme( Pop_1994, breakpoints); //Create a Legend for the RangedTheme Legend legend = new Legend(200, 300, image/gif, Pop1994, presentationcontenttype.url); //Set the background color of the Legend legend.bgcolor = #00FF00 ; //Add the Legend to the RangedTheme rangedthemestyle.legend = legend; namedlayer.featuretheme = rangedthemestyle; NamedLayer[]layers ={namedlayer}; pr.namedlayer = layers; XML Sample Gradation The following sample shows how to define a gradation ranged theme, where the Presentation Service will calculate the groupings. This example will create ten groupings and the type of gradation theme is defined as EqualCount. The first grouping will have the SolidYellow style and the last grouping will have the SolidRed style. All other intermediate grouping styles will be calculated by the Presentation Service. <ns3:featuretheme> <ns3:rangedtheme column= Pop_1994 > <ns3:gradation number= 10 > <ns3:beginstyle> <ns3:style> <Name>SolidYellow</Name> </ns3:style> </ns3:beginstyle> <ns3:endstyle> <ns3:style> <Name>SolidRed</Name> Presentation Service Reference 67

68 Ranged Feature Theme </ns3:style> </ns3:endstyle> <ns3:type>equalcount</ns3:type> </ns3:gradation> </ns3:rangedtheme> </ns3:featuretheme> Break Point The following sample shows how to define ranged break point thematic groupings for the Pop_1994 column in the World Countries layer. There are four break points defined, each with an associated value. <ns3:layerex name= World Countries > <ns3:featuretheme> <ns3:rangedtheme column= Pop_1994 > <ns3:breakpoint individualvalue= > <ns3:style> <Name>SolidBlue</Name> </ns3:style> </ns3:breakpoint> <ns3:breakpoint individualvalue= > <ns3:style> <Name>SolidYellow</Name> </ns3:style> </ns3:breakpoint> <ns3:breakpoint individualvalue= > <ns3:style> <Name>SolidRed</Name> </ns3:style> </ns3:breakpoint> <ns3:breakpoint individualvalue= > <ns3:style> <Name>SolidGreen</Name> </ns3:style> </ns3:breakpoint> </ns3:rangedtheme> </ns3:featuretheme> </ns3:layerex> 68 Envinsa 4.1

69 Chapter 4: Thematic Mapping Capabilities Ranged Label Theme A ranged label theme creates a range theme in which labels are drawn with a range style. Ranged label themes are useful when you want to use the labels to convey information about what you are labeling. For example, you could use a ranged label theme when labeling city or town populations. The label of a city with a large population would have a larger font than the label of a town with a small population. Ranged label themes can have the groupings calculated by the Presentation Service using gradation or specified using break points. For more information on the concept of ranged themes, see Ranged Feature Theme on page 61. Inputs and Behaviors for Gradation When defining a gradation ranged label theme, you must specify the following information: Input Required Description Label Ranged Theme Yes Specifies that the type of ranged theme is for labels. Column Yes Defines the column in the layer used to create the thematic groupings of your data. Number Yes Defines the number of thematic groupings you want the Presentation Service to use for the gradation calculations. Begin Font Yes Defines the font used for the first thematic grouping of your data (usually a smaller font). When defining the font, the available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. End Font Yes Defines the font used for the last thematic grouping of your data (usually a larger font). When defining the font, the available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Type Yes Defines the type of thematic calculation performed by the Presentation Service to display your data. The available types are EqualCount, EqualRanges, StandardDeviation, and NaturalBreak. See Types of Ranged Themes on page 61 for a description of these types. Presentation Service Reference 69

70 Ranged Label Theme Inputs and Behaviors for Break Point When defining a break point ranged label theme, you can specify the following information: Input Required Description Label Ranged Theme Yes Specifies that the type of ranged theme is for labels. Column Yes Defines the column in the layer used to create the thematic groupings of your data. Individual Value Yes Specifies the values used to group the data. You must specify a value for each of the break points. When creating break point ranged themes you must have a thorough knowledge of your data. This allows you to create break points in your data at divisions that represent meaningful groupings. If you do not know the maximum value in your data, you can specify an empty value for the last break point (and assign a style). The Presentation Service will calculate this grouping from the last specified value to the highest known value in your data. Note: You should use a two character format when specifying alphabetical break points in your data. For example, if you want to group a listing of names, you could define your break points as Fz, Mz, Tz, and Zz. Using z as the second character assures that all of the names starting with the first character are placed in that grouping. Description No Defines the text used to describe your break points when displayed in a legend. Since you are defining your break points using a single character or number, these would have little meaning if displayed in a legend. By defining a description of the break points you can add meaningful text to display in your legend. For example, a break point set to 1000 might have a description Cities < 1000 Pop. Font Yes For each of the defined break points, you must define the font used for the thematic grouping of your data. When defining the font, the available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Java Code Sample The following sample shows how to define a gradation ranged label theme, where the Presentation Service will calculate groupings of the world population values. This example will create ten groupings and the type of gradation theme is defined as TYPE_EQUAL_COUNT. The theme will 70 Envinsa 4.1

71 Chapter 4: Thematic Mapping Capabilities show the calculated groupings of population values in the defined font styles. The first grouping will be blue (#0000ff) 7 point Arial font and the last grouping will be green (#00ff00) 20 point Arial font. All other intermediate grouping fonts will be calculated by the Presentation Service. //Set the LabelTheme for the first layer. The LabelTheme is represented as a RangedTheme that //displays the label of the world countries using different fonts based on the specified gradation Gradation gradationfont = new Gradation(10); //Set the Gradation BeginStyle //Create the begin Font Font fontbegin = new Font( Arial, 7); fontbegin.setfgcolor(color.decode( #0000ff )); gradationfont.setbeginstyle(new ThemeStyle(fontBegin)); //Set the Gradation EndStyle Font fontend = new Font( Arial, 20); fontend.setfgcolor(color.decode( #00ff00 )); gradationfont.setendstyle(new ThemeStyle(fontEnd)); //Set the Gradation type gradationfont.settype(gradation.type_equal_count); RangedTheme rangedthemefont = new RangedTheme( Pop_1994, gradationfont); layers[0].setlabeltheme(rangedthemefont); //Create the second layer of the Basemap layers[1] = new LayerContent( Ocean (Robinson) ); basemap = new BasemapEx(layers, BasemapEx.FILTER_INCLUDE); //set the name of the Basemap basemap.setname( world ); //Add the BasemapEx to the PortrayMapRequestEx maprequest.setbasemap(basemap);.net Code Sample The following sample shows how to define a gradation ranged label theme, where the Presentation Service will calculate groupings of the world population values. This example will create ten groupings and the type of gradation theme is defined as EqualCount. The theme will show the calculated groupings of population values in the defined font styles. The first grouping will be blue (#0000ff) 7 point Arial font and the last grouping will be green (#00ff00) 20 point Arial and font. All other intermediate grouping fonts will be calculated by the Presentation Service. NamedLayer namedlayer = new NamedLayer( WorldCountries ); namedlayer.autolabel = on ; //Set the FeatureTheme for the NamedLayer. The FeatureTheme is represented as a RangedTheme that Presentation Service Reference 71

72 Ranged Label Theme //display the world countries in different styles based on the specified gradation //Create the Gradation object Gradation gradationfont = new Gradation(10); //Set the Gradation type gradationfont.distributiontype = DistributionType.EqualCount; //Set the Gradation BeginStyle gradationfont.beginstyle = new ThemeStyle(new Font( Arial, 7)); //Set the Gradation EndStyle gradationfont.endstyle = new ThemeStyle(new Font( Arial, 20)); RangedTheme rangedthemefont = new RangedTheme( Pop_1994, gradationfont); LayerExtension layer1 = new LayerExtension( World Countries ); layer1.labeltheme = rangedthemefont; LayerExtension layer2 = new LayerExtension( Ocean (Robinson) ); LayerExtension [] layers = {layer1, layer2}; basemap.layerextension = layers; pr.basemap = basemap; XML Sample The following sample shows how to define a gradation ranged label theme, where the Presentation Service will calculate the groupings of the world population values. This example will create ten groupings and the type of gradation theme is defined as EqualCount. The theme will show the calculated groupings of population values in the defined font styles. The first grouping will be blue (#0000ff) 7 point Arial font and the last grouping will be green (#00ff00) 20 point Arial font. All other intermediate grouping fonts will be calculated by the Presentation Service. <ns3:labeltheme> <ns3:rangedtheme column= Pop_1994 > <ns3:gradation number= 10 > <ns3:beginstyle> <ns3:font FGcolor= #0000ff bold= false family= Arial italic= false size= 7 underline= false /> </ns3:beginstyle> <ns3:endstyle> <ns3:font FGcolor= #00ff00 bold= false family= Arial italic= false size= 20 underline= false /> </ns3:endstyle> <ns3:type>equalcount</ns3:type> </ns3:gradation> </ns3:rangedtheme> </ns3:labeltheme> 72 Envinsa 4.1

73 Chapter 4: Thematic Mapping Capabilities Individual Value Theme Individual value themes show points, lines, or boundaries that are shaded by individual values contained in a particular field of your data. This type of theme allows the thematic shading of features based on specific attribute values for a specified column. For example, use an individual value theme to modify the renditions of region features in a coverage dataset based on the values in the territories column. Territories with type values of southwest could be red, while values of southeast could be shaded blue. You can use both numerical and nominal values in individual values maps. The Presentation Service gives each unique value its own color or symbol. When an individual values map uses symbol types, the symbols are taken from the default style of the map. For example, a soft drink distributor maintains a table of the supermarkets that buy soft drinks from him by postal code in Washington D.C. Each supermarket sells the distributor s brand of soft drink for a different price. If the distributor shades the postal code boundaries by price, using individual values, all stores that sell the soft drink for 49 cents are shaded one color, all stores that sell the soft drink for 51 cents are shaded another color, and so on. Each unique value is assigned its own color. The distributor is able to see the price distribution among the supermarkets and can determine where he should increase his sales volume, based on the price. If you are shading your points, lines, or boundaries using nominal data, you can shade only by individual values. Nominal data is either numeric or non-numeric data. Examples of non-numeric data include name, type of cuisine served, or brand of automobile sold. Dates are considered numeric data and can be used in both ranged and individual values maps. For example, you have the results from a consumer survey. One question on the survey reads What is your favorite Sunday afternoon activity? The possible responses are: 1. Sleeping 2. Watching TV 3. Taking a drive 4. Reading 5. Playing or watching sports 6. Visiting museums or art galleries 7. Going to the movies You want to shade each consumer point with the response for the favorite Sunday activity. The Sunday field of your dataset contains the number that corresponds to the consumer s favorite activity. However, the numbers in this column do not represent quantitative values. Going to the movies is not greater than playing or watching sports even though 7 > 5. When numbers are used as names instead of values, you must shade your objects by individual values. The numbers are only used to reference the pastimes so a color can be assigned to it. Individual Value Label Theme An individual value label theme creates a thematic map which uses the layer's data as labels, and generates the theme based on the value of these labels. As with ranged label themes, individual value label themes are also useful when you want use the labels to convey information about what Presentation Service Reference 73

74 Individual Value Theme you are labeling. When working with street data, for example, you could use an individual value label theme to label different types of roads with different fonts. In this case, a highway would be represented by a label with a different style than the label for a county road. Inputs and Behaviors When defining an individual value theme, you can specify the following information: Input Required Description Feature or Label Value Theme Yes Specifies that the type of individual value theme is for features and labels. Column Yes Defines the column that has the individual values you would like to use to create the theme. Individual Value Yes Specifies the value from the column of your data for each of the individual values that you want to apply a theme. When creating individual value themes you must have a thorough knowledge of your data. This allows you to create themes that represent meaningful analysis. For example you can create a world map continent theme by specifying the continent names for the values and apply a style. Description No Defines the text used to describe your individual values when displayed in a legend. Sometimes the values used for the theme will have little meaning if displayed in a legend. By defining a description of the individual values you can add meaningful text to display in your legend. For example, a value of dense urban might have a description Urban Area Pop > 2 million. Style/Font Yes Defines a style or font for each of the defined values. Styles are for features and font are for labels. All styles are defined using named styles. For more information on creating named styles, see the Map Management Guide. When defining the font, the available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Java Code Sample The following sample shows how to create an individual value feature theme where the world countries layer will display countries in different colors based on the assigned style for the continent column. //Create a PortrayMapRequestEx PortrayMapRequestEx maprequest = new PortrayMapRequestEx(METHOD_NAME, 74 Envinsa 4.1

75 Chapter 4: Thematic Mapping Capabilities VERSION, R1 ); //Create an OutputEx object and add it to the PortrayMapRequestEx OutputEx output = new OutputEx(400, 220, image/png ); output.setbgcolor(color.decode( # )); output.settransparent(false); output.setpresentationcontent(outputex.content_base64);// Data //Add the OutputEx to the PortrayMapRequestEx maprequest.addoutput(output); //Create a Basemap that contains one layer //Create the Layers that will compose the Basemap LayerContent[] layers = new LayerContent[2]; //Create the first layer that will compose the Basemap layers[0] = new LayerContent( World Countries ); //Create a FeatureTheme which is represented as an IndividualTheme //Create an IndividualTheme //Create an array of IndividualStyle and attach it to the IndividualTheme IndividualValueStyle[] individualstyle = new IndividualValueStyle[5]; individualstyle[0] = new IndividualValueStyle( Africa, new Style( SolidBlue )); individualstyle[1] = new IndividualValueStyle( South America, new Style( SolidGreen )); individualstyle[2] = new IndividualValueStyle( Asia, new Style( SolidYellow )); individualstyle[3] = new IndividualValueStyle( North America, new Style( SolidRed )); individualstyle[4] = new IndividualValueStyle( Europe, new Style( SolidRed )); IndividualValueTheme individualtheme = new IndividualValueTheme( Continent, individualstyle); //Create a Legend for the IndividualTheme Legend legend = new Legend( image/png, Continents, Legend.CONTENT_BASE64);// Data legend.settitlestyle(new Font( arial, 20)); //Add the Legend to the IndividualTheme individualtheme.setlegend(legend); //Add the FeatureTheme to the first layer layers[0].setfeaturetheme(individualtheme); //Create the second layer that will compose the Basemap layers[1] = new LayerContent( Ocean (Robinson) ); //Add the layers to the BasemapEx Presentation Service Reference 75

76 Individual Value Theme BasemapEx basemap = new BasemapEx(layers, BasemapEx.FILTER_INCLUDE); basemap.setname( world ); //Add the BasemapEx to the PortrayMapRequestEx maprequest.setbasemap(basemap);.net Code Sample The following sample shows how to create an individual value feature theme where the world countries layer will display countries in different colors based on the assigned style for the continent column. PortrayMapRequest pr = new PortrayMapRequest(); pr.requestid = R3 ; //Set map output with map format and size Output output = new Output(500,500, image/gif ); output.transparent = true; output.contenttype = presentationcontenttype.url; Output[] outs = {output}; pr.output = outs; //Create a BaseMap including an extended layer Basemap basemap = new Basemap(); basemap.name = world ; basemap.filter = LayerTypeFilter.Include; LayerExtension layer1 = new LayerExtension( World Countries ); IndividualTheme individualvaluetheme = new IndividualTheme( Continent ); IndividualStyle [] styles = new IndividualStyle[5]; styles[0] = new IndividualStyle( Africa, new Style( SolidBlue )); styles[1] = new IndividualStyle( South America, new Style( SolidGreen )); styles[2] = new IndividualStyle( Asia, new Style( SolidYellow )); styles[3] = new IndividualStyle( North America, new Style( SolidRed )); styles[4] = new IndividualStyle( Europe, new Style( SolidRed )); individualvaluetheme.individualstyle = styles; layer1.featuretheme = individualvaluetheme; //Create a Legend for the IndividualTheme Legend legend = new Legend(100, 500, image/png, Continents, presentationcontenttype.data); legend.titlestyle = new Font( arial, 20); //Add the Legend to the IndividualTheme individualvaluetheme.legend = legend; LayerExtension layer2 = new LayerExtension( Ocean (Robinson) ); GenericLayer [] layers = {layer1, layer2}; basemap.layerextension = layers; pr.basemap = basemap; 76 Envinsa 4.1

77 Chapter 4: Thematic Mapping Capabilities XML Sample The following sample shows how to create an individual value feature theme where the world countries layer will display countries in different colors based on the assigned style for the continent column. <ns3:featuretheme> <ns3:individualvaluetheme column= Continent > <ns3:individualvaluestyle individualvalue= Africa > <ns3:style> <Name>SolidBlue</Name> </ns3:style> </ns3:individualvaluestyle> <ns3:individualvaluestyle individualvalue= South America > <ns3:style> <Name>SolidGreen</Name> </ns3:style> </ns3:individualvaluestyle> <ns3:individualvaluestyle individualvalue= Asia > <ns3:style> <Name>SolidYellow</Name> </ns3:style> </ns3:individualvaluestyle> <ns3:individualvaluestyle individualvalue= North America > <ns3:style> <Name>SolidRed</Name> </ns3:style> </ns3:individualvaluestyle> <ns3:individualvaluestyle individualvalue= Europe > <ns3:style> <Name>SolidRed</Name> </ns3:style> </ns3:individualvaluestyle> <ns3:legend content= URL format= image/png transparent= false > <ns3:title>continents</ns3:title> <ns3:titlestyle bold= false family= arial italic= false size= 20 underline= false /> </ns3:legend> </ns3:individualvaluetheme> </ns3:featuretheme> Adding Theme Legends You can create a legend for your Ranged or Individual Value theme based on the data and how you have assigned styles to your divisions. You have a lot of control over how the legend will look. You can change the title, fonts, and insets, as well as modify the descriptive text and colors. Theme legends provide a key of colors, symbols, and styles used for themes. This key explains what the colors, symbols, and styles represent. Presentation Service Reference 77

78 Adding Theme Legends A theme legend is useful whenever you have a map that contains themes. With a weather map that displays precipitation, rainfall may be represented by varying shades of green. A theme legend would be important in visually explaining that the darkest shade of green represents the highest amount of rainfall while lighter shades represent lower amounts of rainfall. Inputs and Behaviors When creating a cartographic legend, you can specify the following information: Input Required Description Background Color No Background Color of the legend. The default is #FFFFFF (hex number or White (name color). For both XML and.net SDK requests you must specify the color in RGB hex format (for example, #FFFFFF), for the Java SDK you must specify the color in name format (for example, White). You can use the color.decode method in the Sun Java SDK to transform a hex number to a color name. Image Format Yes Specifies what the encoding of the legend should be. This is specified as a mime-type. The supported mime-types are GIF, JPEG, and PNG (for example, image/png or image/jpeg). Width No The width of the legend in screen pixel units. Height No The height of the legend in screen pixel units. Legend Content No Specifies what type of content will be returned, either as URL or Data (base64 encoded image). The default is URL. Geometry Type No Defines the type of legend feature rendered. The geometry type can be Point, Line, or Region. Point geometries are used to create legends for cities, POIs, or landmarks. Line geometries are used to create legends for roads, rivers, or trains. Region geometries are used to create legends for countries, land types, or population distributions. Transparency No Boolean that defines the opacity of the background of the legend. The default is false (not transparent). Label Order No Ascending or Descending. Title Yes You must define a title used to describe your legend. 78 Envinsa 4.1

79 Chapter 4: Thematic Mapping Capabilities Input Required Description Title Style No Defines the font style used for the title of your legend. The available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Key Style No Defines the font style used for the individual key text of your legend. The available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Java Code Sample This code sample shows how to create a theme legend, based on a Ranged theme defined in the request. The legend is returned as base64 data in the response representing a.png image. The legend is created using values from the Pop1994 column. The background color of the legend is set to LIGHT_GREY. //Create a PortrayMapRequestEx PortrayMapRequestEx maprequest = new PortrayMapRequestEx(METHOD_NAME, VERSION, R1 ); //Create an OutputEx object and add it to the PortrayMapRequestEx OutputEx output = new OutputEx(400, 220, image/png ); output.setbgcolor(color.decode( # )); output.settransparent(false); output.setpresentationcontent(outputex.content_base64);// Data //Add the OutputEx to the PortrayMapRequestEx maprequest.addoutput(output); //Create a Basemap that contains one layer BasemapEx basemap = new BasemapEx(BasemapEx.FILTER_INCLUDE); basemap.setname( world ); //Add the BasemapEx to the PortrayMapRequestEx maprequest.setbasemap(basemap); //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //Set the FeatureTheme for the NamedLayer. The FeatureTheme is represented as a RangedTheme that //display the world countries in different styles based on the specified gradation //Create the Gradation object Gradation gradationstyle = new Gradation(10); Presentation Service Reference 79

80 Adding Theme Legends //Set the Gradation type gradationstyle.settype(gradation.type_equal_count); //Set the Gradation BeginStyle gradationstyle.setbeginstyle(new ThemeStyle(new Style( SolidYellow ))); //Set the Gradation EndStyle gradationstyle.setendstyle(new ThemeStyle(new Style( SolidRed ))); RangedTheme rangedthemestyle = new RangedTheme( Pop_1994, gradationstyle); //Create a Legend for the RangedTheme Legend legend = new Legend( image/png, Pop1994, Legend.CONTENT_BASE64);// Data //Set the background color of the Legend legend.setbgcolor(color.light_gray); //Add the Legend to the RangedTheme rangedthemestyle.setlegend(legend); //Add the RangedTheme to the NamedLayer namedlayer.setfeaturetheme(rangedthemestyle); //Add the NamedLayer to the PortrayMapRequestEx maprequest.addnamedlayer(namedlayer);.net Code Sample This code sample shows how to create a theme legend, based on a Ranged theme defined in the request. The legend is returned as a URL in the response pointing to the.gif image on the file system. The legend is created using values from the Pop1994 column. The legend is 200 by 300 pixels in size and the background color of the legend is set to bright green (#00FF00). Basemap basemap = new Basemap(LayerTypeFilter.Include); basemap.name = world ; pr.basemap = basemap; NamedLayer namedlayer = new NamedLayer( WorldCountries ); namedlayer.autolabel = on ; //Set the FeatureTheme for the NamedLayer. The FeatureTheme is represented as a RangedTheme that //display the world countries in different styles based on the specified gradation //Create the Gradation object Gradation gradationstyle = new Gradation(10); //Set the Gradation type gradationstyle.distributiontype = DistributionType.EqualCount; //Set the Gradation BeginStyle gradationstyle.beginstyle = new ThemeStyle(new Style( SolidYellow )); 80 Envinsa 4.1

81 Chapter 4: Thematic Mapping Capabilities //Set the Gradation EndStyle gradationstyle.endstyle = new ThemeStyle(new Style( SolidRed )); RangedTheme rangedthemestyle = new RangedTheme( Pop_1994, gradationstyle); //Create a Legend for the RangedTheme Legend legend = new Legend(200, 300, image/gif, Pop1994, presentationcontenttype.url); //Set the background color of the Legend legend.bgcolor = #00FF00 ; //Add the Legend to the RangedTheme rangedthemestyle.legend = legend; namedlayer.featuretheme = rangedthemestyle; NamedLayer[]layers ={namedlayer}; pr.namedlayer = layers; XML Sample This code sample shows how to create a theme legend, based on a Ranged theme defined in the request. The legend is returned as a URL in the response pointing to the.png image on the file system. The legend is created using values from the Pop1994 column. A title is created for the legend and the background color of the legend is set to light grey (#c0c0c0). <ns3:namedlayer compositerendering= false name= WorldCountries > <ns3:featuretheme> <ns3:rangedtheme column= Pop_1994 > <ns3:gradation number= 10 > <ns3:beginstyle> <ns3:style> <Name>SolidYellow</Name> </ns3:style> </ns3:beginstyle> <ns3:endstyle> <ns3:style> <Name>SolidRed</Name> </ns3:style> </ns3:endstyle> <ns3:type>equalcount</ns3:type> </ns3:gradation> <ns3:legend BGcolor= #c0c0c0 content= URL format= image/png transparent= false > <ns3:title>pop1994</ns3:title> </ns3:legend> </ns3:rangedtheme> </ns3:featuretheme> Presentation Service Reference 81

82 Adding Cartographic Legends </ns3:namedlayer> Adding Cartographic Legends Cartographic legends display independent data for map layers. A legend is created for each layer that you choose to include in the legend. You can create a legend for an individual layer, giving it particular emphasis, or you can place legends for several layers in one legend. Many of the attributes of the cartographic legend can be customized, allowing you to enhance your map presentation. Furthermore, when creating a cartographic legend, you have the ability to use multiple datasets on-the-fly through the use of a named resource, thus allowing you to obtain legend feature descriptions from another datasets while you are creating the legend. A cartographic legend is very useful whenever you have a map that contains objects that represent items on the map. For example, a map with landmarks requires a cartographic legend. Hospitals, schools, churches, and airports would each be represented by a different symbol. The cartographic legend provides a visual explanation of the different types of landmarks that are represented on the map. Inputs and Behaviors When creating a cartographic legend, you can specify the following information: 82 Envinsa 4.1

83 Chapter 4: Thematic Mapping Capabilities Input Required Description Background Color No Specifies the background color of the legend. The default is #FFFFFF (hex number or White (name color). For both XML and.net SDK requests, you must specify the color in RGB hex format (for example, #FFFFFF), for the Java SDK you must specify the color in name format (for example, White). You can use the color.decode method in the Sun Java SDK to transform a hex number to a color name. Image Format Yes Specifies what the encoding of the legend should be. This is specified as a mime-type. The supported mime-types are GIF, JPEG, and PNG (for example, image/png or image/jpeg). Width No Specifies the width of the legend in screen pixel units. Height No Specifies the height of the legend in screen pixel units. Legend Content No Specifies what type of content will be returned, either as URL or Data (base64 encoded image). The default is URL. Geometry Type No Defines the type of legend feature rendered. The geometry type can be Point, Line, or Region. Point geometries are used to create legends for cities, POIs, or landmarks. Line geometries are used to create legends for roads, rivers, or trains. Region geometries are used to create legends for countries, land types, or population distributions. Transparency No Defines the opacity of the background of the legend. The default is false (not transparent). Label Order No Specifies the order the labels are displayed. The value can be either Ascending or Descending. Title Yes Defines a title used to describe your legend. Title Style No Defines the font style used for the title of your legend. The available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Key Style No Defines the font style used for the individual key text of your legend. The available options are family, size, foreground and background color, background mode, italic, bold, and underline. See Font Options in Chapter 5 on page 120 for more information on customizing fonts. Presentation Service Reference 83

84 Adding Cartographic Legends Input Required Description Key Layer Yes Specifies the name of the layer that contains the features to be displayed in the legend. Key Column Yes Specifies the column in the layer used to describe the features in the legend. Named Layer Yes Defines if the layer used for the legend is a named layer. The default is false. Java Code Sample The following sample shows how to create a cartographic legend. This example creates two legends in a single request. The first legend is a point legend that describes landmarks from the lk layer (based on the Name column). The second legend is a line legend that describes streets from the d1_s layer (based on the Name column) and streets from the d2_s layer (based on the StreetName column). Both legends are returned as base64 data. //create portray map request PortrayMapRequestEx maprequest = new PortrayMapRequestEx(METHOD_NAME, VERSION, R1 ); //create an OutputEx object that contains the CartographicLegend OutputEx output = new OutputEx(300, 300, image/png ); output.setpresentationcontent(outputex.content_base64);// Data //Create a CartographicLegendContent CartographicLegendContent[] legendcontent = new CartographicLegendContent[2]; //Create LegendKey for the CartographicLegendContent LegendKey[] legendkey = new LegendKey[1]; legendkey[0] = new LegendKey( lk, Name, false); legendcontent[0] = new CartographicLegendContent( image/png, LandMark, OutputEx.CONTENT_BASE64, legendkey);// Data legendcontent[0].setbgcolor(color.light_gray); //Set the GeometryType of the CartographicLegendContent legendcontent[0].setgeometrytype(legend.geometry_point); legendkey = new LegendKey[2]; legendkey[0] = new LegendKey( d1_s, Name, false); legendkey[1] = new LegendKey( d2_s, StreetName, false); legendcontent[1] = new CartographicLegendContent( image/png, Streets, OutputEx.CONTENT_BASE64, legendkey);// Data 84 Envinsa 4.1

85 legendcontent[1].setbgcolor(color.light_gray); //Set the GeometryType of the CartographicLegendContent legendcontent[1].setgeometrytype(legend.geometry_line); //set legend content output.setlegendcontent(legendcontent); //Add the OutputEx to the PortrayMapRequestEx maprequest.addoutput(output); //Create a BaseMap BasemapEx basemapex = new BasemapEx(); basemapex.setname( MapDisplay/low ); //Add the Basemap to the PortrayMapRequestEx maprequest.setbasemap(basemapex); Chapter 4: Thematic Mapping Capabilities.NET Code Sample The following sample shows how to create a cartographic legend. This example creates one legend being returned as a URL to the image created on the file system. The legend is a point legend that describes landmarks from the lk layer (based on the Name column). PortrayMapRequest pr = new PortrayMapRequest(); pr.requestid = R1 ; //Set map outputs //output1: define the map format, size and context Output output1 = new Output(); output1.width = 500; output1.height = 500; output1.format = image/gif ; CenterContext cc = new CenterContext(); cc.srs = EPSG:4326 ; cc.radius = new Distance(0.5); cc.centerpoint = GeometryUtils.newPoint( , , EPSG:4326 ); output1.centercontext = cc; CartographicLegendContent legendcontent = new CartographicLegendContent(); legendcontent.width = 400; legendcontent.height = 400; legendcontent.format = image/gif ; legendcontent.contenttype = presentationcontenttype.url; legendcontent.title = landmark ; LegendKey [] lkeys = new LegendKey[1]; lkeys[0] = new LegendKey(); lkeys[0].layername = lk ; lkeys[0].descriptioncolumn = Name ; lkeys[0].namedlayer = false; Presentation Service Reference 85

86 Adding Cartographic Legends legendcontent.legendkey = lkeys; //legendcontent.legendgeometrytype = LegendGeometryType.Point; CartographicLegendContent[] legendcontents = {legendcontent}; output1.legendcontent = legendcontents; Output[] outs = {output1}; pr.output = outs; //assume that all layers should be visible, set nothing to exclude. Basemap basemap = new Basemap( MapDisplay/low ); basemap.filter = LayerTypeFilter.Exclude; pr.basemap = basemap; XML Sample The following sample shows how to create a cartographic legend. This example creates two legends in a single request. The first legend is a point legend that describes landmarks from the lk layer (based on the Name column). The second legend is a line legend that describes streets from the d1_s layer (based on the Name column) and streets from the d2_s layer (based on the StreetName column). <Output xsi:type= ns3:outputtypeex BGcolor= #ffffff content= URL format= image/png height= 300 returnzoomlevel= on transparent= true width= 300 > <ns3:cartographiclegend> <ns3:legendcontent BGcolor= #c0c0c0 content= URL format= image/png geometrytype= Point transparent= false > <ns3:title>landmark</ns3:title> <ns3:keys descriptioncolumn= Name layername= lk namedlayer= false /> </ns3:legendcontent> <ns3:legendcontent BGcolor= #c0c0c0 content= URL format= image/png geometrytype= Line transparent= false > <ns3:title>streets</ns3:title> <ns3:keys descriptioncolumn= Name layername= d1_s namedlayer= false /> <ns3:keys descriptioncolumn= StreetName layername= d2_s namedlayer= false /> </ns3:legendcontent> </ns3:cartographiclegend> <ns3:vrmlcontext imagetextureformat= image/gif spec= GeoVRML11 > <ns3:geometryoverlay/> </ns3:vrmlcontext> </Output> 86 Envinsa 4.1

87 Layer and Label Control Capabilities 5 This section describes the concept of layers and how to control layers for effective mapping applications. The Presentation Service provides extensive control on layer labeling, ordering, accessibility, and visibility. When using layers to create a map, you can specify the layer label definition including content, position, visibility range, and the display range of the layer (visibility based on the zoom range) This section describes how to manage a layer s order, visibility, and labeling In this section: Layer Concept Defining Named Layers Defining Analysis Layers (Charts) Defining Raster Layers (WMS Layer) Setting the Layer Order Defining Content Layers and Filters in the Request Adding Custom Styles to Your Layers Setting the Display Range of Your Layers Labeling Your Map Layers

88 Layer Concept MapInfo maps are organized into layers containing map features. Think of the layers as transparencies that are stacked on top of one another. Each layer contains different aspects of the whole map. For example, one layer may contain state boundaries, a second layer may have symbols that represent capitals, a third layer might consist of text labels. By stacking these layers one on top of the other, you begin to build a complete map. You can display one, two, or many layers at a time. Map layers form the building blocks of maps for the Presentation Service. Once you have created your map of layers, you can customize the layers in a variety of ways, add and delete layers, or reorder them. Each layer may be altered at design-time, or programmatically during run-time. A Layer collection is made up of (0 - n) Layers. The Layer object is made up of a collection of features, with each feature having its own properties and styles. A collection of features is made up of Feature objects, which correspond to a feature on the map such as a point, line, or region. Map Features as Layers We mentioned earlier that maps in the Presentation Service are made up of layers of map features. There are four basic types of features: Regions Closed objects that cover a given area. These include polygons, ellipses, and rectangles. For example, country boundaries, postal code boundaries, sales territories. Point objects Single locations of data. For example, customer locations, restaurants, and parking meters. Line objects Open objects that cover a given distance. These include lines, polylines, and arcs. Examples are streets, rivers, and power lines. Text objects Text that describes a map or another object, such as labels and titles. You can have each type of object in a separate layer (most common), or you can combine objects in the same layer. You can have each type of feature in a separate layer (most common), or you can combine features in the same layer. The Presentation Service provides tools that allow you to create, edit, customize, and display these features to make maps that meet your needs. When discussing layers, in general there are two types of layers that make up a map: 88 Envinsa 4.1

89 Chapter 5: Layer and Label Control Capabilities Annotation layers Annotation layers are special map layers that contain features which mark or place emphasis on certain areas of the map. Typically, features returned from a search, such as finding the nearest cinemas, are added to the Annotation Layer. Map data layers Map data layers are layers that contain geographical data such as streets, waterways, buildings, and city boundaries. Static Layers Static layers are named layers which are always rendered during the portray map process. The static layer is always a named layer. The layer rendering order is defined in the services configuration. The topmost static layer is logo layer (overlay), which can define logo and copyright information. For further description on how to configure static layers, see Static Layer Preferences in Chapter 7 on page 137. Defining Named Layers Named layers are map layers that you give a unique name to, so that you can recall the layer by name in the future. Named layers have the same benefits as other named resources: The resource is known by its name and not by its properties. The resource resides in one location but can be referenced from many locations. To change the look or behavior of applications or data the resource only need be changed, not each application or data file. You can manage your named layers using the Map Manager utility provided with Envinsa. For more information on the Map Manager and named resources, refer to the Map Management Guide. Inputs and Behaviors When defining a named layer in the request, you can define the following information: Input Required Description Layer Name Yes Specifies the unique name for the named layer that you are referencing. Auto Label No Determines if the layer is going to be labeled in the map. Set auto label to on for the layer to be labeled. Composite Rendering No Allows the layer to overlap the lower layers regardless of the order set for the layers. By default this is false (no overlap). Presentation Service Reference 89

90 Defining Named Layers Input Required Description Layer Order No Determines the layer order. By default the layer will be ordered based on the Presentation Service defaults. For more information on determining the order for the layer, see Setting the Layer Order on page 107. To make the layer the top layer, specify the order=0. Enabled No Determines if the layer will be rendered in the map. By default the layer will be rendered (true). This is a useful tool when displaying analysis layers. You can display the chart and not display the layer used to create the chart. Layer Style No Specifies a style for the layer when rendered. See Adding Custom Styles to Your Layers on page 116. Layer Label No Specifies the qualities of the labels on a layer with full labeling capabilities. These qualities include the style in which they display, what priority they have, and in what position. For more information on Labeling, see Labeling Your Map Layers on page 118. Display Range Feature or Label Theme No No Defines the zoom settings at which the layer is displayed. You can set the minimum, maximum, and unit for the display range. See Setting the Display Range of Your Layers on page 117 for more information. Defines a feature or label theme for your layer. Layers are the basis for creating themed maps. See Chapter 4: Thematic Mapping Capabilities for more information on using layers to create themes. Java Code Sample The following example defines two named layers (SFGeoTif and SFElevation) and sets the order to display the SFElevation layer on top of the SFGeoTif layer. //Create an array of NamedLayer NamedLayer[] namedlayer = new NamedLayer[2]; namedlayer[0] = new NamedLayer( SFGeoTif ); namedlayer[0].setorder(2); namedlayer[1] = new NamedLayer( SFElevation ); namedlayer[1].setorder(1); //Add the NamedLayer to the PortrayMapRequestEx maprequest.setnamedlayer(namedlayer); 90 Envinsa 4.1

91 Chapter 5: Layer and Label Control Capabilities.NET Code Sample The following example defines two named layers (SFGeoTif and SFElevation) and sets the order to display the SFElevation layer on top of the SFGeoTif layer. //add named layers to the map //create an array of NamedLayer NamedLayer namedlayer1 = new NamedLayer( SFGeoTif );namedlayer1.order=2; NamedLayer namedlayer2 = new NamedLayer( SFElevation );namedlayer2.order=1; NamedLayer[] namedlayer = {namedlayer1, namedlayer2}; //add the NamedLayer to the PortrayMapRequest pr.namedlayer = namedlayer; XML Sample The following example defines two named layers (SFGeoTif and SFElevation) and sets the order to display the SFElevation layer on top of the SFGeoTif layer. <ns3:namedlayer compositerendering= false name= SFGeoTif order= 2 /> <ns3:namedlayer compositerendering= false name= SFElevation order= 1 / > Defining Analysis Layers (Charts) Analysis layers provide you the capability to display information based on expressions that can span multiple attributes in you data. There are two types of analysis layers: Bar Chart Layers are themes that contain bar charts with bars that represent each data value. A bar chart is built for each map object (feature), at the centroid of the object, for the layer. This enables you to analyze several thematic variables in a particular chart by comparing the height of the bars. Pie Chart Layers are themes that contain pie charts with wedges that represent each data value. In pie charts, you compare the wedges in a single pie, or examine a particular pie wedge across all of the pies. Both pie and bar charts are particularly useful for analyzing demographic data. The chart will be created at the centroid of each feature retrieved from the layer. The chart can be created from a basemap layer, a named layer, or a layer created from a Content in the Content manager (CMLayer). For more information about the Content Manager, refer to the Content Manager Guide. For example, you can analyze a dataset of demographic information for the world that shows the populations of several major demographic groups. Using a pie chart layer, you can show the population of each demographic group, and visually see the fraction of the pie for the group population. Presentation Service Reference 91

92 Defining Analysis Layers (Charts) Bar Chart Layers Bar themes are useful for examining the same variable across all the features in your map. For example, you have a table of U.S. state boundaries containing female and male population. Using bar charts, you can create a thematic map that displays a two bar chart for each state: one bar representing female, and the other representing male population. You can compare the population differences of each state, or you can examine several states and compare population differences to the others. Stacked Bar Chart Layer A stacked bar chart has all the categories composing one bar for each feature. The user specifies the height of the bar chart with the largest sum. The following stacked bar charts show the distribution of 3 population groups (45-54, 55-59, 60-64) on a per state basis. Side-by-Side Bar Chart Layer One bar for each category comprises the chart for each feature. The user specifies the height of the bar that represents the largest value. The Presentation Service will determine the heights for all other bars. The following bar charts show the distribution of three population groups (45-54, 55-59, 60-64) on a per state basis. Inputs and Behaviors When defining a bar chart in the request, you can define the following information: Input Required Description Layer Name Yes Defines a unique name for your analysis layer. You must specify the unique name. Reference Type Yes Defines the type of layer being used to define the chart. The available layer types are NamedLayer, DynamicLayer (used for CMLayer), and BasemapLayer. 92 Envinsa 4.1

93 Chapter 5: Layer and Label Control Capabilities Input Required Description Reference Layer Yes Specifies the layer used to define the chart. Layer Order No Determines the layer order. By default, the layer will be ordered based on the Presentation Service defaults. For more information on determining the order for the layer, see Setting the Layer Order on page 107. To make the layer the top layer, specify the order=0. Composite Rendering No Allows the layer to overlap the lower layers regardless of the order set for the layers. By default, this is false (no overlap). Offset No Defines the number of pixels the chart will display in the direction of the alignment from the centroid of the feature. The default is 0 (zero). Alignment No Defines the chart position relative to the centroid of the feature you are describing. Charts can be oriented in any of nine different positions relative to the centroid: Center Left LowerLeft UpperLeft Right LowerRight UpperRight Top Bottom Width No Defines the width of each bar in pixels. The default width is ten (10) pixels Type of Chart No Defines the type of chart. There are two types of bar charts: Stacked and SideBySide. The default chart type is Stacked. Columns Yes Defines the columns of the reference layer being used to supply the data for your chart. Each column defined will create a bar in each chart. For each column you must define a fill style. Line Style No Defines the line style used to draw a border around each bar. The style is defined using a named style. The line style is optional and if a style is not specified, no border will be drawn around the bar. Presentation Service Reference 93

94 Defining Analysis Layers (Charts) Input Required Description Legend No Specifies the qualities of an included legend. See Adding Theme Legends in Chapter 4 on page 77 for more information on the parameters used for adding legends to your layers. Display Range No Defines the zoom settings at which the layer is displayed. You can set the minimum, maximum, and unit for the display range. See Setting the Display Range of Your Layers on page 117 for more information. Chart Size No Defines the size of the individual charts by gradation or a fixed size in pixels. A bar chart defined by a maximum size will have the largest value (or sum of values) equal to that size (height of bar). The value of the size must be between 5 and 500. If no default maximum size is defined, the maximum size will be calculated by the Presentation Service for optimal appearance. A bar chart defined by gradation, changes the height of the main bar and the individual bars within according to a reference value, maximum bar size, and an equation (method). All bars are subsequently sized relative to the bar size based on the sum of their values. If you do not specify a value at a defined size (height), the value used is the maximum of all the values. Three equations (methods) of gradation are available: Constant, SquareRoot, or Log (natural base 10). The SquareRoot method should be used if there are large differences between your data ranges. Note: The Log method should not be used if you have 0 (zero) or null values in your data. Java Code Sample Stacked Bar Chart This code sample shows how to create a stacked bar chart. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //Add the NamedLayer to the PortrayMapRequestEx maprequest.addnamedlayer(namedlayer); //Create a Bar chart layer 94 Envinsa 4.1

95 Chapter 5: Layer and Label Control Capabilities BarChartLayer barchartlayer=new BarChartLayer( BarChartLayer, WorldCountries,BarChartLayer.LAYER_TYPE_ NAMED_LAYER); barchartlayer.setbarcharttype(barchartlayer.chart_type_stacked); barchartlayer.setwidth(10); barchartlayer.setgraduationproperties( , 10, BarChartLayer.GRADUATION_METHODS_SQUAREROOT); ChartColumn[] cols=new ChartColumn[3]; cols[0]= new ChartColumn( Pop_0_14, SolidYellow ); cols[1]= new ChartColumn( Pop_15_64, SolidRed ); cols[2]= new ChartColumn( Pop_65Plus, SolidGreen ); barchartlayer.setcolumns(cols); //set chart legend Legend legend = new Legend( image/png, Pop1994, Legend.CONTENT_URL);// Data barchartlayer.setlegend(legend); maprequest.addbarchartlayer(barchartlayer);.net Code Sample Stacked Bar Chart This code sample shows how to create a stacked bar chart. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //Add the NamedLayer to the PortrayMapRequestEx maprequest.namedlayer = new NamedLayer[]{namedLayer}; //Create a Bar chart layer BarChartLayer barchartlayer = new BarChartLayer( BarChartLayer, WorldCountries, RefLayer.NAMEDLAYER); barchartlayer.type = BarChart.STACKED; barchartlayer.width = 10; GraduationProperties gp = new GraduationProperties(); gp.referencevalue = ; gp.size = 10; gp.method = GraduationMethods.SQUAREROOT; ChartSize cs = new ChartSize(); cs.graduationproperties = gp; barchartlayer.chartsize = cs; ChartColumn[] cols=new ChartColumn[3]; Presentation Service Reference 95

96 Defining Analysis Layers (Charts) cols[0]= new ChartColumn( Pop_0_14, new Style( SolidYellow )); cols[1]= new ChartColumn( Pop_15_64,new Style( SolidRed )); cols[2]= new ChartColumn( Pop_65Plus,new Style( SolidGreen )); barchartlayer.columns = cols; //set chart legend Legend legend = new Legend( image/png, Pop1994,presentationContentType.URL); barchartlayer.legend = legend; maprequest.barchartlayer = new BarChartLayer[]{barChartLayer}; XML Sample Stacked Bar Chart This code sample shows how to create a stacked bar chart. <ns3:namedlayer name= WorldCountries /> <ns3:barchartlayer name= BarChartLayer referencelayer= WorldCountries referencetype= NamedLayer type= Stacked width= 10 > <ns3:columns> <ns3:columnname>pop_0_14</ns3:columnname> <ns3:fillstyle> <Name>SolidYellow</Name> </ns3:fillstyle> </ns3:columns> <ns3:columns> <ns3:columnname>pop_15_64</ns3:columnname> <ns3:fillstyle> <Name>SolidRed</Name> </ns3:fillstyle> </ns3:columns> <ns3:columns> <ns3:columnname>pop_65plus</ns3:columnname> <ns3:fillstyle> <Name>SolidGreen</Name> </ns3:fillstyle> </ns3:columns> <ns3:legend content= URL format= image/png > <ns3:title>pop1994</ns3:title> </ns3:legend> <ns3:chartsize> <ns3:graduationproperties> <ns3:referencevalue> </ns3:referencevalue> <ns3:size>10</ns3:size> <ns3:method>squareroot</ns3:method> </ns3:graduationproperties> </ns3:chartsize> </ns3:barchartlayer> 96 Envinsa 4.1

97 Chapter 5: Layer and Label Control Capabilities Pie Chart Layers Pie charts are particularly useful for analyzing demographic data. For example, you have a dataset of demographic information for the United States. Your dataset shows the populations of several major demographic groups. Using pie charts, you can show the population of each demographic group, and see what fraction of the pie it makes up in each chart. This enables you to see the distribution of demographic groups on a per state basis, or across the entire United States. You can also look at one demographic group and see how the relative population of the group varies in different states. Variable Pie Chart Layer Using a pie chart layer, you can show the population of each demographic group, and visually see the fraction of the pie for the group population. The following map shows how to use a pie chart layer to show the distribution of three population groups on a percountry basis. The size of pie charts reflects the sum of the total population: Equal Size Pie Chart Layer To simplify a pie chart you can create charts with fixed sizes, known as equal size pie charts. This allows you to only indicate one relationship between the data. For example if you want to show the percentage of population groups: Presentation Service Reference 97

98 Defining Analysis Layers (Charts) Inputs and Behaviors When defining a pie chart in the request, you can define the following information: Input Required Description Layer Name Yes Defines a unique name for your analysis layer. You must specify the unique name. Reference Type Yes Defines the type of layer being used to define the chart. The available layer types are NamedLayer, DynamicLayer (used for CMLayer), and BasemapLayer. Reference Layer Yes Specifies the layer used to define the chart. Layer Order No Determines the layer order. By default the layer will be ordered based on the Presentation Service defaults. For more information on determining the order for the layer, see Setting the Layer Order on page 107. To make the layer the top layer, specify the order=0. Composite Rendering No Allows the layer to overlap the lower layers regardless of the order set for the layers. By default, this is false (no overlap). Offset No Defines the number of pixels the chart will display in the direction of the alignment from the centroid of the feature. The default is 0 (zero). Alignment No Defines the chart position relative to the centroid of the feature you are describing. Charts can be oriented in any of nine different positions relative to the centroid: Center Left LowerLeft UpperLeft Right LowerRight UpperRight Top Bottom Clockwise No Determines if the pie chart sections are rendered in clockwise or counterclockwise order. The default is true, rendering the pie chart in clockwise order. Start Angle No Defines the starting angle for the first pie section in decimal degrees. The default start angle is Envinsa 4.1

99 Chapter 5: Layer and Label Control Capabilities Input Required Description Type of Chart No Defines the type of chart. There are two types of pie charts: Full and Half. The default chart type is Full. A Full chart type specifies an equal pie chart, where all charts are the same size defined by the maximum chart size. A Half chart type specifies a pie chart where the size of the chart is determined by the sum of column values, and largest chart is determined by the chart size set. Columns Yes Defines the columns of the reference layer being used to supply the data for your chart. Each column defined will create a pie in each chart. For each column you must define a fill style. Line Style No Defines the line style used to draw a border around each pie. The style is defined using a named style. The line style is optional and if a style is not specified, no border will be drawn around the pie. Legend No Specifies the qualities of an included legend. See Adding Theme Legends in Chapter 4 on page 77 for more information on the parameters used for adding legends to your layers. Display Range No Defines the zoom settings at which the layer is displayed. You can set the minimum, maximum, and unit for the display range. See Setting the Display Range of Your Layers on page 117 for more information. Presentation Service Reference 99

100 Defining Analysis Layers (Charts) Input Required Description Chart Size No Defines the radius of the individual charts by gradation or a fixed size in pixel units. A pie chart defined by a maximum size will have the largest value (or sum of values) equal to that size (radius of pie section). For an equal pie chart, the maximum size defines the size for all charts. The value of the size must be between 5 and 500. If no maximum size is defined, the maximum size will be calculated by the Presentation Service for optimal appearance. A pie chart defined by gradation, changes the radius of the largest pie by defining a reference value, size (radius in pixels), and an equation (method). All pies are subsequently sized relative to this pie size based on the sum of their values. If you do not specify a value at a defined size (radius), the value used is the maximum of all the values. Three equations (methods) of gradation are available: Constant, SquareRoot, or Log (natural base 10). The SquareRoot method should be used if there are large differences between your data ranges. Note: The Log method should not be used if you have 0 (zero) or null values in your data. Java Code Sample Pie Chart The following code sample shows how to create a pie chart making the size of the individual charts vary depending on the data. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //Add the NamedLayer to the PortrayMapRequestEx maprequest.addnamedlayer(namedlayer); //Create a pie chart layer PieChartLayer piechartlayer=new PieChartLayer( piechartlayer, WorldCountries,PieChartLayer.LAYER_TYPE_ NAMED_LAYER); piechartlayer.setpiecharttype(piechartlayer.chart_type_half); ChartColumn[] cols=new ChartColumn[3]; cols[0]= new ChartColumn( Pop_0_14, SolidBlue ); cols[1]= new ChartColumn( Pop_15_64, SolidGreen ); cols[2]= new ChartColumn( Pop_65Plus, SolidYellow ); 100 Envinsa 4.1

101 Chapter 5: Layer and Label Control Capabilities piechartlayer.setcolumns(cols); maprequest.addpiechartlayer(piechartlayer); Equal Pie Chart The following code sample shows how to create a pie chart making the size of the individual charts equal. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //set it invisiable namedlayer.enablelayer(false); //Add the NamedLayer to the PortrayMapRequestEx maprequest.addnamedlayer(namedlayer); //Create a FullPie chart layer PieChartLayer piechartlayer=new PieChartLayer( piechartlayer, WorldCountries,PieChartLayer.LAYER_TYPE_ NAMED_LAYER); piechartlayer.setpiecharttype(piechartlayer.chart_type_full); piechartlayer.setstartangle(90); //set size piechartlayer.setmaxsize(30); ChartColumn[] cols=new ChartColumn[3]; cols[0]= new ChartColumn( Pop_0_14, SolidYellow ); cols[1]= new ChartColumn( Pop_15_64, SolidRed ); cols[2]= new ChartColumn( Pop_65Plus, SolidGreen ); piechartlayer.setcolumns(cols); maprequest.addpiechartlayer(piechartlayer);.net Code Sample Pie Chart The following code sample shows how to create a pie chart making the size of the individual charts vary depending on the data. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //Add the NamedLayer to the PortrayMapRequest maprequest.namedlayer = new NamedLayer[]{namedLayer}; Presentation Service Reference 101

102 Defining Analysis Layers (Charts) //Create a pie chart layer PieChartLayer piechartlayer=new PieChartLayer( piechartlayer, WorldCountries,RefLayer.NAMEDLAYER); piechartlayer.type = PieChartType.HALF; piechartlayer.compositerendering = true; ChartColumn[] cols=new ChartColumn[3]; cols[0]= new ChartColumn( Pop_0_14, new Style( SolidBlue )); cols[1]= new ChartColumn( Pop_15_64,new Style( SolidGreen )); cols[2]= new ChartColumn( Pop_65Plus,new Style( SolidYellow )); piechartlayer.columns = cols; maprequest.piechartlayer = new PieChartLayer[]{pieChartLayer}; Equal Pie Chart The following code sample shows how to create a pie chart making the size of the individual charts equal. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //set it invisiable namedlayer.enabled = false; //Add the NamedLayer to the PortrayMapRequest maprequest.namedlayer = new NamedLayer[]{namedLayer}; //Create a FullPie chart layer PieChartLayer piechartlayer=new PieChartLayer( piechartlayer, WorldCountries,RefLayer.NAMEDLAYER); piechartlayer.type = PieChartType.FULL; piechartlayer.startangle = new Angle(90); piechartlayer.compositerendering = true; //set size GraduationProperties gp = new GraduationProperties(); gp.size = 30; ChartSize cs = new ChartSize(); cs.graduationproperties = gp; piechartlayer.chartsize = cs; ChartColumn[] cols=new ChartColumn[3]; cols[0]= new ChartColumn( Pop_0_14, new Style( SolidYellow )); cols[1]= new ChartColumn( Pop_15_64,new Style( SolidRed )); cols[2]= new ChartColumn( Pop_65Plus,new Style( SolidGreen )); 102 Envinsa 4.1

103 Chapter 5: Layer and Label Control Capabilities piechartlayer.columns = cols; maprequest.piechartlayer = new PieChartLayer[]{pieChartLayer}; XML Sample Pie Chart The following code sample shows how to create a pie chart making the size of the individual charts vary depending on the data. <ns3:namedlayer name= WorldCountries /> <ns3:piechartlayer name= piechartlayer referencelayer= WorldCountries referencetype= NamedLayer type= Half > <ns3:columns> <ns3:columnname>pop_0_14</ns3:columnname> <ns3:fillstyle> <Name>SolidBlue</Name> </ns3:fillstyle> </ns3:columns> <ns3:columns> <ns3:columnname>pop_15_64</ns3:columnname> <ns3:fillstyle> <Name>SolidGreen</Name> </ns3:fillstyle> </ns3:columns> <ns3:columns> <ns3:columnname>pop_65plus</ns3:columnname> <ns3:fillstyle> <Name>SolidYellow</Name> </ns3:fillstyle> </ns3:columns> </ns3:piechartlayer> Equal Size Pie Chart The following code sample shows how to create a pie chart making the size of the individual charts equal. <ns3:namedlayer enabled= false name= WorldCountries /> <ns3:piechartlayer name= piechartlayer referencelayer= WorldCountries referencetype= NamedLayer type= Full > <ns3:columns> <ns3:columnname>pop_0_14</ns3:columnname> <ns3:fillstyle> <Name>SolidYellow</Name> </ns3:fillstyle> </ns3:columns> <ns3:columns> <ns3:columnname>pop_15_64</ns3:columnname> <ns3:fillstyle> Presentation Service Reference 103

104 Defining Raster Layers (WMS Layer) <Name>SolidRed</Name> </ns3:fillstyle> </ns3:columns> <ns3:columns> <ns3:columnname>pop_65plus</ns3:columnname> <ns3:fillstyle> <Name>SolidGreen</Name> </ns3:fillstyle> </ns3:columns> <ns3:chartsize> <ns3:maxsize>30</ns3:maxsize> </ns3:chartsize> <ns3:startangle uom= DecimalDegrees >90.0</ns3:startAngle> </ns3:piechartlayer> Defining Raster Layers (WMS Layer) Raster images make excellent backgrounds for maps. For example, aerial photographs that show real-world detail such as buildings, refineries, and vegetation are well-suited as base layers for a map. Scanned paper maps are another example of a raster image. Use a raster image as a base layer and overlay vector data such as street networks, point locations representing customers, and postal boundaries, to create useful and visually appealing maps. You can include raster layers by overlaying the raster as a map, or define a raster layer. By using the raster layer, it allows you to insert the raster at any position in the map layers. This way, it is more flexible to utilize a WMS image from a GetMap response as an overlay, middle, or a backdrop layer. Raster images used with vector data must be registered so that known geographic points on the image coincide with the same features on the vector data. Additionally, company logos and other art you wish to display must be registered to some location on earth, even though they are not true georeferenced data. Many raster images available today come with a registration file (GeoTIFF). To register a raster image, you can import it into MapInfo Professional and register it there. The registration information is stored in a.tab file. Inputs and Behaviors To render raster images you can specify the following inputs: Input Required Description Name Yes Specifies a name for your layer. Order No Defines the rendering order for the layer. If you do not specify the order for the layer, the layer will be rendered in the order specified. See Setting the Layer Order on page 107 for more information. 104 Envinsa 4.1

105 Chapter 5: Layer and Label Control Capabilities Input Required Description Composite Rendering No Allows the layer to overlap the lower layers regardless of the order set for the layers. By default this is false (no overlap). Layer Content Yes Specifies the content of your raster layer by providing a URL to your layer (for example a GetMap response URL) or include the base64 encoded data for your layer. In addition to the content you must specify the format (mime type) of the layer image (for example, image/png), the width of the layer output image in pixels, and the height of the output image in pixels. Keep in mind what order your raster layer is going to be rendered. If you are not using the raster layer as a backdrop, its important to use a transparent background for your raster layer. This allows features to display from the layers rendered behind your raster layer. Display Range No Sets the display range for your layer. This will determine at what level of display the layer will be visible. See Setting the Display Range of Your Layers on page 117 for more information. Bounding Box No Defines the new map bounds based on the existing map. The bounding box for the coordinates is defined from the lower left corner to the upper right corner. Java Code Sample The following code sample shows how to render a raster layer from a WMS GetMap response. //Create a Map Overlay //specify the bounds, width, height and mime image format in the map output Envelope box = GeometryUtils.newEnvelope(-187,18,-66,71, EPSG:4326 ); String url= miwms?request=getmap&srs=epsg:4326&bbox=-187,18,- 66,71&WIDTH=400&HEIGHT=300&LAYERS=Demographic_Data/USA/Ranged_Themes/ race/demofin_st&styles=&format=image/png&transparent=true ; com.mapinfo.miaware.clientsdk.services.presentation.rasterlayer rasterlayer =new com.mapinfo.miaware.clientsdk.services.presentation.rasterlayer(box,400,3 00, image/png,url, RasterLayer ); //Add the Overlay to the PortrayMapRequestEx maprequest.addrasterlayer(rasterlayer); Presentation Service Reference 105

106 Defining Raster Layers (WMS Layer).NET Code Sample The following code sample shows how to render a raster layer from a WMS GetMap response. //Create a Map Overlay //specify the bounds, width, height and mime image format in the map output Point[]vertex = new Point[2]; vertex[0] = GeometryUtils.newPoint(-187,18); vertex[1] = GeometryUtils.newPoint(-66,71); Envelope box = GeometryUtils.newEnvelope(vertex, EPSG:4326 ); String url= miwms?request=getmap&srs=epsg:4326&bbox=-187,18,- 66,71&WIDTH=400&HEIGHT=300&LAYERS=Demographic_Data/USA/Ranged_Themes/ race/demofin_st&styles=&format=image/png&transparent=true ; RasterLayer[] rasterlayer = new RasterLayer[1]; rasterlayer[0] = new RasterLayer(); rasterlayer[0].bboxcontext = box; rasterlayer[0].width = 400; rasterlayer[0].height = 300; rasterlayer[0].format = image/png ; rasterlayer[0].url = url; rasterlayer[0].name = RasterLayer ; //Add the Overlay to the PortrayMapRequest maprequest.rasterlayer = rasterlayer; XML Sample The following code sample shows how to render a raster layer from a WMS GetMap response. <ns3:rasterlayer name= RasterLayer > <Content format= image/png height= 300 width= 400 > <URL> miwms?request=getmap&srs=epsg:4326&bbox=-187,18,- 66,71&WIDTH=400&HEIGHT=300&LAYERS=Demographic_Data/USA/ Ranged_Themes/race/DemoFin_ST&STYLES=&FORMAT=image/ png&transparent=true</url> </Content> <BBoxContext srsname= EPSG:4326 > <ns5:pos dimension= 2 xsi:type= ns5:directpositiontype xmlns:ns5= > </ns5:pos> <ns6:pos dimension= 2 xsi:type= ns6:directpositiontype xmlns:ns6= > </ns6:pos> </BBoxContext> </ns3:rasterlayer> 106 Envinsa 4.1

107 Chapter 5: Layer and Label Control Capabilities Setting the Layer Order Map layers in a Layer collection display in increasing index order (specifically, Layers(1) is the top layer, Layers(2) is the layer underneath Layer(1), and so on), with the bottom layer drawn first and the top layer drawn last. It is important to order your layers correctly. For example, suppose that you have a layer of customer points and a layer of census tracts. If the layers are incorrectly ordered in the Layer collection, the Presentation Service will draw the customer points first and then display the census tract layer second. Your customer points would be obscured by the census tract layer. You can reorder how layers are displayed in a map at design time. The Presentation Service renders a map in the following layer order (1 being the top layer and 5 being the bottom layer): 1. Static Overlay Layer (defined in the configuration). 2. Composite Rendering Overlay and layers (when set to true for each layer). 3. Overlay. 4. Basemap, Named Layer, Dynamic Layer, Pie Chart Layer, Bar Chart Layer, and Raster Layer. 5. Static Backdrop Layer (defined in the configuration). You can reorder how layers are displayed in three ways: 1. Manage the Layers Using the Map Manager Map layers display in the order that they defined using the Map Manager utility. These layers are ordered in the Layer Control dialog box, with the bottom layer drawn first and the top layer (which is always the Cosmetic Layer) drawn last. It is important to order your layers correctly. The basemap layer order is defined in the NamedMap file. You can change it with the Map Manager utility. For more information see the Map Management Guide. 2. Set the Static Layers in the Configuration The static layers rendering order (Overlay or Backdrop) are specified in the services configuration. See Static Layer Preferences in Chapter 7 on page 137 for instructions on setting the static layers. 3. Control the Layers in a Request To control the layer order of the basemap, named layers, and dynamic layers in the Presentation Service, specify the order, where order=0 is the top layer, followed by order=1, order=2, and so on. To control the overlay rendering, you can specify the zorder attribute, where zorder=0 is the top overlay. If no order is specified for the basemap, named layer, dynamic layer, chart layer, or raster layer the following default order will be applied: 1. The named layer or dynamic layer will be the top layer, and the basemap will be used as the backdrop. 2. If no order is specified, the named layer, dynamic layer, chart layer, and raster layer will be sorted in the reverse order presented in the request. For example, a request order specified similar to the following: <NamedLayer name="b"/> <NamedLayer name="c"/> Presentation Service Reference 107

108 Setting the Layer Order <DynamicLayer name="d".../> <NamedLayer name="e"/> <Basemap name="a".../> will result in the following rendering order (from top to bottom): <NamedLayer name="e"/> <DynamicLayer name="d".../> <NamedLayer name="c"/> <NamedLayer name="b"/> <Basemap name="a".../> Java Code Sample The following example, sets the order of two named layers, SFElevation being the top layer (setorder(1)) and SFGeoTif being the bottom layer (setorder(2)). //Create an array of NamedLayer NamedLayer[] namedlayer = new NamedLayer[2]; namedlayer[0] = new NamedLayer("SFGeoTif"); namedlayer[0].setorder(2); namedlayer[1] = new NamedLayer("SFElevation"); namedlayer[1].setorder(1);.net Code Sample The following example, sets the order of two named layers, SFElevation being the top layer (NamedLayer("SFElevation");namedLayer2.Order=1) and SFGeoTif being the bottom layer (NamedLayer("SFGeoTif");namedLayer1.Order=2). //create an array of NamedLayer NamedLayer namedlayer1 = new NamedLayer("SFGeoTif");namedLayer1.Order=2; NamedLayer namedlayer2 = new NamedLayer("SFElevation");namedLayer2.Order=1; NamedLayer[] namedlayer = {namedlayer1, namedlayer2}; XML Sample The following example, sets the order of two named layers, SFElevation being the top layer (name="sfelevation" order="1") and SFGeoTif being the bottom layer (name="sfgeotif" order="2"). <NamedLayer compositerendering="false" name="sfgeotif" order="2"/> <NamedLayer compositerendering="false" name="sfelevation" order="1"/ 108 Envinsa 4.1

109 Chapter 5: Layer and Label Control Capabilities Defining Content Layers and Filters in the Request A specific type of Dynamic layer is a Content layer (CMLayer). This kind of layer allows the Presentation Service to access and render Content Manager spatial data. Content can be displayed if full, in part, or as a theme. The layer content can be rendered with or without filters. You can specify filters as a template or define the filter within the request. Content layers provide Content Manager content accessibility and visualization of the data. Since the Presentation Service implements the Content Manager interfaces, all of the Content Manager filter abilities are inherited. You have the ability to define both template filters and inline filters using the Presentation Service. There are two basic types of filters: static and dynamic. Dynamic filters, in turn, have three subtypes: spatial, logical, and comparison. All three types of filters can be defined or used in a Presentation Service request. In a presentation request, you can use filters in the following ways: 1. You can define a new filter (inline) in the request. This allows you to define a new filter that is not based on an existing filter defined in the Content Manager. Such a filter is specific to the request in which it is defined, and has no existence beyond the scope of that request. You can define any type of filter in a request that you could otherwise define in the Content Manager. 2. You can use an existing filter (template) that is defined in the Content Manager. To use a template filter in a request, you may need to pass parameters to it. To find out what filters have been defined and the runtime parameters required for each filter, you can use a Presentation Service resource information request. For a description of the resource information request, see Describing the Available Resources in Chapter 2 on page You can define a more complex filter by combining filters defined in the request and filters defined in the Content Manager. For a complete list of filter concepts, types of filters, and filter operations, see the Content Manager Guide. Inputs and Behaviors When defining a Content Layer in the request, you can include the following information: Input Required Description Layer Type Yes Specifies the layer type as CMLayer. Layer Name Content Path Yes No Specifies a unique name for the Content Layer. Specifies the name of the Content used for the CMLayer. The Content path is specified using the Content Manager directory structure. For more information on specifying Content and the directory structure, see the Content Manager Guide. Presentation Service Reference 109

110 Defining Content Layers and Filters in the Request Input Required Description Filter No There are two types of filters that you can define for a CMLayer: template filter or inline filter. Template Filters The simplest form of filter is the template filter. You can use attribute or spatial filters previously defined in the Content Manager in your request. Some filters only require a referenced by name, while other require you to pass parameters or values in the request. To find out what filters have been defined, and the runtime parameters required by each filter, you can use a Presentation Service resource information request on your CMLayers. For examples on how to create template filters in a request, see the following examples: CMLayer Defined with a Template Filter in Java on page 111 CMLayer Defined with a Template Filter in XML on page 114 Inline Filters The more complicated form of filter is the inline filter. You can create a new filter by defining all aspects, including type, values, operators, and content. This type of filter requires you to have a good working knowledge of your content. For a complete list of supported filter types and operators see the Content Manager Guide. For examples on how to create inline filters in a request, see the following examples: CMLayer Defined with an Inline Filter in Java on page 113 CMLayer Defined with an Inline Filter in XML on page 115 Layer Style No Sets a style for the layer when rendered. See Adding Custom Styles to Your Layers on page 116. Auto Label No Determines if the layer is going to be labeled in the map. Set auto label to on for the layer to be labeled. Composite Rendering No Allows the layer to overlap the lower layers regardless of the order set for the layers. By default this is false (no overlap). Enabled No Determines if the layer will be rendered in the map. By default the layer will be rendered (true). This is a useful tool when displaying analysis layers. You can display the chart and not display the layer used to create the chart. 110 Envinsa 4.1

111 Chapter 5: Layer and Label Control Capabilities Input Required Description Layer Order Layer Label Display Range Feature or Label Theme No No No No Determines the layer order for your Content Layer. By default the Dynamic layer will be ordered based on the Presentation Service defaults. For more information on determining the order for the layer, see Setting the Layer Order on page 107. To make the Content Layer the top layer, specify the order=0. Specifies the qualities of the labels on a layer with full labeling capabilities. These qualities include the style in which they display, what priority they have, and in what position. For more information on Labeling, see Labeling Your Map Layers on page 118. Defines the zoom settings at which the layer is displayed. You can set the minimum, maximum, and unit for the display range. See Setting the Display Range of Your Layers on page 117 for more information. You can use the dynamic layer as the source of your thematic map. For more information on thematic mapping in the Presentation Service, see Chapter 4: Thematic Mapping Capabilities. Java Code Sample CMLayer Defined with a Template Filter in Java The following sample shows how to define a CMLayer with an attribute template filter. The first part of the sample shows how the layer preferences define the content used (Canadian POIs) and the filter. The filter is defined using the filter name (attributefilter), as it is specified in the resource information response from the Presentation Service. This template filter requires the code parameter be defined in the request (defined as code=24). The second part of the sample shows the label options on the A2_Code column. The third part of the sample uses the World CMLayer, and creates a ranged gradation theme (with legend) on the population values. //Create the PresentationRequest PortrayMapRequestEx presentationrequest = new PortrayMapRequestEx( perform, 1.5, ID ); //Create the Output //Create a CenterContext CenterContext centercontext = new CenterContext( , , EPSG:4326, new Distance(2000, DistanceUnit.KM)); OutputEx output = new OutputEx(centerContext, 600, 400, image/gif ); //Set the return zoomlevel to on output.enablereturnzoomlevel(true); output.setpresentationcontent(output.content_base64);// data Presentation Service Reference 111

112 Defining Content Layers and Filters in the Request //Add the Ouput to the PresentationRequest presentationrequest.addoutput(output); //Create a Polygon that will be used for spatial search //Create the first CMLayer //Create a Properties object that contains info about the attribute filter Properties attributefilter = new Properties(); attributefilter.setproperty( code, 24 ); //Create a CMCLayer which is a our implementation of the DynamicLayer and add it to the PresentationRequest //Specify the content path ( defined in content manager ) CMLayer cmclayer = new CMLayer( Canadian POIs ); //Specify the name of the attribute filter to be used. This attribute filter must be defined using content //manager, under the above specified content cmclayer.setattributefiltername( attributefilter ); //Specify the properties for this attribute filter cmclayer.setattributeproperties(attributefilter); //Specify the order of this CMLayer cmclayer.setorder(0); //Specify a Label for this CMLayer LabelProperties cmlabel = new LabelProperties(); cmlabel.setduplicate(true); cmlabel.setoverlap(true); cmlabel.setlabeltextexpression( A2_Code ); cmclayer.setlabelproperties(cmlabel); //Adds the CMLayer to the presentation request presentationrequest.adddynamiclayer(cmclayer); //Create the second CMLayer. Can be any name CMLayer cmdynamiclayer = new CMLayer( World ); //Set the order for the this CMLayer cmdynamiclayer.setorder(1); //Set the LabelProperties for this DynamicLayer //Create a LabelProperties for this DynamicLayer LabelProperties label = new LabelProperties(); label.setlabeltextexpression( Country ); cmdynamiclayer.setlabelproperties(label); //Create a FeatureTheme for this DynamicLayer. The FeatureTheme is in a form of RangedTheme //Create the Gradation for the RangedTheme Gradation gradation = new Gradation(10); 112 Envinsa 4.1

113 Chapter 5: Layer and Label Control Capabilities //Set the Gradation BeginStyle, EndStyle and Type gradation.settype(gradation.type_equal_count); gradation.setbeginstyle(new ThemeStyle(new Style( SolidYellow ))); gradation.setendstyle(new ThemeStyle(new Style( SolidRed ))); RangedTheme rangedtheme = new RangedTheme( Pop_1994, gradation); //Set the Legend for the RangedTheme Legend legend = new Legend( image/png, Pop_1994, Legend.CONTENT_BASE64); // Data rangedtheme.setlegend(legend); //Add the RangedTheme to this DynamicLayer cmdynamiclayer.setfeaturetheme(rangedtheme); //Add the DynamicLayer to the PresentationRequest presentationrequest.adddynamiclayer(cmdynamiclayer); CMLayer Defined with an Inline Filter in Java The following sample shows how to define an attribute and nearest inline filter for a CMLayer. The code will filter all of the Canadian POIs that are within Quebec (attributefilter) and then do a nearest search on those POIs within a one thousand kilometer radius of the given point. The first part of the sample shows how the attribute filter is defined, using the A1_Code column and filter for all values equal to 24 (the LIKE operator). The second part of the sample shows how the attribute filter (attributefilter) is created. The third part of the sample shows how the point is created to be used in the nearest filter. The last part of the sample shows how the nearest filter is defined, using the NearestFilterImp and specifying a distance of 1000 kilometers from the Point geometry. //Create a Filter object that contains info about the attribute filter SimpleAttributeFilter filter = null; ScalarAttributeDefinition col = new ScalarAttributeDefinitionImpl( A1_ Code, ScalarAttributeType.STRING); try{ filter = FilterFactory.newSimpleAttributeFilter(col, new ScalarAttributeValueImpl( 24 ), SimpleAttributeFilter.LIKE); }catch(exception e){ e.printstacktrace(); } //Second PropertySet contains a Properties object that contains info about the attribute filter layerpref[1] = new PropertySet( attributefilter, filter); Point pol = null; try { xlsgmlfactory gmlf = (xlsgmlfactory)gmlfactory.newinstance(gmlfactory.xls); Presentation Service Reference 113

114 Defining Content Layers and Filters in the Request //a new center point pol = gmlf.newpoint(gmlf.newdirectposition( )); pol.setsrs( EPSG:4326 ); //Create a Filter object that contains the geometry used in spatial searching SpatialFilter spf = new NearestFilterImpl( MI_GEOMETRY, pol,new com.mapinfo.unit.distance(1000,linearunit.kilometer),50); //Third PropertySet contains a Properties object that contains info about the spatial filter layerpref[2] = new PropertySet( containsfilter, spf); } catch(exception e) { e.printstacktrace(); } XML Sample CMLayer Defined with a Template Filter in XML The following sample shows how to define a CMLayer with an attribute template filter. The first part of the sample shows the label options on the A2_Code column. The second part of the sample shows how the layer preferences define the content used (Canadian POIs) and the filter. The filter is defined using the filter name (attributefilter), as it is specified in the resource information response from the Presentation Service. This template filter requires the code parameter be defined in the request (defined as code=24). The third part of the sample uses the World CMLayer, and creates a ranged gradation theme (with legend) on the population values. <ns3:dynamiclayer compositerendering= false name= ContentManager order= 0 type= CMLayer > <ns3:label duplicate= true overlap= true > <ns3:text> <ns3:expression>a2_code</ns3:expression> </ns3:text> </ns3:label> <ns3:layerpreferences> <ns3:propertyset name= Content > <ns3:property name= ContentPath >Canadian POIs</ns3:Property> <ns3:property name= AttributeFilterName >attributefilter</ ns3:property> </ns3:propertyset> <ns3:propertyset name= attributefilter > <ns3:property name= code >24</ns3:Property> </ns3:propertyset> <ns3:propertyset xsi:nil= true /> </ns3:layerpreferences> </ns3:dynamiclayer> <ns3:dynamiclayer compositerendering= false name= ContentManager order= 1 type= CMLayer > 114 Envinsa 4.1

115 Chapter 5: Layer and Label Control Capabilities <ns3:label duplicate= false overlap= false > <ns3:text> <ns3:expression>country</ns3:expression> </ns3:text> </ns3:label> <ns3:featuretheme> <ns3:overridetheme xsi:nil= true /> <ns3:rangedtheme column= Pop_1994 > <ns3:gradation number= 10 > <ns3:beginstyle> <ns3:font xsi:nil= true /> <ns3:style> <Name>SolidYellow</Name> <StyleContent xsi:nil= true /> </ns3:style> </ns3:beginstyle> <ns3:endstyle> <ns3:font xsi:nil= true /> <ns3:style> <Name>SolidRed</Name> <StyleContent xsi:nil= true /> </ns3:style> </ns3:endstyle> <ns3:type>equalcount</ns3:type> </ns3:gradation> <ns3:legend content= URL format= image/png height= 300 transparent= false width= 200 > <ns3:title>pop_1994</ns3:title> </ns3:legend> </ns3:rangedtheme> <ns3:individualvaluetheme xsi:nil= true /> </ns3:featuretheme> <ns3:layerpreferences> <ns3:propertyset name= Content > <ns3:property name= ContentPath >World</ns3:Property> </ns3:propertyset> <ns3:propertyset xsi:nil= true /> <ns3:propertyset xsi:nil= true /> </ns3:layerpreferences> </ns3:dynamiclayer> CMLayer Defined with an Inline Filter in XML The following sample shows how to define an attribute and nearest inline filter for a CMLayer. The following sample will filter all of the Canadian POIs that are within Quebec (attributefilter) and then do a nearest search on those POIs within a one thousand kilometer radius of the given point. The first part of the sample shows how the two filters (attribute and spatial) are named (attributefilter and filter) and how the content is defined (Canadian POIs). The second part of the sample shows how the attribute filter is defined, using the A1_Code column and filter for all values equal to 24 (the like operator). The third part of the sample shows how the nearest filter is defined, using the FindNearestFilterType and specifying a distance of kilometers from the Point geometry. Presentation Service Reference 115

116 Adding Custom Styles to Your Layers <ns3:propertyset name= Content > <ns3:property name= SpatialFilterName >filter</ns3:property> <ns3:property name= ContentPath >Canadian POIs</ns3:Property> <ns3:property name= AttributeFilterName >attributefilter</ ns3:property> </ns3:propertyset> <ns3:propertyset name= attributefilter > <ns5:_filter xsi:type= ns5:stringfiltertype xmlns:ns5= > <ns5:stringvalueexpression xsi:type= ns5:stringvalueexpressiontype > <ns5:attributename xsi:type= xsd:string >A1_Code</ ns5:attributename> </ns5:stringvalueexpression> <ns5:operator xsi:type= xsd:string >mapinfo:op like</ns5:operator> <ns5:stringvalue xsi:type= xsd:string >24</ns5:StringValue> </ns5:_filter> </ns3:propertyset> <ns3:propertyset name= filter > <ns6:_filter xsi:type= ns6:findnearestfiltertype xmlns:ns6= > <ns6:spatialvalueexpression xsi:type= ns6:spatialvalueexpressiontype > <ns6:attributename xsi:type= xsd:string >MI_GEOMETRY</ ns6:attributename> </ns6:spatialvalueexpression> <ns6:maxresults>50</ns6:maxresults> <ns6:maxdistance uom= epsg:9036 >1000.0</ns6:MaxDistance> <ns7:_geometry srsname= EPSG:4326 xsi:type= ns7:pointtype xmlns:ns7= > <ns7:pos dimension= 2 xsi:type= ns7:directpositiontype > </ns7:pos> </ns7:_geometry> </ns6:_filter> </ns3:propertyset> Adding Custom Styles to Your Layers Styles are usually predefined for your named layers. You can override these existing styles or assign a style that will determine how the layer will be rendered. All styles are defined using named styles. For more information on creating named styles, see the Map Management Guide. Inputs and Behaviors When defining a custom style for a layer, you should define the following input: Input Required Description Named Style Yes Defines the named style used to render the layer. 116 Envinsa 4.1

117 Chapter 5: Layer and Label Control Capabilities Java Code Sample The following code sample sets the PositionSyle named style to be used to render the WorldCountries named layer. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); namedlayer.setstyle(new Style( PositionStyle )); namedlayer.setorder(0);.net Code Sample The following code sample sets the PositionStyle named style to be used to render the WorldCountries named layer. //Create a NamedLayer NamedLayer[] namedlayer = new NamedLayer[1]; namedlayer[0] = new NamedLayer( WorldCountries ); namedlayer[0].style = new Style( PositionStyle ); namedlayer[0].order = 0; XML Sample The following code sample sets the PositionSyle named style to be used to render the WorldCountries named layer. <ns3:namedlayer name= WorldCountries order= 0 > <ns3:style> <Name>PositionStyle</Name> </ns3:style> </ns3:namedlayer> Setting the Display Range of Your Layers Sometimes you want a map layer to display only at certain zoom levels. Zoom layering (or display range) allows you to view a map layer when the map's zoom level falls within a preset distance. You can set a different zoom layering level for each layer. For example, if your map includes a street map layer, you may find that the streets become illegible when the user zooms out too far. Using zoom layering, you might set up your map so that the Presentation Service automatically hides the streets whenever the user zooms out to show an area larger than five miles. Different layers in the same map can be displayed at different zoom levels. For example, you have a layer of streets, a layer of county boundaries, and a layer of state boundaries. You want the streets layer to be visible only when the zoom level is less than eight miles. You want the county boundary layer to display when the zoom level falls between 20 miles and 200 miles. You want the states boundary layer to be visible only when the zoom level is greater than 100 miles. You can set a different zoom level for every layer in your map. Note: The display range of a layer will affect the display of an associated legend. If the layer is not visible due to display range values, the legend will not be visible. Presentation Service Reference 117

118 Labeling Your Map Layers Inputs and Behaviors You can overwrite the visibility setting of the layer (include/exclude) by setting the minimum and maximum zoom level for the layer by defining the following inputs: Input Required Description Minimum Zoom Yes Defines the minimum zoom level where the layer will display Maximum Zoom Yes Defines the maximum zoom level where the layer will display Unit Yes Defines the unit for the zoom level. Java Code Sample The following sample sets the display range for the layer to display between zero and fifty thousand kilometers. DisplayRange range = new DisplayRange(0,50000,DistanceUnit.KM); namedlayer.setdisplayrange(range); XML Sample The following sample sets the display range for the layer to display between zero and fifty thousand kilometers. <ns3:displayrange maxzoom= minzoom= 0.0 unit= KM /> Labeling Your Map Layers Labels are dynamically connected to their map features. If the layer is closed or is made invisible, the labels no longer display. If the data or geographic information changes, the labels change. Labels can be rendered for any type of layer and can be set to be automatically labeled using the Auto Label option when defining the layer. The position, display, and look of labels can be controlled. You can set conditions for displaying labels, in the style in which they will display, what priority they have, and in what position for all the objects in the layer. Inputs and Behaviors The Presentation Service allows you to define the following label controls: 118 Envinsa 4.1

119 Chapter 5: Layer and Label Control Capabilities Input Required Description Text No Specifies the label content and font definition for text, symbols, or an expression. For a description of font controls, refer to Font Options on page 120. For a description of how to label an expression, refer to Text Expressions on page 120. Position No Specifies the positioning of the label. For a description on how to control the position of a label, refer to Position Options on page 121. Display Range No Specifies the visibility of a label based on zoom range. For a description on how to control the visibility of a label, refer to Managing Label Visibility (Display Range) on page 122. Intragroup Priority No Sets the intragroup priority for this group's labels. The intragroup priority can be used to more precisely specify the relative importance of labels within a common group or layer. This value is used to differentiate between two labels only when they have equal (main) priorities. The default value is 0. Multiline Mode No Specifies the mode for using multiline text with labels. For long text strings, the way the string is displayed is significant to the readability of your map. The following multiline modes are available: Off Labels are formatted as a single line of text. Existing line breaks within text do not result in multi-line text. This is the default mode, and is the most preferred. On Existing line breaks within label text is respected, resulting in multi-line labels. Compute Label text is dynamically evaluated by the labeling engine. The labeling engine may determine to format label text on multiple lines. This mode has the largest run-time overhead. Duplicate No Specifies whether duplicate labels are allowed (default is false). You would allow duplicate labels if you need to label a map feature in more than one location with the same label (for example, a very long street or a large body of water). Keep in mind that a map with a lot of overlapping or duplicate labels will be hard to read. Overlap No Specifies whether labels will be allowed to overlap (default is false). If overlapping is allowed, labels that overlap may appear on the map. If overlapping is not allowed, only one label may appear in any one spot on the map. The label with highest priority will be favored for labeling. Presentation Service Reference 119

120 Labeling Your Map Layers Input Required Description Priority No Specifies the override priority for a layer. Labeling for multiple layers is carried out according to a priority. Use this to change the priority of labeling for the layer. Those layers drawn last will take precedence over lower layers drawn first. The higher the number, the higher the priority. A label s default priority is calculated by (number of layers - layer position) * 10. So, if there are 20 layers, the default label priority for the layer at position 5 is 150 (layer 0 being the highest). A layer's default label priority may change when other layers are added or removed. Labels with greater priority will be rendered in the case of overlaps or duplicates. Intragroup priority is used if the priority between labels is tied. Text Expressions The content for label text can be a result of an expression, containing column names for the layer and/or static text. The character + is the delimiter between column names and static text. Static text strings are enclosed in escaped double quote characters. The following expression creates a label that prepends the static text "Pop:" to actual population values using the POPULATION column for a particular layer: "\"Pop: \" + POPULATION" Multiple column names and static text tokens are also permitted: "\"The population of \" + STATE_NAME + \" is: \" + POPULATION" If only the population values are to be returned (no static text), just the column name would be used: "POPULATION" Font Options When specifying the text for the label, you can also specify the font and text options. The following is a list of font controls that can be applied to your label text: Input Required Description Family Yes Specifies the font family name (for example, Arial). The Presentation Service GetCapbilities request can return a list of available font families. Size Yes Specifies the font height in pixel. Foreground Color Background Color No No Specifies the foreground color of the text in Hex number format (for example, #00ff00). Specifies the background color of the text in Hex number format (for example, #00ff00). 120 Envinsa 4.1

121 Chapter 5: Layer and Label Control Capabilities Input Required Description Background Mode No Specifies the background style of the text. There are three available formats for the background style: Box draws the bounding box of the symbol or text filled with the current BGcolor before the symbol or text is drawn. Halo draws the text string halo-ed by drawing an expanded outline of the text string using the current BGcolor. Outline draws the outline of the text string using the current BGcolor. Italic No Draws the text in italics. The default is false. Bold No Draws the text in bold. The default is false. Underline No Underlines the text. The default is false. Position Options When specifying the label, you can also specify the position of the label. The following is a list of position controls that can be applied to your label: Input Required Description Offset No Sets the offset for the label point. The offset is the incremental change, measured in device units (x,y), to be applied to the existing label point coordinates in order to fine tune the label position. For example, if the current label point is (30,40) and the offset is (3,-4), the final label position will be (33,36). Mode No Specifies the procedure used for assigning a labels initial point. There are two available modes: Compute Calculates the label anchor point using both the feature's geometry and the view rectangle in which rendering occurs. Any value returned by the feature's getlabelpoint method is ignored. This mode increases the likelihood that a feature s label will be within the view rectangle. Static Returns the value of the feature's getlabelpoint method and uses that as the label anchor point. The view rectangle used for a particular rendering request may not contain the label point, in which case the feature may not be labeled. Presentation Service Reference 121

122 Labeling Your Map Layers Input Required Description Vertical No Specifies the vertical alignment used for labels. There are four positions for vertical alignment: Center labels Centered on the reference point. Baseline labels Aligned so that the label's baseline is at the height of the reference point. Top labels Aligned so that the label bounding box top edge is at the height of the reference point. Bottom labels Aligned so that the label bounding box bottom edge is at the height of the reference point. Horizontal No Specifies the horizontal alignment used for labels. There are three positions for horizontal alignment: Left labels Aligned so that the label bounding box left edge is closest to the reference point. Center labels Centered on the reference point. Right labels Aligned so that the label bounding box right edge is closest to the reference point. Rotate No Specifies that a label for a line will be drawn parallel to the line (default labels for lines will be drawn parallel). If this value is set to true, the labels will be drawn perpendicular to the line. Along Path No In addition to straight line labels, you can set labels for polylines or polygons to follow the curved path of the feature (default labels are straight line and are located at the centroid of a geometry). If this value is set to true, the label will be drawn along the curved path of the line or along the polygon boundary. Managing Label Visibility (Display Range) You can specify the labels to display only within a specific zoom range, the same way that you display layers within a certain zoom range, by setting the minimum and maximum zoom at which the labels will display. To keep from creating a cluttered map when labeling all layers, specify the label zoom at different values so that as you zoom in or out, the appropriate labels display. For example, specify the zoom for the world layer at 0 kilometers minimum and 2000 maximum. Specify the capital city layer to display labels between 200 and 500 kilometers. Specify the city layer to display labels only when zoomed in below 50 kilometers. Input Required Description Minimum Zoom Yes Defines the minimum zoom level where the layer will display Maximum Zoom Yes Defines the maximum zoom level where the layer will display Unit Yes Defines the unit for the zoom level. 122 Envinsa 4.1

123 Chapter 5: Layer and Label Control Capabilities Java Code Sample The following example uses the WorldCountries named layer and sets the label properties. The labels for this named layer are an expression from the Pop_1994 column (labeling population figures). The style for the labels are specified as 10 point Arial and underlined. The labels are centered both vertically and horizontally on the counties geometry, with a slight offset of -5 pixels on the x-axis and 5 pixels on the y-axis. //Create a NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); //Set the autolabel for this Layer to on namedlayer.setautolabel( on ); //Create NamedLayer LabelProperties LabelProperties label = new LabelProperties(); //Create the LabelProperties Font Font labelfont = new Font( Arial, 10); labelfont.setfgcolor(color.decode( #ff0000 )); labelfont.setbgcolor(color.decode( #ff0000 )); labelfont.setunderline(true); //Add Font to the LabelProperties label.setlabeltextfont(labelfont); //Add Expression to the LabelProperties label.setlabeltextexpression( Pop_1994 ); //Add Position to the LabelProperties LabelPosition labelposition = new LabelPosition(); labelposition.setlabelmode(labelposition.label_mode_compute); labelposition.setverticalalignment(labelposition.vertical_alignment_ CENTER); labelposition.sethorizontalalignment(labelposition.horizontal_alignment_ CENTER); labelposition.setoffset(-5, 5); label.setlabelposition(labelposition); //Add the LabelProperties to the NamedLayer namedlayer.setlabelproperties(label);.net Code Sample The following example uses the WorldCountries named layer and sets the label properties. The labels for this named layer are an expression from the Pop_1994 column (labeling population figures). The style for the labels are specified as 10 point Arial. The labels are centered both vertically and horizontally on the counties geometry, with a slight offset of -5 pixels on the x-axis and 5 pixels on the y-axis. //Add the LabelProperties to the NamedLayer NamedLayer namedlayer = new NamedLayer( WorldCountries ); Presentation Service Reference 123

124 Labeling Your Map Layers namedlayer.autolabel = on ; //add a label to the name layer Label label = new Label(); Font lf = new Font();lF.Family= Arial ;lf.size=10;lf.fgcolor= #ff0000 ;lf.italic=false; lf.underline=false; label.labeltextfont = lf; label.labeltextexpression= Pop_1994 ; //Set Position to the LabelProperties LabelPosition labelposition = new LabelPosition(); double[] offset = {-5,5}; labelposition.offset = offset; labelposition.labelmode = LabelGeometryModeType.Compute; labelposition.verticalalignment = VerticalAlignmentType.Center; labelposition.horizontalalignment = HorizontalAlignmentType.Center; label.labelposition = labelposition; namedlayer.label =label; XML Sample The following example shows how to set the label properties for any layer. The labels for this layer are an expression from the Pop_1994 column (labeling population figures). The style for the labels are specified as 10 point Arial and underlined. The labels are centered both vertically and horizontally on the counties geometry, with a slight offset of -5 pixels on the x-axis and 5 pixels on the y-axis. <ns3:label duplicate= false overlap= false > <ns3:text> <ns3:expression>pop_1994</ns3:expression> <ns3:font BGcolor= #ff0000 FGcolor= #ff0000 bold= false family= Arial italic= false size= 10 underline= true /> </ns3:text> <ns3:position alongpath= false horizontal= Center mode= Compute rotate= false vertical= Center > <ns3:offset> </ns3:Offset> </ns3:position> </ns3:label> 124 Envinsa 4.1

125 Presentation Service Fundamentals 6 The Presentation Service renders geographic information for display on a mobile terminal or desktop station. This section describes fundamental concepts that are essential to understand to properly implement this service. In this section: Mapping Concepts Hints and Tips Service Standards Compliance Functionality Limitations

126 Mapping Concepts The central element to a mapping application is the map. This section presents a short overview of the most important mapping terms that you will likely encounter while building your application with the Presentation Service. These topics include: Maps Tables Layers Features Labels and Legends Themes Maps A map displays the spatial relationship among map features, such as town boundaries, customer locations, or power lines. The map visually orients you to where those features are and what they represent. In addition to features, elements on the map can include labels, titles, legends, and themes. Themes are created based on some action taken involving the features and information on the map. Tables Tables contain the data you wish to display on the map. Tables hold rows and columns of information that describe the features, including their geometry, style, and attributes. The Presentation Service supports tables from a wide variety of sources including, native tables (MapInfo.TAB), and relational database management systems (RDBMS). Layers Maps are made up of layers. Layers contain map features, such as postal code boundaries, schools, or streets networks. It is important to understand the order of the layers. The bottommost layer is drawn first and the topmost layer drawn last. Layers containing features that would obscure other features (such as boundaries over points), should be placed below other layers. Layers can represent more than features. Layers can be raster or grid images, seamless maps (joined maps), contain labels or user-drawn features, or contain an object theme. Layers can be grouped for easier positioning and to facilitate animation of their features. Features Features are described by their geometry, style, data source, key, and attributes. Typically a feature is a row in a table. Supported geometries include closed objects that cover a given area (for example, Polygons or Ellipses); point objects that represent single locations of data (for example, Points or MultiPoints); and line objects that cover a given distance (for example, LineStrings or Arcs). 126 Envinsa 4.1

127 Chapter 6: Presentation Service Fundamentals Labels and Legends Maps without elements to describe what is displayed are not very useful. Maps need text such as labels and legends. Labels allow you to control every aspect of a maps design (for example, visibility, position, style, and content). Other text elements can also be used in a map to help deliver its message properly. Legends are cartographic elements that describe the features in a coded manner. For example, the legend may describe the boundaries as school districts, the lines as a power line network, or points as corporate office locations. Legends also contain a title to describe collectively what the map represents. Themes Computer maps are not only useful for visibly showing spatial relationships among the map features, but you can analyze the underlying data that is associated with the features to learn more about what you see. A common analytical technique is to create a theme based on a feature layer in which the data is ranked in specific ways. For example, a ranged theme shows color blocks where each color represents features on the map that meet the same criteria. A graduated symbol theme is useful for showing distributions of populations for example, with the largest symbol representing the largest population. Themes can also be created for labels. For example, use a ranged label theme to show the relative population size among cities. The largest labels represent the cities with the largest populations. Hints and Tips The following hints and tips are important to keep in mind when creating applications using the Presentation Service. Presentation Service Reference 127