Merge pull request #8 from eoda-dev/dev

Dev

Author: crazycapivara

.github/workflows/deploy-docs.yml

@@ -0,0 +1,53 @@
+name: Build and deploy docs
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+    branches:
+      - "*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package
+        run: pip install -e .
+
+      - name: Install dependencies
+        run: pip install -r requirements.docs.txt
+
+      - name: Build docs
+        run: mkdocs build -d dist
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pytest.yml

@@ -0,0 +1,31 @@
+name: Test package
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # You can test your matrix by printing the current Python version
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+      - name: Install package
+        run: pip install -e .
+
+      - name: Install dev dependencies
+        run: pip install -r requirements.dev.txt
+
+      - name: Test package
+        run: pytest

README.md

@@ -1,4 +1,38 @@
-# OpenLayers for Python
+# py-openlayers: OpenLayers for Python
+
+[![Release](https://img.shields.io/github/v/release/eoda-dev/py-openlayers)](https://img.shields.io/github/v/release/eoda-dev/py-openlayers)
+[![pypi](https://img.shields.io/pypi/v/openlayers.svg)](https://pypi.python.org/pypi/openlayers)
+[![License](https://img.shields.io/github/license/eoda-dev/py-openlayers)](https://img.shields.io/github/license/eoda-dev/py-openlayers)
+[![OpenLayers JS](https://img.shields.io/badge/OpenLayers-v10.5.0-blue.svg)](https://github.com/openlayers/openlayers/releases//tag/v10.5.0)
+
+Provides Python bindings for [Openlayers](https://openlayers.org/), a high-performance, full-featured web mapping library that displays maps from various sources and formats. It makes it a easy to create interactive maps in [Marimo](https://marimo.io/) and [Jupyter](https://jupyter.org/) notebbooks with a few lines of code in a pydantic way.
+
+## Features
+
+### Tiled Layers
+
+Pull tiles from OSM, CartoDB, MapTiler and any other XYZ source.
+
+
+### Vector Layers
+
+Render vector data from GeoJSON, TopoJSON, KML, GML and other formats. 
+
+### Controls
+
+Add geocoding, draw, full screen and other controls to your map.
+
+### WebGL
+
+Render large data sets using WebGL.
+
+### PMTiles
+
+Render PMTiles from vector and raster sources.
+
+### Interactions
+
+Drag and drop GPX, GeoJSON, KML or TopoJSON files on to the map. Modify, draw and select features.
 
 ## Installation
 
@@ -7,3 +41,21 @@ uv init
 
 uv add "git+https://github.com/eoda-dev/py-openlayers@main"
 ```
+
+## Quickstart
+
+```python
+import openlayers as ol
+
+# Jupyter or Marimo
+m = ol.MapWidget()
+m # Display map
+
+# Standalone
+m = ol.Map()
+m.save()
+```
+
+## Note
+
+The documentation is still in an early stage, more examples will be added as soon as possible.

TODOS.md

@@ -0,0 +1,5 @@
+# TODOS
+
+## STAC layers
+
+https://openlayers.org/en/latest/examples/stac-item.html

docs/api/basemaps.md

@@ -0,0 +1,7 @@
+# Basemaps
+
+::: openlayers.basemaps.BasemapLayer
+
+::: openlayers.basemaps.CartoBasemapLayer
+
+::: openlayers.basemaps.MapTilerBasemapLayer

docs/api/controls.md

@@ -0,0 +1,3 @@
+# Controls
+
+::: openlayers.controls

docs/api/express.md

@@ -0,0 +1,3 @@
+# OpenLayersExpress
+
+::: openlayers.express.GeoJSONLayer

docs/api/geopandas.md

@@ -0,0 +1,5 @@
+# GeoPandas
+
+::: openlayers.geopandas.OLAccessor
+
+::: openlayers.geopandas.GeoDataFrame

docs/api/layers.md

@@ -0,0 +1,15 @@
+# Layers
+
+::: openlayers.layers.Layer
+
+::: openlayers.layers.VectorLayer
+
+::: openlayers.layers.VectorTileLayer
+
+::: openlayers.layers.TileLayer
+
+::: openlayers.layers.WebGLVectorLayer
+
+::: openlayers.layers.WebGLVectorTileLayer
+
+::: openlayers.layers.WebGLTileLayer

docs/api/map.md

@@ -0,0 +1,8 @@
+# Map
+
+::: openlayers.Map
+
+::: openlayers.view.View
+
+::: openlayers.MapWidget
+

docs/api/sources.md

@@ -0,0 +1,3 @@
+# Sources
+
+::: openlayers.sources

docs/api/styles.md

@@ -0,0 +1,5 @@
+# Styles
+
+::: openlayers.styles.FlatStyle
+
+::: openlayers.styles.default_style

docs/concepts/controls.md

@@ -0,0 +1,9 @@
+# Controls
+
+Controls are user interface elements that you can add to your map:
+
+```python
+-8<-- "concepts/controls.py"
+```
+
+> See [Controls API](../../api/controls/)

docs/concepts/geopandas.md

@@ -0,0 +1,7 @@
+# GeoPandas
+
+Python-OpenLayers shipes with a [GeoPandas](https://geopandas.org/) extension:
+
+```python
+-8<-- "concepts/geopandas.py"
+```

source renamed to docs/concepts/interactions.md

@@ -0,0 +1,48 @@
+# Layers and sources
+
+Sources and layers are used to display _raster_ or _vector_ data on your map.  
+
+## Sources
+
+Sources state which data the map should display.
+
+```python
+-8<-- "concepts/sources.py"
+```
+
+> See [Sources API](../../api/sources/)
+
+## Layers
+
+ A layer defines how a source is displayed on the map:
+
+```python
+-8<-- "concepts/layers.py"
+```
+
+> See [Layers API](../../api/layers/)
+
+## Styles
+
+Vector layers are styled with an object containing properties for the different styles, such as _stroke_, _fill_, _circle_ or _icon_:
+
+```python
+style = ol.FlatStyle(
+    stroke_color = "yellow",
+    stroke_width = 1.5,
+    fill_color = "orange" 
+)
+```
+
+It is also possible to use a simple dictonary instead. In this case property names must use hyphens instead
+of underscores:
+
+```python
+const style = {
+  "stroke-color": "yellow",
+  "stroke-width": 1.5,
+  "fill-color": "orange",
+}
+```
+
+> See [Styles API](../../api/styles/) and [ol/style/flat](https://openlayers.org/en/latest/apidoc/module-ol_style_flat.html) for details.

docs/concepts/layers.md

@@ -0,0 +1,31 @@
+# Map
+
+The [Map](../../api/map/#openlayers.Map) is the core component of your visualization, to which other components such as [controls](../controls), [layers](../layers) or overlays are added. Components can be added either during initialization or afterwards:
+
+```python
+-8<-- "concepts/basic_map.py"
+```
+
+## View state
+
+Properties such as _center_, _zoom level_ and _projection_ are managed by the [View](../../api/map/#openlayers.view.View) instance:
+
+```python
+-8<-- "concepts/view.py"
+```
+
+## Basemaps
+
+A basemap in openlayers consists of one or more layers from your layer stack:
+
+```python
+-8<-- "concepts/basemaps.py"
+```
+
+> See [BasemapLayer API](../../api/basemaps/#openlayers.Basemaps.BasemapLayer)
+
+If you hand over an empty layer stack to your map, a blank background is displayed:
+
+```python
+m = ol.Map(layers=[])
+```

docs/concepts/map.md

@@ -0,0 +1,8 @@
+import openlayers as ol
+from openlayers.basemaps import CartoBasemapLayer, Carto
+
+# Use default OSM basemap
+m = ol.Map(layers=[ol.BasemapLayer()])
+
+# Use a CartoDB basemap
+m = ol.Map(layers=[CartoBasemapLayer(Carto.DARK_NO_LABELS)])

docs/examples/concepts/basemaps.py

@@ -0,0 +1,7 @@
+import openlayers as ol
+
+# Add components during initialization
+m = ol.Map(controls=[ol.ZoomSliderControl()])
+
+# Add components after initialization
+m.add_control(ol.FullScreenControl())

docs/examples/concepts/basic_map.py

@@ -0,0 +1,7 @@
+import openlayers as ol
+
+# Add controls during initialization
+m = ol.Map(controls=[ol.ZoomSliderControl(), ol.OverviewMapControl()])
+
+# Add components after initialization
+m.add_control(ol.ScaleLineControl(units="degrees"))

docs/examples/concepts/controls.py

@@ -0,0 +1,7 @@
+import openlayers as ol
+from openlayers.geopandas import GeoDataFrame
+
+data = "https://openlayers.org/en/latest/examples/data/geojson/roads-seoul.geojson"
+
+m = GeoDataFrame.from_file(data).ol.explore(tooltip=True)
+m.add_control(ol.ScaleLineControl())

docs/examples/concepts/geopandas.py

@@ -0,0 +1,16 @@
+import openlayers as ol
+
+data = "https://openlayers.org/en/latest/examples/data/geojson/roads-seoul.geojson"
+
+vector = ol.VectorLayer(
+    id="roads",
+    source=ol.VectorSource(url=data),
+    fit_bounds=True,
+)
+
+
+m = ol.Map(
+    ol.View(rotation=3.14 / 8),
+    layers=[ol.BasemapLayer(), vector]
+)
+m.add_default_tooltip()

docs/examples/concepts/layers.py

@@ -0,0 +1,14 @@
+import openlayers as ol
+
+geojson = ol.VectorSource(
+    url="https://openlayers.org/en/latest/examples/data/geojson/roads-seoul.geojson"
+)
+
+geotiff = ol.GeoTIFFSource(
+    sources=[{"url": "https://s2downloads.eox.at/demo/EOxCloudless/2020/rgbnir/s2cloudless2020-16bits_sinlge-file_z0-4.tif"}]
+)
+
+pmtiles = ol.PMTilesVectorSource(
+    url="https://r2-public.protomaps.com/protomaps-sample-datasets/nz-buildings-v3.pmtiles",
+    attributions=["© Land Information New Zealand"]
+)

docs/examples/concepts/sources.py

@@ -0,0 +1,11 @@
+import openlayers as ol
+
+initial_view = ol.View(center=(9.5, 51.31667), zoom=14)
+
+m = ol.Map(initial_view)
+
+# Change view settings afterwards
+m.set_center(lon=172.606201, lat=-43.556510)
+m.set_zoom(14)
+
+m.set_view(ol.View(center=(172.606201, -43.556510), zoom=12))