explaingit

rastapasta/mapscii

9,112JavaScriptAudience · developerComplexity · 2/5Setup · easy

TLDR

A terminal app that renders a zoomable, pannable world map using OpenStreetMap data drawn with Braille and ASCII characters, with no installation needed to try it via telnet.

Mindmap

mindmap
  root((MapSCII))
    What it does
      World map in terminal
      OpenStreetMap data
      Pan and zoom controls
    Rendering
      Braille characters
      ASCII block mode
      Mouse drag support
    Use Cases
      Terminal map browsing
      Custom tile servers
      Offline map viewing
    Setup
      npx or npm install
      Telnet public demo
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Browse and navigate a world map entirely in the terminal using keyboard arrow keys or mouse scroll.

USE CASE 2

Connect to a custom or private tile server to display your own geographic data in ASCII in the terminal.

USE CASE 3

Try it instantly with no installation by connecting to the public demo server via telnet.

Tech stack

JavaScriptNode.js

Getting it running

Difficulty · easy Time to first run · 5min
The explanation does not specify the license terms.

In plain English

MapSCII renders a world map directly inside your terminal window, using Braille and ASCII characters to draw geography at surprisingly fine detail. You can scroll around, zoom in and out, and explore points of interest, all without leaving the command line. The quickest way to try it is to connect via telnet to a public server the project maintains, with no installation required. Map data comes from OpenStreetMap, the community-maintained open map of the world. MapSCII fetches vector tiles, which are compact geographic data files, and converts them into characters your terminal can display. It supports Mapbox style files for visual customization, and it can connect to any public or private tile server, not just the default one. You can also run it offline if you have local tile files in a supported format. Controls are designed around the keyboard: arrow keys pan the map, and two letter keys zoom in and out. If your terminal supports mouse events, you can also drag the map and use the scroll wheel to zoom, which makes navigation feel more natural. A toggle switches between Braille and block character rendering modes. Installing it locally takes one command with npm or snap on Linux, or npx to run it without installing. It requires Node.js version 10 or later. On Windows, the telnet-to-public-server approach is the easiest path since the project recommends a third-party telnet client for Windows users. The project is written entirely in JavaScript and is open source. It uses several well-known geographic and terminal libraries under the hood to handle tile parsing, line drawing, spatial indexing, and color rendering. The map data from OpenStreetMap is licensed under the Open Database License, and the project notes that you must credit OpenStreetMap if you use or redistribute the data.

Copy-paste prompts

Prompt 1
How do I install MapSCII with npm and connect it to a custom Mapbox tile server instead of the default one?
Prompt 2
Show me how to run MapSCII using npx so I can try it without installing anything permanently.
Prompt 3
How do I switch between Braille and block character rendering modes while using MapSCII?
Prompt 4
How do I use MapSCII with a local tile file for offline map browsing when I have no internet connection?
Prompt 5
How do I enable mouse controls in MapSCII to drag the map and zoom with the scroll wheel?
Open on GitHub → Explain another repo

← rastapasta on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.