{"id":13426249,"url":"https://github.com/w3reality/three-geo","last_synced_at":"2025-05-14T09:08:55.403Z","repository":{"id":37706571,"uuid":"147122360","full_name":"w3reality/three-geo","owner":"w3reality","description":"3D geographic visualization library","archived":false,"fork":false,"pushed_at":"2025-02-25T08:20:32.000Z","size":11739,"stargazers_count":1151,"open_issues_count":29,"forks_count":190,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-11T04:09:12.551Z","etag":null,"topics":["dataviz","gis","gps-coordinates","terrain","threejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/w3reality.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":"2018-09-02T21:14:13.000Z","updated_at":"2025-04-10T10:55:02.000Z","dependencies_parsed_at":"2023-02-12T00:00:58.633Z","dependency_job_id":"238d8364-a05b-4ac0-9b2e-0c7c7da33b3e","html_url":"https://github.com/w3reality/three-geo","commit_stats":{"total_commits":368,"total_committers":5,"mean_commits":73.6,"dds":0.09510869565217395,"last_synced_commit":"54dbec379dc1fc2d711898454ccb4e717544a15e"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3reality%2Fthree-geo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3reality%2Fthree-geo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3reality%2Fthree-geo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3reality%2Fthree-geo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/w3reality","download_url":"https://codeload.github.com/w3reality/three-geo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253592890,"owners_count":21932900,"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":["dataviz","gis","gps-coordinates","terrain","threejs"],"created_at":"2024-07-31T00:01:30.006Z","updated_at":"2025-05-14T09:08:50.389Z","avatar_url":"https://github.com/w3reality.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Front-end Framework","Javascript frontend frameworks and librairies"],"sub_categories":["Map display libraries"],"readme":"# three-geo\n\n[![NPM][npm-badge]][npm-url]\n[![MIT licensed][mit-badge]][mit-url]\n[![CI][actions-badge]][actions-url]\n\n[npm-badge]: https://img.shields.io/npm/v/three-geo.svg\n[npm-url]: https://www.npmjs.com/package/three-geo\n[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg\n[mit-url]: https://github.com/w3reality/three-geo/blob/master/LICENSE\n[actions-badge]: https://github.com/w3reality/three-geo/workflows/CI/badge.svg\n[actions-url]: https://github.com/w3reality/three-geo/actions\n\n**three-geo** is a [three.js](https://github.com/mrdoob/three.js) based geographic visualization library. Using three-geo, we can easily build satellite-textured 3D terrain models in near real-time by simply specifying GPS coordinates anywhere on the globe. The geometry of the terrain is based on the RGB-encoded DEM (Digital Elevation Model) provided by the Mapbox Maps API.\n\nThe terrain is represented by standard [THREE.Mesh](https://threejs.org/docs/#api/en/objects/Mesh) objects. This makes it easy for us to access underlying geometry/texture array and perform original GIS (Geographic Information System) experiments in JavaScript. (See Usage for how to programatically obtain those mesh objects).\n\nCredits: this library has been made possible thanks to\n\n- geo-related libraries ([mapbox](https://github.com/mapbox), [Turfjs](https://github.com/Turfjs/turf)) and [the Mapbox Maps API](https://www.mapbox.com/api-documentation/#maps).\n- [peterqliu](https://github.com/peterqliu) for informative 3D terrain-related articles and implementation.\n\n## Demo\n\n### 1) examples/geo-viewer ([live](https://w3reality.github.io/three-geo/examples/geo-viewer/io/index.html) | [source code](https://github.com/w3reality/three-geo/tree/master/examples/geo-viewer))\n\nThis demo app includes features such as\n\n- on-demand 3D terrain building (by a mouse click on the Leaflet map),\n- real-time camera projection onto Leaflet (with oritentaion and HFoV indication),\n- terrain interaction with a VR-like laser beam,\n- measuring Euclidean distances between terrain points,\n- auto camera orbiting around the custom z-axis.\n\nLive:\n\n- \u003chttps://w3reality.github.io/three-geo/examples/geo-viewer/io/index.html?lat=46.5763\u0026lng=7.9904\u003e\n\n  [![image](https://w3reality.github.io/three-geo/examples/img/5.jpg)](https://w3reality.github.io/three-geo/examples/geo-viewer/io/index.html?lat=46.5763\u0026lng=7.9904\u0026title=Eiger)\n\n- \u003chttps://w3reality.github.io/three-geo/examples/geo-viewer/io/index.html?lat=46.5763\u0026lng=7.9904\u0026mode=contours\u003e\n\n  [![image](https://w3reality.github.io/three-geo/examples/img/eiger-contours-100m.png)](https://w3reality.github.io/three-geo/examples/geo-viewer/io/index.html?lat=46.5763\u0026lng=7.9904\u0026mode=contours\u0026title=Eiger)\n\n- \u003chttps://w3reality.github.io/three-geo/examples/geo-viewer/io/index.html?lat=36.2058\u0026lng=-112.4413\u003e\n\n  [![image](https://w3reality.github.io/three-geo/examples/img/2.jpg)](https://w3reality.github.io/three-geo/examples/geo-viewer/io/index.html?lat=36.2058\u0026lng=-112.4413\u0026title=Colorado_River)\n\n### 2) examples/heightmaps ([live](https://w3reality.github.io/three-geo/examples/heightmaps/index.html) | [source code](https://github.com/w3reality/three-geo/tree/master/examples/heightmaps))\n\nThis demo illustrates the relationship between a reconstructed 3D terrain and its underlying satellite/DEM tiles.\n\n[![image](https://w3reality.github.io/three-geo/examples/img/heightmap-demo-2.jpg)](https://w3reality.github.io/three-geo/examples/heightmaps/index.html)\n\n### 3) examples/flat ([live](https://w3reality.github.io/three-geo/examples/flat/index.html) | [source code](https://github.com/w3reality/three-geo/tree/master/examples/flat/index.html))\n\nHow to get a flattened view of the terrain by post-editing the underlying geometry.\n\n### \u003ca name=\"ex-proj\"\u003e\u003c/a\u003e4) examples/projection ([live](https://w3reality.github.io/three-geo/examples/projection/index.html) | [source code](https://github.com/w3reality/three-geo/tree/master/examples/projection/index.html))\n\nHow to register a new 3D object on top of the terrain based on its geographic location `[latitude, longitude, elevation]`.\n\n## Setup\n\n**Installation**\n\n```\n$ npm i three-geo\n```\n\n**Loading**\n\nScript tag: use `ThreeGeo` after\n\n```\n\u003cscript src=\"dist/three-geo.min.js\"\u003e\u003c/script\u003e\n```\n\nES6:\n\n```\nimport ThreeGeo from 'dist/three-geo.esm.js';\n```\n\n## Usage\n\nHere is an example of how to build a geographic terrain located at GPS coordinates (46.5763, 7.9904) in a 5 km radius circle. The terrain's satellite zoom resolution is set to 12. (The highest zoom value supported is 17.)\n\nFor standalone tests, use **examples/simple-viewer** ([source code](https://github.com/w3reality/three-geo/tree/master/examples/simple-viewer)).\n\nFor use with NodeJS, do enable [this `isNode` option](#note-nodejs) as well.\n\n```js\nconst tgeo = new ThreeGeo({\n    tokenMapbox: '********', // \u003c---- set your Mapbox API token here\n});\n\nconst terrain = await tgeo.getTerrainRgb(\n    [46.5763, 7.9904], // [lat, lng]\n    5.0,               // radius of bounding circle (km)\n    12);               // zoom resolution\n\nconst scene = new THREE.Scene();\nscene.add(terrain);\n\nconst renderer = new THREE.WebGLRenderer({ canvas });\nrenderer.render(scene, camera);\n```\n\n[![image](https://w3reality.github.io/three-geo/examples/img/1.jpg)](https://w3reality.github.io/three-geo/examples/simple-viewer/index.html)\n\n## Who is using `three-geo`?\n\n- [jet-wasp](https://jet-wasp.glitch.me/) - Three-geo as A-Frame component ([source code](https://glitch.com/edit/#!/jet-wasp))\n- [locus-pocus](https://locus-pocus.io/) - A webapp to visualise your area using three-geo\n\n## API\n\nIn this section, we list `three-geo`'s public API methods, where `origin`, `radius`, and `zoom` are parameters common to them:\n\n  - `origin` **Array\\\u003cnumber\\\u003e** Center of the terrain represented as GPS coordinates `[latitude, longitude]`.\n\n  - `radius` **number** Radius of the circle that fits the terrain.\n\n  - `zoom` **number (integer)** Satellite zoom resolution of the tiles in the terrain. Select from {11, 12, 13, 14, 15, 16, 17}, where 17 is the highest value supported. For a fixed radius, higher zoom resolution results in more tileset API calls.\n\n\n`ThreeGeo`\n\n- `constructor(opts={})`\n\n  Create a ThreeGeo instance with parameters.\n\n  - `opts.tokenMapbox`=\\\"\\\" **string** Mapbox API token. This must be provided.\n\n  - `opts.unitsSide`=1.0 **number** The side length of the square that fits the terrain in WebGL space.\n\n  - `opts.isNode`=false **boolean** \u003ca name=\"note-nodejs\"\u003e\u003c/a\u003eTo use three-geo with NodeJS, you must explicitly set this option to `true`. [ Added in v1.4.5 ]\n\n- `async getTerrainRgb(origin, radius, zoom)` [ Added in v1.4 ]\n\n  Return a **THREE.Group** object that represents a 3D surface of the terrain.\n\n  The group object contains an **Array\\\u003cTHREE.Mesh\\\u003e** as `.children`. Each mesh corresponds to a partial geometry of the terrain textured with satellite images.\n\n- `async getTerrainVector(origin, radius, zoom)` [ Added in v1.4 ]\n\n  Return a **THREE.Group** object that represents a 3D contour map of the terrain.\n\n  The group object contains an **Array\\\u003cTHREE.Object3D\\\u003e** as `.children`. Each child object is either an extruded **THREE.Mesh** with `.name` attribute prefixed by `dem-vec-shade-\u003cele\u003e-`, or a **THREE.Line** with `.name` prefixed by `dem-vec-line-\u003cele\u003e-` (`\u003cele\u003e` is the height of each contour in meters).\n\n- `getProjection(origin, radius, unitsSide=1.0)` [ [Example](#ex-proj) ]\n\n  Return an object `{ proj, projInv, bbox, unitsPerMeter }` that includes transformation-related functions and parameters, where\n\n  - `proj(latlng)` is a function that maps geo coordinates `latlng` (an array `[lat, lng]`) to WebGL coordinates `[x, y]`.\n\n  - `projInv(x, y)` is a function that maps WebGL coordinates `[x, y]` to geo coordinates `[lat, lng]`.\n\n  - `bbox` is an array `[w, s, e, n]` that represents the computed bounding box of the terrain, where `w` (West) and `e` (East) are longitudinal limits; and `s` (South) and `n` (North) are latitudinal limits.\n\n  - `unitsPerMeter` is the length in WebGL-space per meter.\n\n\u003cp\u003e\u003cdetails\u003e\n\u003csummary\u003eLegacy callback based API\u003c/summary\u003e\n\n- `getTerrain(origin, radius, zoom, callbacks={})`\n\n  - `callbacks.onRgbDem` **function (meshes) {}** Implement this to request the geometry of the terrain. Called when the entire terrain\\'s geometry is obtained.\n\n    - `meshes` **Array\\\u003cTHREE.Mesh\\\u003e** All the meshes belonging to the terrain.\n\n  - `callbacks.onSatelliteMat` **function (mesh) {}** Implement this to request the satellite textures of the terrain. Called when the satellite texture of each mesh belonging to the terrain is obtained.\n\n    - `mesh` **THREE.Mesh** One of the meshes that's part of the terrain.\n\n  - `callbacks.onVectorDem` **function (objs) {}** Implement this to request the contour map of the terrain. Called when the contour map of the terrain is obtained.\n\n    - `objs` **Array\\\u003cTHREE.Object3D\\\u003e** Extruded meshes (**THREE.Mesh** objects with `.name` attribute prefixed by `dem-vec-shade-\u003cele\u003e-`) and lines (**THREE.Line** objects with `.name` attribute prefixed by `dem-vec-line-\u003cele\u003e-`), where `\u003cele\u003e` is the height of each contour in meters.\n\n\u003c/details\u003e\u003c/p\u003e\n\n## Build\n\nAfter `git clone` and `cd` to the repository,\n\n```\n$ npm i\n$ npm run build\n```\n\n### Building on Windows\n\nWhile `npm run build` on Windows is confirmed to work (via GitHub's [workflow with some tweaks](https://github.com/w3reality/three-geo/blob/b8775e3a3e2d6b815fd550a96f7f45e441ff54a2/.github/workflows/nodejs.yml#L30-L32)), for better results, it is recommended to use WSL2 instead (thanks [@sonicviz](https://github.com/sonicviz) for [reporting this](https://github.com/w3reality/three-geo/issues/44#issuecomment-1482906468)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3reality%2Fthree-geo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fw3reality%2Fthree-geo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3reality%2Fthree-geo/lists"}