Monday, 31 March 2014

Re-visiting the Maestro layer style editor

Consider the current layer style editor in Maestro


Now, despite being serviceable for our needs it does suffer from several shortcomings:

  • A lot of controls are being created to produce this UI. This is really sluggish when you're editing a style with lots of rules and you need to scroll a lot. We also run the risk of running out of handles if we're editing a really big style.
  • The style previews are Maestro-drawn approximations. Composite styles are blank because we simply have no idea how to draw them in pure .net. Using GETLEGENDIMAGE solves our style preview accuracy problems, but the way this UI has been set up makes it hard to use GETLEGENDIMAGE on say a 100 rule layer (arguments about why you have a layer with 100 theme rules aside) without clogging up your application.
The UI as whole looks like a data grid of sorts. Shouldn't this whole UI be more easier and streamlined if it was grid based?

Yes indeed, so that's what we've done. Meet the new grid-based style editor.


The benefits of the grid-based editor is that because we are using a DataGridView component, we have the ability to not only leverage data-binding against rule objects with very little code plumbing, but also to be able to determine what rules are actually in view on the grid.

As a result, we can issue GETLEGENDIMAGE-based previews only for what you currently see. These requests are also done asynchronously on a background thread, ensuring maximum application responsiveness while not making the MapGuide Server cry since we are only asking for previews for what we can currently see.

Clicking on the Filter cell brings up the Expression Editor. Clicking the LegendLabel cell lets you edit the cell contents. Clicking the Style cell brings up the matching point/line/area style editor and clicking the Label cell brings up the label style editor. Any edits you make are immediately visible on the grid when you close the editor dialog.

When you scroll through the grid, you can see rules that haven't had a preview generated for them yet.


To see the previews for these rules, you can click the Refresh Previews button to refresh the style previews for the rules currently in view.


So now that we have a means for having accurate style previews without obsessively hammering a MapGuide Server, it means that we can also show previews for composite styles. Something that was not possible with the old editor.


Clicking the Style cell for a composite rule in this case still brings up the mega-verbose Symbol Instances dialog for editing composite symbolizations, but at least there's no longer a need to delve into this particular dialog just to get a style preview for a composite rule, because like the other style types, previews for composite rules are also shown in the grid as well.

Moving to a grid-based UI opens up other avenues that were not possible before, like being able to filter the current list of rules by some criteria (handy if you want to focus on some specific rules in a layer with 50+ rules). Not that we have done this already, but these are things that a grid-based UI gives us the ability to explore.

Another improvement that's only available for this grid-based style editor is support for theming composite styles. There are some caveats with this support:
  • The theming algorithm is very naive and basic due to the complexity of Advanced Stylization and the thousands of different possible permutations that a given composite rule could be in. However if you stick to a basic prototype of an un-styled point/line/area the theming algorithm should be able to pick up the relevant color property and apply the theme color ramp to it.
  • On that subject, theming a composite style requires a rule to already exist in the style as a prototype. While this is optional for basic styles, this is required for composite styles.
Now that's not to say we have replaced the old style editor. A new feature like this needs some time to be blooded in as a proper replacement. The old editor is still available if you un-tick the new editor option we've added to the options dialog.


The next release of Maestro will use the grid-based editor by default.

Thursday, 27 March 2014

Announcing: mapguide-rest 0.6

Here's the first release of mapguide-rest

And a general disclaimer: This is still work-in-progress code that's not ready for production use. However, that shouldn't stop you from downloading this release and having a play around :)

I have a bunch of mapguide-rest related posts in the draft queue, but it helps to have an accessible release as a point of reference for these posts rather than tell you to get the latest git clone of mapguide-rest.

One thing that stands out in this release since the initial announcement is the introduction of integrated REST API documentation.

What? REST API documentation? Aren't RESTful APIs self-describing, self-documenting and all this other stuff?

That may be true in an ideal sense, but pragmatism trumps idealism. mapguide-rest is the GET/POST/PUT/DELETE to a set of well-crafted URLs variety of REST API. In such cases, it definitely helps to know the definitive list of allowed URLs you can make requests to and the documented parameters that are allowed for each URLs.

So this is what we've provided for you. The documentation can be accessed at the following URL:

http://yourservername/mapguide/rest/doc/index.html

But this isn't a static document.


It's a fully interactive one!


The interactivity allows you to fully explore the REST API in a very intuitive fashion.

All this was made possible with the use of the Swagger documentation framework. The API reference is built on a modified version of Swagger UI. I've found Swagger to be a wonderful tool for generating REST API documentation. The initial set up takes some effort, but the pay-off of the final result is so worth it!

So now that we have a release on the board, stay tuned for more about the GeoREST-style data publishing framework.

Download

Saturday, 22 March 2014

Generating themes by external lookup values

Ever generate an individual theme on a property and get frustrated at the labels that are generated because your property is basically a "foreign key", where the real descriptive labels come from the lookup table that the foreign key points to?


Sure you could set up a view (if your Feature Source is a relational database) to include the descriptive label properties or (gasp) make an Extended Feature Class that uses Feature Joins to pull in the description properties, but there's overhead involved when theming on strings as opposed to theming on numerical lookup ids.

Wouldn't it be nice if there's a way where we can theme based on description values from a lookup table but retain the ability to theme by the base numerical or string lookup id?

In the next release of MapGuide Maestro, we've solved this problem for you.

Meet the new Theme Generation dialog


The Data Setup portion of the dialog has been split into 2 sections:

  • Theme based on values/ranges from this class: This is the existing theming option
  • Theme based on values from an external class: This is the new theming option where you can source the theme rules from an external class definition (eg. A lookup table)
To illustrate this new feature, consider we're theming against the Parcels Feature Source from the Sheboygan Sample data set (as per the above screenshot). We'd pick the RTYPE property, which tells us that 8 theme rules will be created.


Now unfortunately, the RTYPE property only contains abbreviated values and the theme that gets generated doesn't produce very informative labels (as seen in the first screenshot).

Now suppose we had an external Feature Source or lookup table that has descriptive labels for these RTYPE values.


We can use the new theming option to generate theme rules using the main property as a frame of reference.

Firstly, you would specify the Feature Source containing your lookup table


Then specify the Feature Class that represents the lookup table


Then you specify the key and value properties that will determine the filters and labels that will be generated for your theme rules.


If you want to apply any filtering on the lookup table itself to reduce the number of rules that would be generated, you can specify the FDO filter in the Filter field.

Then click Update to get a feel for the number of rules that will be generated. The rules that will be generated follow this form:
  • Filter: RTYPE = [Value of Default:ParcelType.Type]
  • Label: [Value of Default:ParcelType.Description]

At this point, you can then tweak the color setup and other theme generation settings as before. Once you click OK you can see that the theme rules generated match the values from your lookup table.


As you can hopefully see, this feature should dramatically simplify theming of features from relational databases without requiring any table/view contortions to get the desirable theme rules.

Thursday, 20 March 2014

Creative uses for Watermarks

I give you exhibit A: Injecting useful debugging information into a rendered map.


Sunday, 16 February 2014

Cool things to do with the mapguide-rest API: Part 2

Now for part 2 of the cool things you can do with the mapguide-rest API.

Making a new MgMap

mapguide-rest provides a shim to the CREATERUNTIMEMAP operation that returns the same response as the operation we've introduced for the MapGuide 2.6 release. Except this one can work with older releases as well.

POST http://servername/mapguide/rest/services/createmap.xml
mapdefinition = Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition
requestedfeatures = 7



Or if you want a JSON version

POST http://servername/mapguide/rest/services/createmap.json
mapdefinition = Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition
requestedfeatures = 7



Creating a map with the above operation will also create a selection set as well with the same map name (which you can find out inside the response of the above operation)

MgMap interaction

Having created a Runtime Map, here's how you can describe and interact with it.

In case you created a Runtime Map without requesting a layer structure, you can request it like so:

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layers.xml



Or if you want a JSON version

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layers.json



You can list the groups in the same fashion

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layergroups.xml


Or if you want a JSON version

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layergroups.json




But the most important thing you want to do with a runtime map is to render an image of it, here's how you do it

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/overlayimage.png?x=-87.73&y=43.74&scale=75000&width=800&height=600&behavior=2



Note that like GETDYNAMICMAPOVERLAYIMAGE, setting X/Y/Scale/DPI/width/height modifies the state of the MgMap. Knowing some math, you have the means of building a basic map viewer by tweaking the x, y and scale parameters based on mouse clicks and movements.

If you want to request a non-overlay image (ie. GETMAPIMAGE instead of GETDYNAMICMAPOVERLAYIMAGE), just replace overlayimage.png with image.png

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/image.png?x=-87.73&y=43.74&scale=75000&width=800&height=600



You can also request a DWF plot of this map in its current view as well

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/plot.dwf



Or if you have a PrintLayout, you can request a DWF plot using the specified layout.

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/plot.dwf?printlayout=Library://Samples/Sheboygan/Layouts/SheboyganMap.PrintLayout



Map Selection interaction

Like the Runtime Map, there are many ways to interact with a map selection. Like the Runtime Map, interaction with a map selection requires a session id and the map name.

Here's how you get the raw XML of the selection

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/xml


Here's how you can describe what layers are in the selection set

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/layers.xml




Or if you want a JSON version

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/layers.json



If you want to get the actual selected features

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/features.xml/Parcels


Or if you want a more usable format like GeoJSON

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/features.geojson/Parcels




And with any request that returns feature data, we support transform-ability out of the box

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/features.geojson/Parcels?transformto=WGS84.PseudoMercator




There are 2 ways to manipulate selections.

First is by using the shim to QUERYMAPFEATURES

PUT http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection
geometry = POLYGON((-87.72464513939002 43.756626600485,-87.72464513939002 43.757316392651,-87.723570655439 43.757316392651,-87.723570655439 43.756626600485,-87.72464513939002 43.756626600485))
selectionvariant = INTERSECTS
requestdata = 15
selectioncolor = 0xFF000000
selectionformat = PNG
maxfeatures = -1
persist = 1

format = json

The other way is to POST the selection XML 

POST http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/xml


OpenLayers support

If you want to see more concrete examples of map and selection interaction, you can check out the OpenLayers samples included with mapguide-rest, which have been ported over from the ones that will be included in MapGuide Open Source 2.6. These sample use a new OpenLayers.Layer.MapGuideREST class which uses the REST APIs offered by mapguide-rest.

Next post will focus on the other half of mapguide-rest, the data publishing replacement for GeoREST

Monday, 10 February 2014

Cool things to do with the mapguide-rest API: Part 1

Rather than give a verbatim overview of everything that is provided by the REST API in mapguide-rest (because a blog post that is just raw API documentation doesn't exactly sound like thrilling content to read), I'm going to approach this from a different angle.

For this series of posts, I'm going to specifically focus on some of the cool things you can do through the REST API that is either:

  1. Not possible through the mapagent
  2. Is possible through the mapagent, but is really unintuitive or returns content in an undesirable format
For anything else, I'd figure you could either just figure it out from the URLs provided by the various HTML representations available:
  • Site Repository: http://servername/mapguide/rest/library/list.html
  • Coordinate System Catalog: http://servername/mapguide/rest/coordsys/categories.html
  • FDO Provider Registry: http://servername/mapguide/rest/providers.html

Querying Features

Querying data from Feature Sources is possible using the SELECTFEATURES operation in the mapagent, but has some issues that make it difficult for client applications to use:
  • The operation is very verbose and requires lots of parameters to set up.
  • The operation returns MapGuide-specific XML data, and its JSON response is a direct 1:1 conversion of the XML format.
Querying data from Feature Sources through our REST API on the other hand is a simple and intuitive affair. This is because most of the base information is in the URL itself with optional parameters specified in the query string. For example, returning all data from the feature source Library://Samples/Sheboygan/Data/Parcels.FeatureSource is simply issuing the following GET request:

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/features.xml/SHP_Schema/Parcels

This will return everything from the Parcels Feature Source under the SHP_Schema:Parcels feature class in XML format.

From this basic request, you can apply all sorts of extra parameters in various permutations to shape the response to your liking

Want to filter the data? Pass a filter parameter with your URL-encoded FDO filter string

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/features.xml/SHP_Schema/Parcels?filter=RNAME%20LIKE%20'SCHMITT%25'

Where (RNAME%20LIKE%20'SCHMITT%25') is the URL-encoded form of (RNAME LIKE 'SCHMITT%')

Want to filter the same data by bounding box instead? Pass a bbox parameter with an x1,y1,x2,y2 quartet.

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/features.xml/SHP_Schema/Parcels?bbox=-87.6,43.7,-87.7,43.8

Want to cap the results to 500 features maximum? Pass a maxfeatures parameter

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/features.xml/SHP_Schema/Parcels?maxfeatures=500

Want the geometry data transformed to a different coordinate system (eg. Web Mercator)? Pass a transformto parameter

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/features.xml/SHP_Schema/Parcels?transformto=WGS84.PseudoMercator

And here's possibly the best one of the lot, want the data in a more usable format than XML like GeoJSON? Sure you can!

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/features.geojson/SHP_Schema/Parcels

Aggregating data

Unlike the feature querying capabilities, the aggregation capabilities of the REST API are much more simplified and is focused around 3 key common scenarios:
  • Counting the number of features
  • Getting the bounding box of a feature class
  • Getting the distinct list of values for a given property
So using the same Parcels feature source, here's how you can count the number of features

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/aggregates.xml/count/SHP_Schema/Parcels


Here's how you get a bounding box

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/aggregates.xml/bbox/SHP_Schema/Parcels



Want it in a different coordinate system? Pass a transformto parameter.

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/aggregates.xml/bbox/SHP_Schema/Parcels?transformto=WGS84.PseudoMercator



Here's how you can get a distinct set of RTYPE property values

GET http://servername/mapguide/rest/library/Samples/Sheboygan/Data/Parcels.FeatureSource/aggregates.xml/distinctvalues/SHP_Schema/Parcels?property=RTYPE


And finally, if you want this in JSON instead of XML, just use aggregates.json in the URL instead of aggregates.xml

Transforming Coordinates

Here's something you definitely can't do through the mapagent. 

With the rise of HTML5 and powerful client-side web applications, probably the greatest irony about MapGuide as a web mapping solution is that we have one of the most powerful Coordinate System libraries with comprehensive support for every coordinate system on this planet you could imagine but ... we can't even tap into this library on the client-side in the web browser where it probably matters the most! It's why Fusion, OpenLayers, etc use libraries like Proj4js for its coordinate transformation needs because nothing better exists.

While I can't say that the REST API solves this problem (we're not exactly giving you csmap.js here), we do try make the issue of transforming spatial data as minimal as possible in the REST API:
  • All data with spatial/geometric components whether queried in the above fashion or published via our GeoREST-style framework (which I'll elaborate in a future post) have transform-ability built-in as an option.
  • For everything else, we provide an endpoint for transforming a batch of coordinates from one coordinate system to another. Read on to find out how.
To transform a set of coordinates from one CS to another, you simply make a POST request like so:

POST http://servername/mapguide/rest/services/transformcoords
from = "LL84"
to = "WGS84.PseudoMercator"
coords = "-87.1 43.2,-87.2 43.3,-87.4 43.1"

This will give you a response which looks like this.


More cool stuff

If this post got you excited, then stay tuned because there's more where that came from in the next part.

Announcing: MapGuide Open Source 2.6 Preview Release 2

With FDO finally in sync with MapGuide in terms of VS compiler, we are now finally able to put out another preview release of MapGuide Open Source 2.6

Apart from a newer build of Fusion, this release has no new features over the first preview release, but includes updated web tier components:
  • PHP 5.5.3
  • Apache httpd 2.4.6
  • Apache Tomcat 7.0.42
All of MapGuide and its dependent components are now built with the same Visual Studio 2012 C++ compiler, meaning from an installer perspective, we no longer need to carry Visual C++ 2008 and 2010 runtime libraries as nothing we install is built with any of these compilers anymore.

All of these changes have a major impact on MapGuide installation, configuration and deployment, which is why we've put out this preview release, so that you (the interested user/tester) can help us check and verify that all our installation/configuration bases have been covered.

And in case this wasn't apparent, as a result of everything moving to VS 2012 we no longer support Windows XP or Windows Server 2003 as an installation target. If you need to use MapGuide on either one of these OSes, you'll have to stick with the 2.5 release.