Add polygon support

Add support for Canvas.polygon. Something like:

endangered_agg = cvs.polygon(df, 'my_polygon_field', how='sum', field='endangered_species_list_score')

[jbednar]

Now in master.

[jonmmease]

I think I have a pretty clear understanding of what this might look like now that I’ve finished the following PRs:

• RaggedArray pandas extensions array (https://github.com/pyviz/datashader/pull/687)
• Support for row-oriented coordinates in Canvas.line (https://github.com/pyviz/datashader/pull/694)
• Add quadmesh glyph with rectilinear and curvilinear support (https://github.com/pyviz/datashader/pull/779)

Here’s what I’m thinking…

Polygon representation

I think the easiest thing to do here is to represent a polygon set as a pair of arrays, one for each the x and y coordinate. nan values are then used to indicate the end of one polygon and the start of the next.

Polygon fill rendering

In the quadmesh PR (https://github.com/pyviz/datashader/pull/779) I implemented filling using the “crossing number” point-in-polygon test (http://geomalgorithms.com/a03-_inclusion.html). If we use this same algorithm for these sets of polygons then we naturally get the following behavior.

• The first polygon is filled in if it’s the only one
• The second (and third, forth, …) polygon acts as a hole if it is enclosed in the first polygon, or it is filled in as a separate polygon if it is outside of the first polygon.

Polygon API

I propose that the Canvas.polygon method have the same API as Canvas.line. We don’t need to cover the full API right away, but in principle every combination of the axis and column arguments supported by Canvas.line could also be supported by Canvas.poly. Here are the two API uses that I expect to be most common:

Variable sized polygons, one per row. In this case, the x and y coordinates would be stored as RaggedArray columns in the DataFrame.

canvas.polygon(df, 'x', 'y', axis=1)

A collection of fixed-size polygons. This would be useful for displaying a large collection of polygons that all have the same number of vertices. In this case, the data frame would have a column for each x and y coordinate. For example, rendering a collection of pentagons would look something like this

canvas.polygon(df, ['x0', 'x1', 'x2', 'x3', 'x4'], ['y0', 'y1', 'y2', 'y3', 'y4'], axis=1)

Polygon outlines

A nice consequence of using this polygon representation and this API is that we get polygon outline rendering for free. Just change canvas.polygon to canvas.line. The line method already uses nan values to separate lines, and as long as the polygons are closed, the line method would automatically be able to draw the polygon outlines.