{"id":13585178,"url":"https://github.com/banesullivan/localtileserver","last_synced_at":"2026-05-07T19:22:17.619Z","repository":{"id":38445948,"uuid":"429299380","full_name":"banesullivan/localtileserver","owner":"banesullivan","description":"🌐  dynamic tile server for visualizing rasters in Jupyter with ipyleaflet or folium","archived":false,"fork":false,"pushed_at":"2025-04-01T21:22:43.000Z","size":117909,"stargazers_count":324,"open_issues_count":16,"forks_count":29,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-12T15:13:50.785Z","etag":null,"topics":["dynamic-tiling","folium","geospatial","gis","ipyleaflet","jupyter","large-image","localtileserver","map-tiles","python","raster","satellite-imagery","visualization"],"latest_commit_sha":null,"homepage":"https://localtileserver.banesullivan.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/banesullivan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-18T04:47:16.000Z","updated_at":"2025-05-10T06:23:25.000Z","dependencies_parsed_at":"2023-09-22T07:26:06.793Z","dependency_job_id":"0ee9b1ea-aa48-4bb7-9389-4202fcc9fa64","html_url":"https://github.com/banesullivan/localtileserver","commit_stats":{"total_commits":572,"total_committers":9,"mean_commits":63.55555555555556,"dds":0.4895104895104895,"last_synced_commit":"0920f747a027863b6434e64574b67008e5180d3a"},"previous_names":["banesullivan/flask-tileserver"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banesullivan%2Flocaltileserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banesullivan%2Flocaltileserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banesullivan%2Flocaltileserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banesullivan%2Flocaltileserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/banesullivan","download_url":"https://codeload.github.com/banesullivan/localtileserver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253764555,"owners_count":21960596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dynamic-tiling","folium","geospatial","gis","ipyleaflet","jupyter","large-image","localtileserver","map-tiles","python","raster","satellite-imagery","visualization"],"created_at":"2024-08-01T15:04:46.935Z","updated_at":"2026-05-07T19:22:17.612Z","avatar_url":"https://github.com/banesullivan.png","language":"Python","funding_links":["https://github.com/sponsors/banesullivan"],"categories":["Python","Software","Geospatial Library"],"sub_categories":["Visualization","Python"],"readme":"### 🚀 Support This Project\n\nIf localtileserver saves you time, powers your work, or you need direct help, please consider supporting the project and my efforts:\n\n[![Sponsor](https://img.shields.io/badge/Sponsor%20Bane%20Sullivan-🚀-green?style=for-the-badge)](https://github.com/sponsors/banesullivan)\n\n![tile-diagram](https://raw.githubusercontent.com/banesullivan/localtileserver/main/imgs/oam-tiles.jpg)\n\n# 🌐 Local Tile Server for Geospatial Rasters\n\n[![codecov](https://codecov.io/gh/banesullivan/localtileserver/branch/main/graph/badge.svg?token=S0HQ64FW8G)](https://codecov.io/gh/banesullivan/localtileserver)\n[![PyPI](https://img.shields.io/pypi/v/localtileserver.svg?logo=python\u0026logoColor=white)](https://pypi.org/project/localtileserver/)\n[![conda](https://img.shields.io/conda/vn/conda-forge/localtileserver.svg?logo=conda-forge\u0026logoColor=white)](https://anaconda.org/conda-forge/localtileserver)\n\n_Need to visualize a rather large (gigabytes+) raster?_ **This is for you.**\n\nA Python package for serving tiles from large raster files in\nthe [Slippy Maps standard](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)\n(i.e., `/zoom/x/y.png`) for visualization in Jupyter with `ipyleaflet` or `folium`.\n\nTry it live on MyBinder: [![MyBinder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/banesullivan/localtileserver/HEAD?labpath=examples/example.ipynb) (more demos in [`examples/`](examples/))\n\nDocumentation: https://localtileserver.banesullivan.com/\n\nBuilt on [rio-tiler](https://github.com/cogeotiff/rio-tiler) and [FastAPI](https://fastapi.tiangolo.com/)\n\n## 🌟 Highlights\n\n- Launch a tile server for large geospatial images\n- View local or remote raster files with `ipyleaflet` or `folium` in Jupyter\n- Band math expressions for on-the-fly computed imagery (e.g., NDVI)\n- Per-band statistics and multiple image stretch modes\n- Multiple output formats: PNG, JPEG, WebP, GeoTIFF, NPY\n- Spatial subsetting via bounding box crops and GeoJSON masks\n- [STAC](https://stacspec.org/) item support for multi-asset catalogs\n- [Xarray](https://xarray.dev/) DataArray tile serving (NetCDF, Zarr, etc.)\n- Virtual mosaics from multiple raster files\n- View rasters with CesiumJS with the built-in web application\n- Full REST API powered by FastAPI with auto-generated OpenAPI docs\n\n## 🚀 Usage\n\nUsage details and examples can be found in the documentation: https://localtileserver.banesullivan.com/\n\nThe following is a minimal example to visualize a local raster file with\n`ipyleaflet`:\n\n```py\nimport localtileserver as lts\nfrom ipyleaflet import Map\n\n# First, create a tile server from local raster file\nclient = lts.open('path/to/geo.tif')\n\n# Create ipyleaflet tile layer from that server\nt = lts.get_leaflet_tile_layer(client)\n\nm = Map(center=client.center(), zoom=client.default_zoom)\nm.add(t)\nm\n```\n\n![ipyleaflet](https://raw.githubusercontent.com/banesullivan/localtileserver/main/imgs/ipyleaflet.png)\n\n### Band Math Expressions\n\nCompute derived imagery on the fly using band math expressions:\n\n```py\nclient = lts.open('path/to/multispectral.tif')\n\n# NDVI: (NIR - Red) / (NIR + Red) where NIR=b4, Red=b1\nt = lts.get_leaflet_tile_layer(client, expression='(b4-b1)/(b4+b1)',\n                               vmin=-1, vmax=1, colormap='RdYlGn')\n```\n\n### STAC Support\n\nVisualize assets from STAC catalogs:\n\n```py\nimport requests\n\n# Fetch tiles from a STAC item's assets\nresp = requests.get('http://localhost:PORT/api/stac/tiles/10/512/512.png',\n                    params={'url': 'https://example.com/stac/item.json',\n                            'assets': 'visual'})\n```\n\n### Xarray DataArrays\n\nServe tiles directly from xarray DataArrays (NetCDF, Zarr, etc.):\n\n```py\nimport xarray as xr\n\nds = xr.open_dataset('temperature.nc')\nda = ds['temperature']\nda = da.rio.write_crs('EPSG:4326')\n\n# Register and serve tiles through the REST API\n```\n\n### VS Code, Colab, and other webview notebooks\n\n`localtileserver` works out of the box in JupyterLab, Notebook 7, JupyterHub,\nand Binder because those frontends let the browser reach the jupyter-server\norigin directly. VS Code Jupyter (including Remote-SSH), Google Colab, Shiny\nfor Python, Solara, and marimo render notebook outputs in a sandboxed webview\nwhose origin is **not** the jupyter-server — so root-relative tile URLs never\nreach the proxy, and `http://127.0.0.1:\u003cport\u003e/…` fails to resolve.\n\nTo cover those frontends, `localtileserver` integrates with\n[`jupyter-loopback`](https://github.com/banesullivan/jupyter-loopback). When\nyou call `get_leaflet_tile_layer(...)` or `get_folium_tile_layer(...)`, the\nhelper automatically routes that client's tile URLs through the comm bridge.\nNo install step or notebook changes required — `jupyter-loopback[comm]` is\npulled in by the core `pip install localtileserver`.\n\nIf you use a `TileClient` outside those helpers (e.g. embedding raw tile\nURLs in a custom HTML output), call the method explicitly:\n\n```py\nclient = lts.open('path/to/geo.tif')\nclient.enable_jupyter_loopback()\n```\n\nOr, for a specific port you're managing yourself:\n\n```py\nimport localtileserver\nlocaltileserver.enable_jupyter_loopback(port)\n```\n\nOpt out globally by setting `LOCALTILESERVER_DISABLE_JUPYTER_LOOPBACK=1` in\nyour environment before importing `localtileserver`.\n\n## ℹ️ Overview\n\nThe `TileClient` class can be used to launch a tile server in a background\nthread which will serve raster imagery to a viewer (usually `ipyleaflet` or\n`folium` in Jupyter notebooks).\n\nThis tile server can efficiently deliver varying resolutions of your\nraster imagery to your viewer; it helps to have pre-tiled,\n[Cloud Optimized GeoTIFFs (COGs)](https://www.cogeo.org/).\n\nThere is an included, standalone web viewer leveraging\n[CesiumJS](https://cesium.com/platform/cesiumjs/).\n\n### REST API\n\nThe server exposes a comprehensive REST API built on FastAPI:\n\n| Endpoint                                  | Description             |\n| ----------------------------------------- | ----------------------- |\n| `GET /api/tiles/{z}/{x}/{y}.{fmt}`        | Raster tiles            |\n| `GET /api/thumbnail.{fmt}`                | Thumbnail preview       |\n| `GET /api/metadata`                       | Raster metadata         |\n| `GET /api/bounds`                         | Geographic bounds       |\n| `GET /api/statistics`                     | Per-band statistics     |\n| `GET /api/part.{fmt}`                     | Bounding box crop       |\n| `POST /api/feature.{fmt}`                 | GeoJSON mask extraction |\n| `GET /api/stac/tiles/{z}/{x}/{y}.{fmt}`   | STAC item tiles         |\n| `GET /api/xarray/tiles/{z}/{x}/{y}.{fmt}` | Xarray DataArray tiles  |\n| `GET /api/mosaic/tiles/{z}/{x}/{y}.{fmt}` | Mosaic tiles            |\n| `GET /swagger/`                           | Interactive API docs    |\n\nAll tile/thumbnail endpoints support `expression`, `stretch`, `indexes`, `colormap`, `vmin`, `vmax`, and `nodata` query parameters.\n\n## ⬇️ Installation\n\nGet started with `localtileserver` to view rasters in Jupyter or deploy as your\nown FastAPI application.\n\n### 🐍 Installing with `conda`\n\nConda makes managing `localtileserver`'s dependencies across platforms quite\neasy and this is the recommended method to install:\n\n```bash\nconda install -c conda-forge localtileserver\n```\n\n### 🎡 Installing with `pip`\n\nIf you prefer pip, then you can install from PyPI: https://pypi.org/project/localtileserver/\n\n```\npip install localtileserver\n```\n\n### Optional Dependencies\n\nFor xarray/DataArray support:\n\n```\npip install localtileserver[xarray]\n```\n\nFor Jupyter widget integration:\n\n```\npip install localtileserver[jupyter]\n```\n\nFor additional colormaps:\n\n```\npip install localtileserver[colormaps]\n```\n\n## 💭 Feedback\n\nPlease share your thoughts and questions on the [Discussions](https://github.com/banesullivan/localtileserver/discussions) board.\nIf you would like to report any bugs or make feature requests, please open an issue.\n\nIf filing a bug report, please share a scooby `Report`:\n\n```py\nimport localtileserver as lts\nprint(lts.Report())\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbanesullivan%2Flocaltileserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbanesullivan%2Flocaltileserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbanesullivan%2Flocaltileserver/lists"}