Zero dependencies isomorphic ASCII-Art globe renderer in JavaScript.

See Live Demo

Installation

npm

npm install ascii-globe

CDN

<!-- IIFE (global variable) -->
<script src="https://cdn.jsdelivr.net/npm/ascii-globe"></script>

<!-- ES Module -->
<script type="module">
import Globe from 'https://esm.run/ascii-globe';
</script>

Usage

ES Module (Node.js / Vite / bundlers)

import Globe from 'ascii-globe';

const globe = new Globe({ size: 1.4 });
console.log(globe.render(90));

CommonJS (Node.js)

const Globe = require('ascii-globe');

const globe = new Globe({ size: 1.4 });
console.log(globe.render(90));

Browser (script tag)

<pre id="output"></pre>
<script src="https://cdn.jsdelivr.net/npm/ascii-globe"></script>
<script>
var globe = new Globe({ size: 1 });
document.getElementById('output').textContent = globe.render(0);
</script>

Browser (ES Module)

<pre id="output"></pre>
<script type="module">
import Globe from 'https://esm.run/ascii-globe';

const globe = new Globe({ size: 1 });
document.getElementById('output').textContent = globe.render(0);
</script>

API

new Globe(options?)

Creates a new globe instance.

Option	Type	Default	Description
size	number	1.4	Scale factor. 1 produces a 120x60 character grid.
map	string	—	Base64-encoded map data. Defaults to the built-in Earth map.
land	string	'#'	Character used to render land masses.
water	string	'-'	Character used to render water/ocean.
background	string	' '	Character used for the area outside the globe disk.
margin	number	0	Number of characters around the globe disk.
marginBlock	number	0	Vertical margin (overrides margin).
marginInline	number	0	Horizontal margin (overrides margin).
pin	string	'@'	Default character for location pins. Can include ANSI escape codes.
pinSize	number	1	Default size multiplier for pin markers.
pins	Pin[]	[]	Array of pin locations.
tilt	number	0	Axial tilt in degrees (Earth's tilt is 23.5°).
speed	number	0.7	Rotation speed in degrees per frame.
format	function

Pin object

Property	Type	Required	Description
lat	number	yes	Latitude in degrees (-90 to 90).
long	number	yes	Longitude in degrees (-180 to 180).
char	string	no	Override character for this pin. Can include ANSI escape codes.
size	number	no	Size multiplier for this pin (overrides pinSize).

format(type, length)

When 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.

Type value	Meaning
0	Background
1	Water
2	Land
3+	Pin (index type - 3 in the pins array)

Example — HTML colored output:

const globe = new Globe({
  size: 1,
  pins: [{ lat: 52.23, long: 21.01 }],
  format(type, length) {
    const chars = [' ', ' ', '#', '@'];
    const colors = ['', '', 'green', 'red'];
    const text = chars[type].repeat(length);
    if (!colors[type]) return text;
    return `<span style="color:${colors[type]}">${text}</span>`;
  }
});

pre.innerHTML = globe.render(250);

Custom maps

The library ships with an Earth map by default, but you can use a different map by passing the map option. The package includes a built-in Death Star map:

import Globe from 'ascii-globe';
import deathStar from 'ascii-globe/maps/death-star';

const globe = new Globe({ map: deathStar, land: '#', water: ' ' });
console.log(globe.render(0));

With a script tag (no modules), load the map as a separate script. The load order doesn't matter:

<pre id="output"></pre>
<script src="https://cdn.jsdelivr.net/npm/ascii-globe"></script>
<script src="https://cdn.jsdelivr.net/npm/ascii-globe/dist/maps/death-star.global.js"></script>
<script>
var globe = new Globe({ map: Globe.maps['death-star'], land: '#', water: ' ' });
document.getElementById('output').textContent = globe.render(0);
</script>

You can also generate your own map data from any equirectangular projection image (see Generating custom map data below).

globe.render(rotation)

Returns a string with the ASCII globe rendered at the given rotation.

• rotation — a single number (horizontal angle in degrees) or a [horizontal, vertical] pair. Values wrap around automatically.

globe.render(90);       // horizontal rotation only
globe.render([90, 30]); // horizontal + vertical tilt

CLI

npx ascii-globe --rotation 200
npx ascii-globe --animate

Or install globally:

npm install -g ascii-globe
globe --rotation 200
globe --animate

ASCII Globe v0.4.2 - Isomorphic ASCII globe renderer

Usage: globe <--rotation <degrees> | --animate> [options]

Options:
  --rotation <degrees>  Rotation angle (single number or h,v pair)
  --animate             Animate the globe in the terminal
  --size <number>       Globe size multiplier (default: 1.4)
  --map <file>          Path to a map data file (generated by extract-texture)
  --land <char>         Character for land (default: #)
  --water <char>        Character for water (default: -)
  --background <char>   Character for background (default: " ")
  --margin <number>     Characters around the globe (default: 0)
  --margin-block <n>    Vertical margin (overrides --margin)
  --margin-inline <n>   Horizontal margin (overrides --margin)
  --pin <char>          Character for location pins (default: @)
  --pin-size <number>   Size of pin markers (default: 1)
  --pins <coords>       Pin locations as lat,long pairs separated by ;
  --tilt <degrees>      Axial tilt in degrees (default: 0)
  --speed <number>      Rotation speed in degrees per frame (default: 0.7)
  --help                Show this help message
  -v, --version         Show version number

Either --rotation or --animate is required.

Example with pins (Warsaw and New York):

globe --rotation 250 --pins '52.23,21.01;40.71,-74.01'
globe --rotation 250 --pin '\x1b[31m@\x1b[m' --pins '52.23,21.01'

Example with a custom map:

globe --rotation 40,20 --map ./my-map.js --land '#' --water ' '

Examples

Node.js terminal animation

import Globe from 'ascii-globe';

const globe = new Globe({ size: 1, land: '#', water: ' ', tilt: 23.5 });

let rotation = 0;

process.stdout.write('\x1B[?25l'); // hide cursor

setInterval(() => {
  process.stdout.write('\x1B[2J\x1B[H'); // clear + home
  process.stdout.write(globe.render(rotation));
  rotation = (rotation + globe.speed) % 360;
}, 1000 / 30);

Run the included example:

npm run example:node

Browser animation

<pre id="globe"></pre>
<button id="toggle">Pause</button>
<input id="rotation" type="number" min="0" max="360" step="0.1" value="0" disabled>

<script src="https://cdn.jsdelivr.net/npm/ascii-globe"></script>
<script>
var globe = new Globe({ size: 1, land: '#', water: ' ' });
var pre = document.getElementById('globe');
var playing = true;
var rotation = 0;

function loop() {
  pre.textContent = globe.render(rotation);
  if (playing) {
    rotation = (rotation + 0.7) % 360;
    requestAnimationFrame(loop);
  }
}

document.getElementById('toggle').addEventListener('click', function() {
  playing = !playing;
  if (playing) loop();
});

loop();
</script>

Open examples/browser/index.html via a local server to run the included browser demo.

Generating custom map data

You can generate map data from any equirectangular projection image (2:1 aspect ratio PNG). The extract script is included in the repository:

npx tsx scripts/extract-texture.ts <image.png> --output <output.ts>

Options:

Flag	Description
--output <path>	Output file path (default: src/maps/<name>.ts)
--grayscale	Use brightness instead of Earth-specific color detection
--alpha	Use the alpha channel as the mask (opaque = land)
--invert	Invert the mask (swap land and water)

The default mode classifies pixels using Earth-specific color heuristics (blue → water, dark → land). Use --grayscale or --alpha for non-Earth images.

The output file can be imported and passed to the map option:

import Globe from 'ascii-globe';
import myMap from './my-map.ts';

const globe = new Globe({ map: myMap });

Or used with the CLI:

globe --rotation 90 --map ./my-map.ts

Building from source

npm install
npm run extract   # generate src/maps/ from globe.png and death-star.png
npm run build     # compile TypeScript to dist/

License

Copyright (c) 2026 Jakub T. Jankiewicz

Released under the MIT License. See LICENSE for details.