{"id":49940755,"url":"https://github.com/jcubic/ascii-globe","last_synced_at":"2026-05-30T08:30:55.938Z","repository":{"id":355029751,"uuid":"1226475421","full_name":"jcubic/ascii-globe","owner":"jcubic","description":"Zero dependencies isomorphic ASCII-Art globe renderer in JavaScript","archived":false,"fork":false,"pushed_at":"2026-05-24T08:56:22.000Z","size":237,"stargazers_count":4,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-24T10:26:34.306Z","etag":null,"topics":["3d","animation","ascii","ascii-art","ascii-art-generator","cartography","globe"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/jcubic.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T12:55:50.000Z","updated_at":"2026-05-24T08:56:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jcubic/ascii-globe","commit_stats":null,"previous_names":["jcubic/ascii-globe"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/jcubic/ascii-globe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Fascii-globe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Fascii-globe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Fascii-globe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Fascii-globe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcubic","download_url":"https://codeload.github.com/jcubic/ascii-globe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcubic%2Fascii-globe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33686018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["3d","animation","ascii","ascii-art","ascii-art-generator","cartography","globe"],"created_at":"2026-05-17T11:00:24.493Z","updated_at":"2026-05-30T08:30:55.932Z","avatar_url":"https://github.com/jcubic.png","language":"TypeScript","funding_links":[],"categories":["JavaScript"],"sub_categories":["Isomorphic"],"readme":"# ![ASCII-Globe](https://github.com/jcubic/ascii-globe/blob/master/.github/logo.svg?raw=true)\n\n[![npm](https://img.shields.io/badge/npm-0.4.2-yellow.svg)](https://www.npmjs.com/package/ascii-globe)\n[![github repo](https://img.shields.io/badge/github-repo-orange?logo=github)](https://github.com/jcubic/ascii-globe)\n![NPM Downloads](https://img.shields.io/npm/dm/ascii-globe)\n[![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/ascii-globe)](https://www.jsdelivr.com/package/npm/ascii-globe)\n[![LICENSE MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jcubic/ascii-globe/blob/master/LICENSE)\n\nZero dependencies isomorphic ASCII-Art globe renderer in JavaScript.\n\nSee [Live Demo](https://codepen.io/jcubic/full/EaNaRVp)\n\n## Installation\n\n### npm\n\n```bash\nnpm install ascii-globe\n```\n\n### CDN\n\n```html\n\u003c!-- IIFE (global variable) --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/ascii-globe\"\u003e\u003c/script\u003e\n\n\u003c!-- ES Module --\u003e\n\u003cscript type=\"module\"\u003e\nimport Globe from 'https://esm.run/ascii-globe';\n\u003c/script\u003e\n```\n\n## Usage\n\n### ES Module (Node.js / Vite / bundlers)\n\n```javascript\nimport Globe from 'ascii-globe';\n\nconst globe = new Globe({ size: 1.4 });\nconsole.log(globe.render(90));\n```\n\n### CommonJS (Node.js)\n\n```javascript\nconst Globe = require('ascii-globe');\n\nconst globe = new Globe({ size: 1.4 });\nconsole.log(globe.render(90));\n```\n\n### Browser (script tag)\n\n```html\n\u003cpre id=\"output\"\u003e\u003c/pre\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/ascii-globe\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nvar globe = new Globe({ size: 1 });\ndocument.getElementById('output').textContent = globe.render(0);\n\u003c/script\u003e\n```\n\n### Browser (ES Module)\n\n```html\n\u003cpre id=\"output\"\u003e\u003c/pre\u003e\n\u003cscript type=\"module\"\u003e\nimport Globe from 'https://esm.run/ascii-globe';\n\nconst globe = new Globe({ size: 1 });\ndocument.getElementById('output').textContent = globe.render(0);\n\u003c/script\u003e\n```\n\n## API\n\n### `new Globe(options?)`\n\nCreates a new globe instance.\n\n| Option         | Type     | Default | Description                                         |\n|----------------|----------|---------|-----------------------------------------------------|\n| `size`         | `number` | `1.4`   | Scale factor. `1` produces a 120x60 character grid. |\n| `map`          | `string` | —       | Base64-encoded map data. Defaults to the built-in Earth map. |\n| `land`         | `string` | `'#'`   | Character used to render land masses.               |\n| `water`        | `string` | `'-'`   | Character used to render water/ocean.               |\n| `background`   | `string` | `' '`   | Character used for the area outside the globe disk. |\n| `margin`       | `number` | `0`     | Number of characters around the globe disk.         |\n| `marginBlock`  | `number` | `0`     | Vertical margin (overrides `margin`).               |\n| `marginInline` | `number` | `0`     | Horizontal margin (overrides `margin`).             |\n| `pin`          | `string` | `'@'`   | Default character for location pins. Can include ANSI escape codes. |\n| `pinSize`      | `number` | `1`     | Default size multiplier for pin markers.            |\n| `pins`         | `Pin[]`  | `[]`    | Array of pin locations.                             |\n| `tilt`         | `number` | `0`     | Axial tilt in degrees (Earth's tilt is 23.5°).      |\n| `speed`        | `number` | `0.7`   | Rotation speed in degrees per frame.                |\n| `format`       | `function` | —     | Callback `(type, length) =\u003e string` for custom output (see below). |\n\n#### Pin object\n\n| Property | Type     | Required | Description                                                        |\n|----------|----------|----------|--------------------------------------------------------------------|\n| `lat`    | `number` | yes      | Latitude in degrees (-90 to 90).                                   |\n| `long`   | `number` | yes      | Longitude in degrees (-180 to 180).                                |\n| `char`   | `string` | no       | Override character for this pin. Can include ANSI escape codes.    |\n| `size`   | `number` | no       | Size multiplier for this pin (overrides `pinSize`).                |\n\n#### `format(type, length)`\n\nWhen provided, `render()` calls this function for each run of consecutive cells of the same type instead of using the `land`/`water`/`background`/`pin` characters. This lets you wrap output in HTML tags, ANSI codes, or any other markup.\n\n| Type value | Meaning    |\n|------------|------------|\n| `0`        | Background |\n| `1`        | Water      |\n| `2`        | Land       |\n| `3+`       | Pin (index `type - 3` in the `pins` array) |\n\nExample — HTML colored output:\n\n```javascript\nconst globe = new Globe({\n  size: 1,\n  pins: [{ lat: 52.23, long: 21.01 }],\n  format(type, length) {\n    const chars = [' ', ' ', '#', '@'];\n    const colors = ['', '', 'green', 'red'];\n    const text = chars[type].repeat(length);\n    if (!colors[type]) return text;\n    return `\u003cspan style=\"color:${colors[type]}\"\u003e${text}\u003c/span\u003e`;\n  }\n});\n\npre.innerHTML = globe.render(250);\n```\n\n#### Custom maps\n\nThe library ships with an Earth map by default, but you can use a different map by passing\nthe `map` option. The package includes a built-in Death Star map:\n\n```javascript\nimport Globe from 'ascii-globe';\nimport deathStar from 'ascii-globe/maps/death-star';\n\nconst globe = new Globe({ map: deathStar, land: '#', water: ' ' });\nconsole.log(globe.render(0));\n```\n\nWith a script tag (no modules), load the map as a separate script. The load order doesn't matter:\n\n```html\n\u003cpre id=\"output\"\u003e\u003c/pre\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/ascii-globe\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/ascii-globe/dist/maps/death-star.global.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nvar globe = new Globe({ map: Globe.maps['death-star'], land: '#', water: ' ' });\ndocument.getElementById('output').textContent = globe.render(0);\n\u003c/script\u003e\n```\n\nYou can also generate your own map data from any equirectangular projection image\n(see [Generating custom map data](#generating-custom-map-data) below).\n\n### `globe.render(rotation)`\n\nReturns a string with the ASCII globe rendered at the given rotation.\n\n- `rotation` — a single number (horizontal angle in degrees) or a `[horizontal, vertical]` pair. Values wrap around automatically.\n\n```javascript\nglobe.render(90);       // horizontal rotation only\nglobe.render([90, 30]); // horizontal + vertical tilt\n```\n\n## CLI\n\n```bash\nnpx ascii-globe --rotation 200\nnpx ascii-globe --animate\n```\n\nOr install globally:\n\n```bash\nnpm install -g ascii-globe\nglobe --rotation 200\nglobe --animate\n```\n\n```\nASCII Globe v0.4.2 - Isomorphic ASCII globe renderer\n\nUsage: globe \u003c--rotation \u003cdegrees\u003e | --animate\u003e [options]\n\nOptions:\n  --rotation \u003cdegrees\u003e  Rotation angle (single number or h,v pair)\n  --animate             Animate the globe in the terminal\n  --size \u003cnumber\u003e       Globe size multiplier (default: 1.4)\n  --map \u003cfile\u003e          Path to a map data file (generated by extract-texture)\n  --land \u003cchar\u003e         Character for land (default: #)\n  --water \u003cchar\u003e        Character for water (default: -)\n  --background \u003cchar\u003e   Character for background (default: \" \")\n  --margin \u003cnumber\u003e     Characters around the globe (default: 0)\n  --margin-block \u003cn\u003e    Vertical margin (overrides --margin)\n  --margin-inline \u003cn\u003e   Horizontal margin (overrides --margin)\n  --pin \u003cchar\u003e          Character for location pins (default: @)\n  --pin-size \u003cnumber\u003e   Size of pin markers (default: 1)\n  --pins \u003ccoords\u003e       Pin locations as lat,long pairs separated by ;\n  --tilt \u003cdegrees\u003e      Axial tilt in degrees (default: 0)\n  --speed \u003cnumber\u003e      Rotation speed in degrees per frame (default: 0.7)\n  --help                Show this help message\n  -v, --version         Show version number\n\nEither --rotation or --animate is required.\n```\n\nExample with pins (Warsaw and New York):\n\n```bash\nglobe --rotation 250 --pins '52.23,21.01;40.71,-74.01'\nglobe --rotation 250 --pin '\\x1b[31m@\\x1b[m' --pins '52.23,21.01'\n```\n\nExample with a custom map:\n\n```bash\nglobe --rotation 40,20 --map ./my-map.js --land '#' --water ' '\n```\n\n## Examples\n\n### Node.js terminal animation\n\n```javascript\nimport Globe from 'ascii-globe';\n\nconst globe = new Globe({ size: 1, land: '#', water: ' ', tilt: 23.5 });\n\nlet rotation = 0;\n\nprocess.stdout.write('\\x1B[?25l'); // hide cursor\n\nsetInterval(() =\u003e {\n  process.stdout.write('\\x1B[2J\\x1B[H'); // clear + home\n  process.stdout.write(globe.render(rotation));\n  rotation = (rotation + globe.speed) % 360;\n}, 1000 / 30);\n```\n\nRun the included example:\n\n```bash\nnpm run example:node\n```\n\n### Browser animation\n\n```html\n\u003cpre id=\"globe\"\u003e\u003c/pre\u003e\n\u003cbutton id=\"toggle\"\u003ePause\u003c/button\u003e\n\u003cinput id=\"rotation\" type=\"number\" min=\"0\" max=\"360\" step=\"0.1\" value=\"0\" disabled\u003e\n\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/ascii-globe\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nvar globe = new Globe({ size: 1, land: '#', water: ' ' });\nvar pre = document.getElementById('globe');\nvar playing = true;\nvar rotation = 0;\n\nfunction loop() {\n  pre.textContent = globe.render(rotation);\n  if (playing) {\n    rotation = (rotation + 0.7) % 360;\n    requestAnimationFrame(loop);\n  }\n}\n\ndocument.getElementById('toggle').addEventListener('click', function() {\n  playing = !playing;\n  if (playing) loop();\n});\n\nloop();\n\u003c/script\u003e\n```\n\nOpen `examples/browser/index.html` via a local server to run the included browser demo.\n\n## Generating custom map data\n\nYou can generate map data from any equirectangular projection image (2:1 aspect ratio PNG).\nThe extract script is included in the repository:\n\n```bash\nnpx tsx scripts/extract-texture.ts \u003cimage.png\u003e --output \u003coutput.ts\u003e\n```\n\nOptions:\n\n| Flag           | Description                                              |\n|----------------|----------------------------------------------------------|\n| `--output \u003cpath\u003e` | Output file path (default: `src/maps/\u003cname\u003e.ts`)      |\n| `--grayscale`  | Use brightness instead of Earth-specific color detection |\n| `--alpha`      | Use the alpha channel as the mask (opaque = land)        |\n| `--invert`     | Invert the mask (swap land and water)                    |\n\nThe default mode classifies pixels using Earth-specific color heuristics (blue → water,\ndark → land). Use `--grayscale` or `--alpha` for non-Earth images.\n\nThe output file can be imported and passed to the `map` option:\n\n```javascript\nimport Globe from 'ascii-globe';\nimport myMap from './my-map.ts';\n\nconst globe = new Globe({ map: myMap });\n```\n\nOr used with the CLI:\n\n```bash\nglobe --rotation 90 --map ./my-map.ts\n```\n\n## Building from source\n\n```bash\nnpm install\nnpm run extract   # generate src/maps/ from globe.png and death-star.png\nnpm run build     # compile TypeScript to dist/\n```\n\n## Acknowledgments\n\nWorld map texture by Ebrahim; [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0); source [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Equirectangular_projection_world_map_without_borders.svg).\n\n## License\n\nCopyright (c) 2025 [Jakub T. Jankiewicz](https://jakub.jankiewicz.org/)\n\nReleased under the MIT License. See [LICENSE](https://github.com/jcubic/ascii-globe/blob/master/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcubic%2Fascii-globe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcubic%2Fascii-globe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcubic%2Fascii-globe/lists"}