Add add_vector_layer function

[giswqs]

Fix #437

This PR adds:

• add_vector_layer function for loading any geopandas supported vector format, including shapefile, geopackage, kml
• vector_to_geojson function for converting any geopandas supported vector format to GeoJSON
• Update the notebook example to include the add_vector_layer examples.

---

📚 Documentation preview: https://jupytergis--445.org.readthedocs.build/en/445/
💡 JupyterLite preview: https://jupytergis--445.org.readthedocs.build/en/445/lite

[github-actions]

👈 Launch a Binder on branch giswqs/jupytergis/vector

[github-actions]

Integration tests report: appsharing.space

[martinRenou]

I guess this will download the GeoJSON if I do something like:

url = "https://github.com/opengeos/datasets/releases/download/world/countries.geojson"
doc.add_vector_layer(path=url, name="GeoJSON")

This is unfortunate since it will embed the GeoJSON data into the JGIS file, which may be an unwanted behavior. Keeping the GeoJSON source pointed by URL may be better.

So I guess we'd want to consider two approaches in this function:

• if it's a URL, we keep the URL as-is and don't embed the data
• if it's a local file or some in-memory data in Python, we don't have the choice but to embed the data so we keep this logic here

[mfisher87]

@martinRenou @giswqs how can we get this PR moving forward?

On Martin's comment above, I prefer not embedding the data in the project file. GeoJSON files can get quite large, and I think if we're ever going to be embedding data in the project file we should consider a string-encoded binary format.

[martinRenou]

we should consider a string-encoded binary format

There are cases we embed JSON data already (e.g. when passing data from Python's memory directly, instead of through file url/path), we should definitely improve things and consider another approach 👍🏽

[mfisher87]

Yeah. I think it makes sense to punt on a better format until later :)

[mfisher87]

We're looking to get this PR over the finish line. We need to rebase to start with.

Then, we discussed a plan which we're not sure how to implement, and I'd like to revisit the minimal version of this that we can complete tomorrow.

• When adding a layer in a format OpenLayers doesn't support with the Python API, convert the data to a local GeoJSON file (aka "the cached file") in a temp location instead of embedding in the project file JSON. Use geopandas as the mechanism to convert the data as this PR already does.
• Store the path to the cached file as a new schema element.
• When loading the project, check if the cached file exists, and if not, re-hydrate the cache. BUT: If we're using geopandas as the conversion mechanism, how do we trigger that when opening a project file by double-clicking on it, as opposed to calling add_vector_layer from a Notebook with a running Python kernel?

I think we've bitten off a big task in this plan and that we can break it into two concerns:

1. Provide a convenience method to add a vector layer "smartly" -- less API surface area for users to keep in their brain. Fairly achievable in a small amount of time.
2. Work towards eliminating the process of embedding GeoJSON in the project file. Requires some big architectural thinking and broad code changes. We all feel this is architecturally important, but don't have an ideal solution.

[arjxn-py]

Thanks all for looking into this. I agree with most of the things mentioned. Rebase shall be easy since no conflicts.

When adding a layer in a format OpenLayers doesn't support with the Python API, convert the data to a local GeoJSON file (aka "the cached file") in a temp location instead of embedding in the project file JSON. Use geopandas as the mechanism to convert the data as this PR already does.

I like that we would not be embedding the geojson in .jGIS file - but can we also think of giving user an option if they don't want to save the data in a temp location but maybe a defined path? - Since we also need to consider the portability/shareability of the .jGIS file.

When loading the project, check if the cached file exists, and if not, re-hydrate the cache.

Infact, I don't think our typescript logic supports something like this yet. In theory, if we want to do this - we'd have to store the path of both Cached Source & Actual Source in the schema & do the thing you're suggesting.

BUT: If we're using geopandas as the conversion mechanism, how do we trigger that when opening a project file by double-clicking on it, as opposed to calling add_vector_layer from a Notebook with a running Python kernel?

That's the core blocker - we simply can't use geopandas without a python server - either we find a similar tool to do that conversion on the typescript part or we raise an informative error admitting it as a current limitation when not using a python server.

I think we've bitten off a big task in this plan and that we can break it into two concerns:

1. Provide a convenience method to add a vector layer "smartly" -- less API surface area for users to keep in their brain. Fairly achievable in a small amount of time.
2. Work towards eliminating the process of embedding GeoJSON in the project file. Requires some big architectural thinking and broad code changes. We all feel this is architecturally important, but don't have an ideal solution.

Agreed - this split makes sense. Thanks again, everyone. I hope each of you gets to contribute your piece, and that you’re enjoying the hack!