Perspective from someone coming to this cold

[andybak]

I'm at the "trying to understand what the heck it is stage".

I know what deck.gl does.

From the Overview and Get Started text it seems Nebula enables an editing UI for deck.gl maps. Fair enough.

I look for an interactive example. Oh good. Here's one: https://nebula.gl/docs/interactive-examples/world-heritage

Huh? Map clustering and simple data viz. That seems to bear no resemblance to what Nebula claims to do. Have I misunderstood the purpose of the repo.

I then look at the front page of the Github repo and there's a gif that clearly shows the kind of interactive editing I was expecting.

So in short - the UNESCO interactive example is rather confusing and makes it less clear what Nebula does.

[xintongxia]

@andybak

From the Overview and Get Started text it seems Nebula enables an editing UI for deck.gl maps. Fair enough.

nebula.gl is an editing library on top of deck.gl, it can directly manipulate the geometries and update corresponding deck.gl layers.

You can have some ideas what the lib does by checking the GeoJSONEditor

So in short - the UNESCO interactive example is rather confusing and makes it less clear what Nebula does.

You are right about this, we haven't updated our website examples.

[supersonicclay]

You are right that the clustering and HTML/React overlays is perhaps a bit tangential to the editing theme of nebula.gl. The primary usages that we've seen of nebula are indeed GeoJSON editing which @xintongxia linked to the demo of.

However, we have seen applications used for geometry editing that also incorporate the HTML/React overlays to provide deeper interactivity. And HTML/React overlays was something that deck.gl didn't provide. But perhaps this belongs in deck.gl or in another library in the future.

Thanks for the great question!

[andybak]

OK. So would it be fair to say that nebula provides two broad pieces of functionality and they are fairly orthogonal?

If so - that would be a great sentence to put in "getting started" and it would be fantastic to point to two live demos - the overlay one that's currently there and the one linked to here which wasn't mentioned in that guide.

[georgios-uber]

Thanks for the feedback @andybak ! We will improve the docs to avoid future confusion.

[ibgreen]

My input is that a pass on the docs makes sense. It is clear that nebula.gl has evolved a lot since its inception.

My sense is that this is now best described as "a suite of components for building (geospatial) tooling", consisting of:

• a suite of composable geometry editing modes optimized for GeoJSON:
  • The EditModes architecture
  • a react component that accepts edit modes
  • a deck.gl editable layer that accepts edit modes.
• Measurement Tools (measures angle, area, ...)
• UI Overlays (React/HTML based) - for map synchronized user interface components.

In addition, we could add some background information to the main doc page on the website to help people understand where we come from:

History/Background

nebula.gl started out as an editable geojson layer for deck.gl, but now has a growing range of components to help build (primarily geospatial) tooling.

[ibgreen]

A few thought about where to put the HTML overlays:

I agree that the HTML overlays do not fit perfectly into nebula.gl, but on the other hand they are not a perfect fit in any of the https://vis.gl modules either

• nebula-gl: They are not necessarily specifically related to editing
• react-map-gl: They could go here, but again they are generic and have no dependency on mapbox-gl.
• deck.gl: deck is a WebGL framework, it is not intended to be a home for generic React components, it is already a very large repo.
• a separate repo: the vis.gl maintainers don't like to maintain and coordinate lot of small repos - we prefer a smaller selection of bigger monorepos.

My thinking is that if nebula.gl is described as a home for "components for building web tools on top of maps" (as suggest in previous comment), then having the overlays here makes some sense.