{"id":48633458,"url":"https://github.com/nono303/kmlsuperoverlay","last_synced_at":"2026-04-09T06:09:54.443Z","repository":{"id":61177991,"uuid":"358577345","full_name":"nono303/kmlsuperoverlay","owner":"nono303","description":"A PHP gateway for displaying online map in Google Earth through kml","archived":false,"fork":false,"pushed_at":"2026-02-22T16:46:20.000Z","size":1860,"stargazers_count":8,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-22T21:32:34.645Z","etag":null,"topics":["gis","kml","map","overlay","php","wms","wmts"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nono303.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-04-16T11:30:29.000Z","updated_at":"2026-02-22T16:46:24.000Z","dependencies_parsed_at":"2024-01-01T09:52:20.926Z","dependency_job_id":"54fd3625-6c3e-4cbc-8b13-69bad5a59313","html_url":"https://github.com/nono303/kmlsuperoverlay","commit_stats":{"total_commits":49,"total_committers":3,"mean_commits":"16.333333333333332","dds":"0.30612244897959184","last_synced_commit":"4590fa24105cc2cf0e968acb8b22651bfc67c4a8"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nono303/kmlsuperoverlay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nono303%2Fkmlsuperoverlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nono303%2Fkmlsuperoverlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nono303%2Fkmlsuperoverlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nono303%2Fkmlsuperoverlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nono303","download_url":"https://codeload.github.com/nono303/kmlsuperoverlay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nono303%2Fkmlsuperoverlay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31588120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-09T05:33:47.836Z","status":"ssl_error","status_checked_at":"2026-04-09T05:32:26.579Z","response_time":112,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["gis","kml","map","overlay","php","wms","wmts"],"created_at":"2026-04-09T06:09:53.901Z","updated_at":"2026-04-09T06:09:54.436Z","avatar_url":"https://github.com/nono303.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"## A PHP gateway for displaying online map in Google Earth    \r\n\r\n\u003e **[Google Earth](https://www.google.com/intl/fr/earth/versions/)** is a super tool to discover earth but it only offers satellite imagery.   \r\n\u003e Online mapsources are consistent and mainly used in webpages, desktop clients and mobile apps so, why not in Google Earth?  \r\n\u003e **KmlSuperOverlay** is a simple PHP gateway that intends to meet this need :) Of course, it's not the unique one!  \r\n\u003e\r\n\u003e I used **[geos](https://github.com/grst/geos)** for a long time - An excellent all-in-one standalone tool but as I'm not a :snake: developer, I was not able to geek on it :(  \r\n\u003e Some \"heavy\" or complex **WSGI server** can also do that and some map providers, like [caltopo](https://training.caltopo.com/all_users/import-export/earth#super), do it for a fee. \r\n\u003e\r\n\u003e *See [credits](#credits) below for further informations.*  \r\n\r\n![](./.readme/ge2.png)  \r\n*French IGN topo over **Écrins***  \r\n![](./.readme/ge3.png)  \r\n*Swiss hiking paths \u0026 Strava run heatmap over **Arolla***\r\n\r\n### What kind of mapsources can I request?  \r\n\r\nYou can use every online map server that doesn't require specific referer or a 2 steps authentication - only url tokens is now supported.  \r\nAs you might know, there is no unique standard to request online tiles with some great complexity like the notorious EPSG!  \r\n\r\n**KmlSuperOverlay** support:  \r\n\r\n- **Tiled Web Map (TMS / WMTS)**  \r\n  - Slippy Map (Standard)s  \r\n  - Reverse Y  \r\n  - Quad Tree  \r\n- **Web Map Service (WMS)**   \r\n  - Version 1.0.0 to 1.3.0, from what I know...  \r\n  - EPSG 4326  \r\n  - EPSG 3857 and some alias - *currently not exhaustively implemented*  \r\n  - For other projections, I'm working on a transformation engine with [cs2cs](https://proj.org/apps/cs2cs.html) from [proj](https://proj.org) with good results on coordinates transformation but still have issues with re-projection...  \r\n### What are the benefits \u0026 features of this *wonderful* Gateway?  \r\n\r\n- Pure \u0026 simple PHP. No dependencies or composer modules.  \r\n- Fast or low memory footprint - *That's why I concatenate string rather than using simple_xml. Thanks not yelling at me ;)*  \r\n- Based on [Mobile Atlas Creator (mobac)](https://mobac.sourceforge.io/) and [GEOS](https://github.com/grst/geos) mapsource xml files.  \r\n### Pre-requisites  \r\n\r\n- #### PHP \u003e= 8 (_see [#1](https://github.com/nono303/kmlsuperoverlay/issues/1) for PHP7_) \r\n\r\n  - [tidy](https://www.php.net/manual/fr/book.tidy.php) extension for a better kml formating  (_optional_)  \r\n  - [zip](https://www.php.net/manual/fr/book.zip.php) extension for kmz support (_optional_)\r\n- #### httpd 2.4  \r\n  \r\n  - Will works with 2.0 or 2.2 just changing `Require` term in configuration  \r\n### So, how does it work? in fact, quite simply!  \r\n\r\n\u003e `/kmlsuperoverlay` will be the **\"how-to\" end-point** example  \r\n\r\n#### 1.  httpd : add this to your host or vhost config *(or .htaccess)*:  \r\n\r\n```  \r\nLoadModule rewrite_module ./modules/mod_rewrite.so  \r\n...  \r\n\u003cLocation /kmlsuperoverlay \u003e  \r\n  RewriteEngine on  \r\n  RewriteCond %{REQUEST_FILENAME} !index.php  \r\n  RewriteRule ^(.*)$ index.php?qs=$1 [L,QSA]  \r\n\u003c/Location\u003e  \r\n  \r\n\u003cLocation /kmlsuperoverlay/mapsources \u003e  \r\n  Require all denied  \r\n\u003c/Location\u003e  \r\n```\r\n\r\n#### 2.  php : (optional) enable tidy \u0026 zip  in php.ini  \r\n\r\n```  \r\nextension=tidy  \r\nextension=zip  \r\n```\r\n\r\n#### 3.  copy `/index.sample.php` to `/index.php` and configure it to fit your environment  \r\n\r\n```  \r\n// !! with ending '/'  \r\ndefine(\"MAP_SOURCE_ROOT\",\"./mapsources/\");  \r\n// !! with ending '/'  \r\ndefine(\"URL_BASE\",\"/kmlsuperoverlay/\");  \r\n```\r\n\r\n#### 4. Use it in Google Earth : add \u003e network link  \r\n\r\n![](./.readme/ge1.png)  \r\n\r\n:boom:**it works!**:boom:  \r\n\r\n#### 5. Tuning : `/class/KmlSuperOverlay.php`  \r\n\r\nAll the \"fine\" tuning might be done with the static vars of `KmlSuperOverlay` Class  \r\n\r\n- `worldBbox`: Default bounding box coordinates for region overlayed  \r\n- `tidyOptions` : Operation made by Tidy (if enabled) to prettify kml format  \r\n- `kmlformat`: Header, footer and styles for the generated kml file  \r\n- `lod`: [Level Of Detail](https://developers.google.com/kml/documentation/kmlreference#lod) configuration for groundOverlay (tiles) and networklink (kml)  \r\n  - Values are automatically overridden in case of:  \r\n    - `overlay == false OR current zoom value == mapsource maxZoom \u003e\u003e lod[\"groundOverlay\"][\"maxLodPixels\"]` **disabled**  \r\n    - `current zoom value == mapsource minZoom \u003e\u003e lod[\"groundOverlay\"][\"minLodPixels\"] \u0026\u0026 lod[\"networkLink\"][\"minLodPixels\"]` **disabled**   \r\n    - Current values are optimized for 256x256px tile size.  \r\n- `altitude`: Limit tile displaying between certain altitude point of view (0 = no limitation)  \r\n- `minZoom`: Set the minimum displayed zoom even if mapsource minZoom is lower than defined  \r\n- `displayRegion`: Enable or disable the display of a green rectangle representing the region if defined in mapsource.  \r\n- `debugHtml`: if set to true, display **kml** output in **html** for browser rendering only  \r\n- `outFormat`: `.kml` or `.kmz`. Default is `.kml`\r\n  - **kmz** need **zip** extension to be enabled and offer less bandwidth but more cpu usage  \r\n#### 6. Debug  \r\n\r\nJust end url with **`/debug`**, it's will set debug mode for all kml networklink.  \r\nCurrently just dumping performance metrics on description element of the kml document.  \r\nDebug output can be **html** or kml (_see above_). **kmz** is disabled, even if it's set as the default output format.  \r\n\r\nYou may have a look at [Google kml superoverlays reference page](https://developers.google.com/kml/documentation/kml_21tutorial#superoverlays) to interpret kml output  \r\n\r\n#### 7. Add mapsources  \r\n\u003e :point_up: If you are a **mobac** and/or **geos** user, you can simply define `MAP_SOURCE_ROOTs` as same as their map sources directory\r\n\u003e **KmlSuperOverlay** will only keep xml **customMapSource** - _excluding `xml` customMultiLayerMapSource and `bsh` BeanShell Script_\r\n\u003e _see [#305 issue on mobac](https://sourceforge.net/p/mobac/feature-requests/305/) for extra elements_\r\n\r\nI provided **as an example** few mapsources for each format and feature in `./mapsources`  \r\n**Please have a look on map providers general conditions of use before** and see [Resources](#Resources) to enlarge your collection ;)  \r\n\r\n- Full documentation about `customMapSource` is available on [geos website](https://geos.readthedocs.io/en/latest/users.html#more-maps)  \r\n\r\n  - \u003cbackgroundColor\u003e described on [mobac website](https://mobac.sourceforge.io/wiki/index.php/Custom_XML_Map_Sources#backgroundColor)  might be used to set **transparency** *(only last hex value is used)*\r\n- **transparent**: `#FFFFFF`**`00`** :warning: Tile will not be visible\r\n    - **50% transparency**: `#FFFFFF`**`80`**\r\n    \r\n- **opaque**: `#FFFFFF`**`FF`** *(default)*\r\n- I added:  \r\n  - \u003cserverParts\u003e described on [mobac website](https://mobac.sourceforge.io/wiki/index.php/Custom_XML_Map_Sources#serverParts)  \r\n  - \u003coverlay\u003e not documented as it's actually specific:  \r\n    Just add \u003coverlay\u003e`true`\u003c/overlay\u003e for tiles in PNG Alpha (transparency)   \r\n    it will change [Level Of Detail (lod)](https://developers.google.com/kml/documentation/regions#pixelrange) configuration to ensure that low zoomed tiles will not be visible and override the viewed ones\r\n#### 8. :warning: ​Beware!  \r\n\r\n- Be sure to encode your `customMapSource` xml files in **utf8**, otherwise they'll not appear in your list if it contains accented char `#frenchy`  \r\n### Credits  \r\n\r\n- **[@grst](https://github.com/grst)** for [geos](https://geos.readthedocs.io) - My main inspiration for this project.  \r\n- **[@r_x](https://sourceforge.net/u/r_x/profile/)** for [mobac](https://sourceforge.net/p/mobac/) - A \"must-have\" tool for all _GeekHiker_ like me ;)  \r\n- **@Nicolas.Paour** for [randochartreuse](http://randochartreuse.free.fr/) - The *\"good maths\"* for coordinates transformation.  \r\n### Resources  \r\n\r\n- **Other \"SuperOverlay\" tools**  \r\n  - [geos](https://github.com/grst/geos)  \r\n  - [MapServer](https://mapserver.org/id/input/vector/kml.html#example-3-displaying-a-superoverlay-kml-file)  \r\n  - [GeoServer](https://docs.geoserver.org/latest/en/user/services/wms/googleearth/features/kmlsuperoverlays.html)  \r\n  \r\n- **Map Servers list**  \r\n  - https://wiki.openstreetmap.org/wiki/Tile_servers  \r\n  - https://josm.openstreetmap.de/wiki/Maps#Listofsources  \r\n  - https://github.com/grst/mapsources  \r\n  - https://en.wikipedia.org/wiki/List_of_online_map_services  \r\n  - https://giswiki.hsr.ch/Hintergrundkarten  \r\n  - http://randochartreuse.free.fr/mobac2.x/mapsources/  \r\n  - https://dzjow.com/2012/04/12/free-online-topographic-maps-for-hiking/  \r\n  - https://osmlab.github.io/editor-layer-index/  \r\n  - https://www.randonner-leger.org/wiki/doku.php?id=cartographie_et_informations_pour_la_randonnee#cartes_glissantes_en_ligne  \r\n  - https://github.com/Ecotrust/madrona/blob/master/madrona/layer_manager/utils/proc_layers.py  \r\n  - https://projects.webvoss.de/2017/06/03/creating-the-perfect-hiking-map-for-germany-and-other-countries/  \r\n  - http://www.f-bmpl.com/index.php/faites-le-vous-meme/210-3-listing-des-serveurs-ortos  \r\n  - https://api.routeconverter.com/v1/mapservers/?format=xml  \r\n  - https://www.camptocamp.org/articles/676486/fr/cartes-topographiques-en-ligne  \r\n  - https://xyz.michelstuyts.be/  \r\n  - http://www.vttour.fr/articles/read_35.html  \r\n  - https://www.creazo.fr/listing-des-fonds-de-cartes-dopen-street-map/","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnono303%2Fkmlsuperoverlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnono303%2Fkmlsuperoverlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnono303%2Fkmlsuperoverlay/lists"}