Changes between Initial Version and Version 1 of Future/RenderHelper

Timestamp:

Aug 16, 2023, 7:27:29 AM (9 months ago)

Author:

jng

Comment:

--

Future/RenderHelper

@@ +1 @@
+[[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