Mapbox-gl-js: Create hexbinning example

[geraldstanje]

Hi,

I would like to request the following feature for mapbox-gl-js, which uses WebGL to render it. Is there currently a way to implement a similar plot?
http://jsfiddle.net/ts4oyyn0/10/

Thanks,

[mourner]

Currently no plans to do this. I think it makes more sense to generate hexbins as GeoJSON polyhons (like Turf does) and then render them with GL JS.

[geraldstanje]

do you mean in the way the example currently works (jsfiddle)? can you point me to any examples which do the rendering in GL JS?

[lucaswoj]

@geraldstanje We don't currently have any examples of this functionality.

@tristen Do you think we could / should build one?

[geraldstanje]

@lucaswoj that would be very useful.

[mollymerp]

happy to hit this if you're swamped @tristen. lmk 👍

[tristen]

@mollymerp yes please!

@geraldstanje it's a little out of date but there's a binning example here: https://www.mapbox.com/analysis-demos/census/ with code for the demo here: https://github.com/mapbox/analysis-demos/tree/mb-pages/census

[geraldstanje]

@tristen thanks so far.
@mollymerp great, I'm looking forward to your example.

if you want to plot the frequency of points within all polygons (see my example) its better to calculate it on the server rather than doing it in the frontend by calling turf.count(hexgrid, dots, 'pt_count'); ?

[peterqliu]

Hex-binning is useful, but I don't think this should be a gl-js example. As @mourner said, the only piece relevant to GL here is drawing a geoJSON polygon, for which there is already an example.

There is an infinite set of building blocks like Turf that works _with_ Mapbox GL (and that's great!), but to avoid future confusion, we should scope our GL examples only to illuminate GL functionality. In this case, the only steps not covered in the example above are 1) calculating the hexbin geometry, and 2) counting the points within each hex. Neither of these are gl-js features.

That said, we should whip up an example for @geraldstanje , and perhaps push this as a blog post as another great use case for GL. The support team could also use this as a lesson for tying together GL + Turf.

cc/ @danswick

[tmcw]

we should scope our GL examples only to illuminate GL functionality.

To make this more obvious for others, could you use a different word than illuminate? There are two interpretations of your note - that GL examples should try to emphasize GL features (which I agree with) or that GL examples should use GL exclusively (which I don't agree with).

The one I don't agree with (which I'm not sure you're trying to say anyway), I don't agree with because 'integration examples' have been very useful for Mapbox.js because integrating different libraries, like Turf and Mapbox GL JS is

1. Much of what novice programmers do.
2. Very confusing to novice programmers but seems 'obvious' to pros.

So there's plenty of value even in really simple integration examples. We won't run out of bits.

[peterqliu]

'integration examples' have been very useful for Mapbox.js

@tmcw this is true, but it's more a question of _where_ to do it than _whether_. Our support team actually cited these integration examples as a cause for sprawl that makes the mapbox.js docs hard to navigate.

I'm glad you brought up the novice, because when we're still learning the individual pieces, talk of integrating them _adds_ confusion of where one ends and another begins. While learning other libraries, I've fallen into traps analogous to these:

• Whoa, mapbox-gl-js does hexbinning?
• Ah, no. So I need Turf in order to use mapbox-gl-js?
• Oh, okay. So mapbox-gl-js works only with Turf to do hexbinning?

GL examples should use GL exclusively (which I don't agree with)

Every new piece adds potential for confusion, so examples should use the minimum necessary to demonstrate the narrow goal at hand.

[peterqliu]

If there's a clear way to separate API-specific examples (what this building block is) from integration examples (how to put these blocks together), this would work. Solves issues of both doc organization and novice confusion.

[tmcw]

We already have category headers in Mapbox.js separating pure examples from examples that need other libraries, including a header called "Turf GIS".

[tristen]

• Whoa, mapbox-gl-js does hexbinning?
• Ah, no. So I need Turf in order to use mapbox-gl-js?
• Oh, okay. So mapbox-gl-js works only with Turf to do hexbinning?

These are fine speed bumps no? Code examples have inline commenting to cite caveats.

Our support team actually cited these integration examples as a cause for sprawl that makes the mapbox.js docs hard to navigate.

This is a design problem with our docs (which we'll fix!). It shouldn't stop anyone from adding more examples to those docs. And solving them should ease speedbumps above. Agree that we should always try and find the right home for code documentation but I'd argue that this is the place for it. Not a blog post we need to carry a link around for.

[danswick]

I agree with @peterqliu that we need to be careful about examples that integrate other libraries with Mapbox GL JS. We could do so by creating more visual separation on the examples page, writing better comments, and/or including more descriptive narrative on the page (we've started doing this to some extent for mobile examples).

This is a design problem with our docs

Definitely agree. By way of (ahem) example - while it's true the the Turf examples all fall under the Turf heading, many users arrive at examples via Google searches and don't necessarily see where the example falls in the page's structure.

Regarding the original example request in this issue, I think the key thing we'll want to demonstrate is the process of:

1. Doing stuff with Turf
2. Creating a GeoJSON source and/or setData'ing an existing GeoJSON source with the results
3. Creating/updating a layer with said source.

A hexbin example that the user can update by adding/removing points might be a nice way to demonstrate how setData works as well.

[mollymerp]

@danswick @peterqliu -- do you think this would be better as a blog post? we could open source the code to serve as a more involved 'puzzle-pieces' demo?

I like that blog posts allow for more context and explanation, but don't like their ephemeral nature and the fact that users in the future might have trouble finding it.

[YunjieLi]

per chat w/ @mollymerp I'm happy to jump in to create an example for this.
Questions:

• Not sure which of the current categories this example falls into. Do we need a new one for 'integration examples'?
• I'd like to use a geojson with a lot of points for this example. I don't know if I could reference the geojson from an external url/space for the brevity of the example code?

PS. I'm also thinking of potentially creating a hexbinning+3d extrusion demo/blog post.

[ryanbaumann]

@yunjieli Nice!

For hosting larger geojson, see the method used in the cluster example https://www.mapbox.com/mapbox-gl-js/example/cluster/

[mollymerp]

I think it makes more sense to put a hexbin example in mapbox/analysis-demos than on the examples page. That way you can put it in on the blog and have the code open sourced for people who are curious about the implementation details, but you don't have to worry about condensing things down to example size.

[YunjieLi]

thanks @ryanbaumann !

I'm creating this demo in labs #1062. Since the turf part would is going to be pretty complicated, I second @mollymerp 's suggestion to make it a blog post instead of a GL JS example.