{"id":25483708,"url":"https://github.com/rahatool/s2-geometry","last_synced_at":"2025-11-07T07:30:22.784Z","repository":{"id":243117352,"uuid":"811464856","full_name":"rahatool/s2-geometry","owner":"rahatool","description":"A native JavaScript port of Google's S2 Geometry library","archived":false,"fork":false,"pushed_at":"2024-06-06T19:49:01.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"development","last_synced_at":"2024-06-06T20:50:41.067Z","etag":null,"topics":["coordinates","distance","geo-location","geo-query","geocode","geohash","geometry","k-nn","nearby","position","proximity","realtime","s2-geometry","spatial-index"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/rahatool.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}},"created_at":"2024-06-06T16:40:59.000Z","updated_at":"2024-06-06T20:50:44.317Z","dependencies_parsed_at":"2024-06-06T21:08:20.641Z","dependency_job_id":null,"html_url":"https://github.com/rahatool/s2-geometry","commit_stats":null,"previous_names":["rahatool/s2-geometry"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahatool%2Fs2-geometry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahatool%2Fs2-geometry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahatool%2Fs2-geometry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahatool%2Fs2-geometry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rahatool","download_url":"https://codeload.github.com/rahatool/s2-geometry/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239520927,"owners_count":19652780,"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":["coordinates","distance","geo-location","geo-query","geocode","geohash","geometry","k-nn","nearby","position","proximity","realtime","s2-geometry","spatial-index"],"created_at":"2025-02-18T17:47:41.185Z","updated_at":"2025-11-07T07:30:22.741Z","avatar_url":"https://github.com/rahatool.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Geometry on the Sphere - JavaScript Library\nA native JavaScript port of Google's S2 Geometry library for dealing with spatial data.\n\n---\nThe S2 Geometry is based on projecting the earth sphere onto a cube, with some scaling of face coordinates to keep things close to approximate equal area for adjacent cells.\n\nTo convert lat,lng to a cell id:\n- convert lat,lng to x,y,z\n- convert x,y,z to face,u,v\n- u,v scaled to s,t with quadratic formula\n- s,t converted to integer i,j offsets\n- i,j converted to a position along a Hilbert space-filling curve\n- combine face,position to get the cell id\n\n![Hierarchy of S2 Geometry](https://s2geometry.io/devguide/img/s2hierarchy.gif)\n\n# Installation\n## CDN\nImport library from the ESM.SH CDN for fast and easy setup:\n### In web browser\nSimply include s2-geometry in your html `\u003cheader\u003e` tag.\n```html\n\u003cscript type=\"module\"\u003e\nimport {S2LatLng, S2Cell} from \"//esm.sh/gh/rahatool/s2-geometry\";\n\u003c/script\u003e\n```\n### In web worker\nSome s2-geometry functions that do not access nor modify the DOM can be used in web workers.\n\nIn order to be able to use s2-geometry in those web workers, you need to import the source file as an ES6 module using:\n```javascript\nimport {S2LatLng, S2Cell} from \"//esm.sh/gh/rahatool/s2-geometry\";\n```\n## NPM registry\nUse the package manager npm to install s2-geometry.\n```shell\n$ npm install github:rahatool/s2-geometry\n```\nLibrary will be copied to `node_modules/@raha.group/s2-geometry` directory.\n## Direct Download\nGrab the [latest release](/archive/refs/heads/development.zip) file.\n\n# Implemented APIs\n\n## S2LatLng API\n\n### Skeleton of S2LatLng\n```javascript\nS2LatLng := ObjectModel {\n\t@Static S2LatLng from(Number latitude, Number longitude);\n\t@Static S2LatLng fromInteger(BigInt identifier);\n\tBigInt toInteger(Level level = MAX_LEVEL);\n\tSequenceOf(S2Cell) getNeighbors(level);\n\tBigInt compareTo(S2LatLng other);\n};\nLevel := RangeLimit\u003cNumber\u003e {\n\tlower := 1,\n\tupper := 30\n};\nMAX_LEVEL := 30;\n```\n\n### Usage of S2LatLng\n```javascript\nlet latitude = 40.2574448;\nlet longitude = -111.7089464;\n// Main factory method to create a S2LatLng object from pair (latitude, longitude)\nlet point = S2LatLng.from(latitude, longitude);\n\nlet level = 15; // Range of level is between 1 and 30\nlet cellId = point.toInteger(level);\nconsole.log(cellId);\n// It prints 9749618446378729472n\n\n// Factory method to create a S2LatLng object from BigInt\npoint = S2LatLng.fromInteger(cellId);\nconsole.log(point);\n// It prints {lat: 40.2574448, lng: -111.7089464}\n\nfor (let cell of point.getNeighbors(level)) {\n\tconsole.log(cell);\n}\n```\n\n## S2Cell API\nCurrently contains basic support for S2Cell.\n\n\u003ctable\u003e\n\t\u003ccaption\u003eMap of Faces\u003c/caption\u003e\n\t\u003ctr\u003e\u003ctd\u003e\u003c/td\u003e\u003ctd\u003eFace: 2\u003cbr /\u003eOrientation: A\u003cbr /\u003eCover: Africa\u003c/td\u003e\u003ctd colspan=\"2\"\u003e\u003c/td\u003e\u003c/tr\u003e\n\t\u003ctr\u003e\u003ctd\u003eFace: 0\u003cbr /\u003eOrientation: A\u003cbr /\u003eCover: Africa\u003c/td\u003e\u003ctd\u003eFace: 1\u003cbr /\u003eOrientation: D\u003cbr /\u003eCover: Asia\u003c/td\u003e\u003ctd\u003eFace: 3\u003cbr /\u003eOrientation: D\u003cbr /\u003eCover: Australia\u003c/td\u003e\u003ctd\u003eFace: 4\u003cbr /\u003eOrientation: A\u003cbr /\u003eCover: Americas, Provo, UT\u003c/td\u003e\u003c/tr\u003e\n\t\u003ctr\u003e\u003ctd colspan=\"3\"\u003e\u003c/td\u003e\u003ctd\u003eFace: 5\u003cbr /\u003eOrientation: D\u003cbr /\u003eCover: Antarctica\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\nThe S2 hierarchy is useful for spatial indexing and for approximating regions as a collection of cells. Cells can be used to represent both points and regions: points are generally represented as leaf cells, while regions are represented as collections of cells at any level(s).\n\nEach cell is uniquely identified by a 64-bit S2CellId. The S2 cells are numbered in a special way in order to maximize locality of reference when they are used for spatial indexing (compared to other methods of numbering the cells).\n\nS2CellId combine face and the hilbert curve position into a single 64 bit integer. this gives efficient space and speed.\n\n### Skeleton of S2Cell\n```javascript\nS2Cell := ObjectModel {\n\t@Static from(Face face, OrderedPair ij, Level level = MAX_LEVEL); // Internal use\n\t\n\t@Static S2Cell fromLatLng(S2LatLng latLng, Level level = MAX_LEVEL);\n\tS2LatLng toLatLng();\n\n\t@Static S2Cell fromInteger(BigInt identifier);\n\tBigInt toInteger();\n\t\n\tSequenceOf(S2LatLng) getCornerLatLngs();\n\tSequenceOf(S2Cell) getNeighbors();\n\tS2Cell move(Number step);\n\n\tBoolean includes(S2LatLng point);\n\tBoolean includes(S2Cell cell);\n\tBigInt compareTo(S2Cell other);\n};\nFace := RangeLimit\u003cNumber\u003e {\n\tlower := 0,\n\tupper := 5\n};\n```\n\n### Usage of S2Cell\n```javascript\n// Factory method to create a S2Cell object from S2LatLng and level\nlet cell = S2Cell.fromLatLng(point, level);\nconsole.log(cell.toLatLng().compareTo(point) == 0n);\n// It prints true\n\n// Factory method to create a S2Cell object from BigInt\ncell = S2Cell.fromInteger(cellId);\nconsole.log(cell.toInteger() == point.toInteger());\n// It prints true\n\nfor (let cell of point.getNeighbors()) {\n\tconsole.log(cell);\n}\n// It prints the neighbors from left, down, right and up.\n\n// You can get the previous and next S2Cell from any given cell:\nlet nextCell = cell.move(1);\nlet previousCell = cell.move(-1);\n\n// Does cell include other item?\nconsole.log(cell.includes(point));\n```\n\n# Supported platforms\nRaha S2-geometry has been tested and works on the following engines:\n- Node.js 10.4+\n- Chrome (desktop \u0026 Android) 67+\n- Firefox 68+\n- Safari 14+ (desktop \u0026 iOS)\n- Latest version of other web-browsers\n\n# License\nS2-geometry by [Raha Group](//raha.group) is licensed under the [CC-BY-SA-4.0 License](//creativecommons.org/licenses/by-sa/4.0/).\n\n# Resources\n- [S2 Geometry Library](//s2geometry.io/)\n- [S2Cell Hierarchy](//s2geometry.io/devguide/s2cell_hierarchy)\n- [Presentation of Google's S2 Library](//docs.google.com/presentation/d/1Hl4KapfAENAOf4gv-pSngKwvS_jwNVHRPZTTDzXXn6Q)\n- [Spatial indexing with Quadtrees and Hilbert Curves](//blog.notdot.net/2009/11/Damn-Cool-Algorithms-Spatial-indexing-with-Quadtrees-and-Hilbert-Curves)\n\n# Alternative projects\n- [coolaj86 / s2-geometry.js](//git.coolaj86.com/coolaj86/s2-geometry.js)\n- [Node S2Geometry Typescript](//github.com/vekexasia/nodes2-ts/)\n\n# Stay connected\nStay in touch with Raha’s community and keep track of development and community news by subscribing to the Raha’s [Blog](//raha.group) and [YouTube channel](//youtube.com/channel/UC0bWOBL-vMPCwT6nI9Cz1yw).\n\n## Documentation\nThe official docs are a great place to discover new things.\n\n## Issue Tracker\nAre you experiencing problems with Raha? [report issues](//groups.google.com/d/forum/rahagroup) and find solutions to your problems here. \n\n## Feature Request\nYou are always welcome to ask for more features to be added to Raha.\n\n## Events\nStay up to date with meetups, conferences and more.\n\n## Support\nLooking for help? please first check out the official (mentioned above) and unofficial (e.g. [Stack Overflow](//stackoverflow.com/questions/tagged/raha)) resources. If you are still experiencing problems, feel free to create a new issue.\n\n# Donation\nIf you'd like Raha to grow even stronger, please become a sponsor today by donating via Paypal [![Donate][paypal-image]][paypal-url] *(Farnood)* to support Raha's ongoing maintenance and development of new functionality.\n\n[paypal-image]: https://img.shields.io/badge/paypal-donate-brightgreen.svg\n[paypal-url]: //paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=RZC8HCR5SPGQY\u0026item_name=Contribute+to+Raha%27s+ongoing+maintenance+and+development\u0026currency_code=USD\u0026source=url","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahatool%2Fs2-geometry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frahatool%2Fs2-geometry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahatool%2Fs2-geometry/lists"}