Use Cases > PTV xMap > How to Do Basic Mapping

How to Do Basic Mapping

For this example we assume that you have some basic knowledge on how to consume SOAP web services in your programming language. If you have not already, you might want to read the information on the usage of PTV xServer technology. Below, each step is accompanied with a source code snippet for C# and Java. Mapping is the process of creating a map with a certain visible area. This area can be specified using one of the two methods available from the PTV xMap client:

renderMap(): accepts a map section defined by the center of the map and the zoom/scale value which is described in the following example.
renderMapBoundingBox(): accepts a map section defined by the bounding rectangle represented by the two coordinates for left/upper and right/lower corner.

Instantiating an PTV xMap Client

Step 1: Create a PTV xMap client.

Java snippet

final String url = "http://localhost:50010/xmap/ws/XMap";
XMapRemoteInterface client = (XMapRemoteInterface) ClientFactory.
createClient(XMapRemoteInterface.class, RemoteType.DOCSTYLE_CXF, "", "", url);

Defining a MapSection

The MapSection is the location information of the visible section to display. It defines the center of the map and the scale, and that's almost it.

The scale is given in co-ordinate units per pixel. This is not - as one might expect - a measure such as 1:25000 in topographic maps. So you have to get used to this notation.
The zoom has no effect in the first step when creating a map. It becomes meaningful for follow-up maps to zoom in or out. It then defines the factor to zoom in (positive) or out (negative). Adding 1 shows half of the currently visible map, taking 1 shows twice as much.

When using the MapSection object it is important to make sure that all necessary properties are set properly. If a property is omitted, the default value of its data type will be used, such as MapSection.scale = 0 which does not make any sense.

The three properties scrollHorizontal, scrollVertical and zoom do not have to be set in this example, as their data type default value as an integer is 0 (zero) which is indeed meaningful in this case - so they do not need to be specified. Our MapSection is now specified for the call of the method renderMap().

Step 2: Create object MapSection.

Java snippet

MapSection mapSection = new MapSection();
Point point = new Point();
// Note: Third dimension added; necessary for java clients 1.17 and higher
point.setPoint(new PlainPoint(685407.751736, 6372537.965244, null))
mapSection.setCenter(point);
mapSection.setScale(1000);

Defining a CallerContext

Step 3: Create object CallerContext.

Java snippet

CallerContext cxt = new CallerContext();
cxt.setLog1("Basic Mapping");
// set CallerContext properties to define profile and CoordFormat
CallerContextProperty props1 = new CallerContextProperty();
props1.setKey("Profile");
props1.setValue("default");
CallerContextProperty props2 = new CallerContextProperty();
props2.setKey("CoordFormat");
props2.setValue("PTV_MERCATOR");
CallerContextProperty[] properties = new CallerContextProperty[]{props1, props2};
cxt.setProperties(properties);
client.setCallerContext(cxt);

Defining an ImageInfo

An ImageInfo object contains the necessary information about the properties of the generated image. These are format, width, height, etc.

Step 4: Create object ImageInfo.

Java snippet

ImageInfo imageInfo = new ImageInfo();imageInfo.setHeight(240);
imageInfo.setWidth(320);
imageInfo.setImageParameter("");

Defining MapParams

With the MapParams object you can set two properties:

showScale: this decides whether to show the scale in the right bottom corner or not.
useMiles: this decides whether to show the scale in anglo-saxon units or in metric units.

Step 5: Create object MapParams.

Java snippet

MapParams mapParams = new MapParams();
mapParams.setShowScale(true);
mapParams.setUseMiles(false);

Set attribute includeImageInResponse

Step 6: Set value for includeImageInResponse.

Java snippet

boolean includeImageInResponse = false;

Calling

In this example we call the method renderMap(). The first three arguments have been defined above. The fourth argument would be an array of layers, but we don't use them in this example. They are a bit more complex and therefore part of other PTV xMap Code Samples. The fifth argument of the method renderMap() is includeImageInResponse:

If true, the image is returned with the response and you have to handle the map data for displaying purposes yourself.
If false an URL is returned. In this case you have to make sure that the configuration of your PTV xMap Server provides the map in the right virtual directory. Important are the following entries within the file conf\xmap.properties:
- imageMapServer.remotePath and
- imageMapServer.remoteURL.

Step 7: Call renderMap method.

Java snippet

Map map = client.renderMap(mapSection, mapParams, imageInfo, null, includeImageInResponse);

Read the response

The return type of the method renderMap() is Map. With this object you can get (among other parameters) the URL of your generated image (in case you configured the config files correctly and you wanted the PTV xMap Server to return an URL and not the raw image in the response). Of course this is not the only information available within the object Map. You can also get the actually drawn BoundingBox and remember its coordinates for further use.

Step 8: Return bounding box.

Java snippet

BoundingBox bbox = map.getVisibleSection().getBoundingBox();

double leftTopX  = bbox.getLeftTop().getPoint().getX();
double leftTopY  = bbox.getLeftTop().getPoint().getY();
double rightBottomX = bbox.getLeftTop().getPoint().getX();
double rightBottomY = bbox.getLeftTop().getPoint().getY();
int scale = map.getVisibleSection().getScale();

Display the map

If you want to display the rendered map image in a window, you can use the code below:

Step 9: Get image.

Java snippet

String imageUrl = "http://"+map.getImage().getUrl();
ImageIcon icon = new ImageIcon(new URL(imageUrl));

Source Code

The example basic mapping is also executable as a stand-alone java program.