[[PageOutline]]

This page is part of the [wiki:Future MapGuide Future] section, where ideas are proposed and refined before being turned into RFCs (or discarded).  Visit the [wiki:Future] page to view more!

= Overview =

The `mg-desktop` sub-project of MapGuide has demonstrated the ability to take the functionality of MapGuide (data access, rendering, etc) and wrap it up in a portable, server-less library for use in desktop application or server-tier-less web applications.

For an application that wants lightweight map rendering capabilities for a given FDO-accessible data source, `mg-desktop` is still a bit too heavy-weight and (more importantly) windows-specific.

This page floats the idea of a portable, lower-level command-line tool that does only one thing: Render maps against FDO-accessible data sources.

= Map Render Tool =

If anyone remembers the ancient MapGuide 6.5 (and older) component called LiteView, the Map Render Tool is basically a command-line version of that concept. 

Or an alternative way of thinking about this tool is that it is a a command-line version of the stateless `GETMAPIMAGE` mapagent operation.

The tool itself does not utilize the MapGuide API services platform. Instead, in line with its lightweight goal, it will use only the MG rendering/stylization libraries directly with FDO for data access. The Foundation/Geometry parts we will most likely leverage for coordinate system and geometry operations functionality.

= Usage patterns =

The basic usage patterns of this tool is as follows:

1. Rendering map images

```
MgMapRender.exe render --map path/to/mapdef.xml --width image_width --height image_height --dpi dpi --format PNG 
[--extent minx,miny,maxx,maxy] or [--view_center x,y --scale scale]
[--showlayers layer1,layer2,...,layerN]
[--showgroups group1,group2,...,groupN]
[--hidelayers layer1,layer2,...,layerN]
[--hidegroups group1,group2,...,groupN]
```

The parameters here basically line up with the `GETMAPIMAGE` mapagent operation

Running the tool will render an image of the map with the given definition and view parameters in the requested format and outputs the image content to standard output.

By sending the image content to standard output, the tool assumes a HTTP-like language neutral embedding API. Any programming environment/framework that supports spawning processes and reading its stdout stream can implement a basic map viewer.

2. Querying features ("clicking" a point)

```
MgMapRender.exe query --map path/to/mapdef.xml --width image_width --height image_height --dpi dpi
[--extent minx,miny,maxx,maxy] or [--view_center x,y --scale scale]
[--query_point x,y] or [--query_geom geometry_wkt]
```

The parameters here basically line up with the `QUERYMAPFEATURES` mapagent operation

= Custom Map Definition XML schema =

Unlike the regular Map Definiton XML schema, the XML schema of the mapdef is substantially different. The reason for this is that this tool does not have a notion of a "resource service" so any layers on this map need to inline their Layer Definition and Feature Source definitions in the same document.

```
XML schema TBD
```

= "Compiling" map definition XML =

Having to point to an XML document every time to render a map image could introduce understandable performance overhead from needing to parse and load this XML on every invocation of the tool.

To avoid this, our tool could support "compiling" this XML map definition into a more compact binary form analogous to existing `MgMap` serialized state in current MapGuide proper that you would reference via a `SESSION` and `MAPNAME` pair when doing any map rendering or query operations.

Then instead of pointing to a mapdef XML document, one could point to this binary blob instead