Python CLI tool for plotting geo data in the terminal
PyPI:
$ pip install pixel-mapuv:
$ uv pip install pixel-mapTo display your data in the terminal, you can just pass a filename as an argument:
$ pixel-map <file_name>Tool can also display data for multiple files at once:
$ pixel-map <file_name_1> <file_name_2>See more examples below ⬇️
CLI Help output (pixel-map -h)
Usage: pixel-map [OPTIONS] FILES...
Plot the geo data into a terminal.
Generates a Matplotlib canvas that is rendered to an image and later transformed into a list of
unicode characters.
╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * files FILES... List of files to display. Those could be any that can be opened by GeoPandas. [required] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --bbox -b BBOX Clip the map to a given bounding box. Expects 4 floating point numbers separated by commas. │
│ --renderer -r TEXT Renderer used for generating terminal output. Possible values: all, ascii, ascii-bw, block, braille, braille-bw, half, quad, │
│ space. │
│ [default: (block)] │
│ --dark --light Uses the predefined dark or light style. Can be overriden with user defined style. [default: dark] │
│ --color -c COLOR Pass color or list of colours per each geo file. │
│ --alpha,--opacity -a FLOAT Pass opacity or list of opacities per each geo file. │
│ --basemap,--tileset -t TILES Set the basemap provider. Can be any value parsed by xyzservices library. Defaults to CartoDB.DarkMatterNoLabels if --dark │
│ or CartoDB.PositronNoLabels if --light. │
│ --no-border,--fullscreen -f Removes the border around the map. │
│ --no-background,--no-bg Removes the background of the map and plots only geo data. │
│ --background-color,--bg-color COLOR Set the background color. Can be used together with --no-background. │
│ --width INT Override the current console width. │
│ --height INT Override the current console height. │
│ --dpi INT DPI used to get better quality matplotlib plot before rendering to terminal. [default: 10] │
│ --example,--example-files Can be used to load one of example files based on name. Possible values: london_buildings, london_park, london_water, │
│ monaco_buildings. │
│ --version -v Show the application's version and exit. │
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
│ --help -h Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯pixel-map is published with few example files for testing.
$ pixel-map --example london_buildings
$ pixel-map --example london_buildings --light
$ pixel-map --example london_buildings london_water london_park -c C1,C0,C2
$ pixel-map --example london_water -c C0 -a 0.6 -t Esri.WorldImagery
You can explore multiple available renderers. Full list available in the pixel-map CLI help.
$ pixel-map --example london_buildings --no-bg -r ascii-bw
-
typer[all] (>=0.9.0)(click, colorama, rich, shellingham): Required for CLI -
rich (>=12.0.0): For showing progress and generating terminal output -
geopandas (>=0.8): For reading Geo files and plotting -
pyarrow (>=16.0.0): For geoparquet files support -
matplotlib (>=3.2.0): For generating the plot with styling and cropping -
contextily (>=1): For adding basemap to the plot -
numpy (>=1.26.0): For transforming matplotlib array into an image -
img2unicode[n2] (>=0.1a11): For transforming generated plot image into a list of unicode characters for the terminal
- Files are read by
GeoPandasto GeoSerieses. Matplotlibfigure is created with the size of the terminal (pixel-mapexpects a default monospace font with the ratio of 8 to 16 pixels. Figure canvas takes terminal height and multiplies it by two).- GeoSerieses are plotted to the canvas.
- Plot bounding box is expanded to the canvas ratio (based on terminal size).
- Basemap is loaded with
contextily. - Canvas is copied to the image as an
NumPyarray. img2unicodeis used to render image using unicode characters with color.Richstring output is generated using the list of unicode characters with background and foreground colors.- Output is printed to the console.
-
Why does my terminal render visible characters in the output?
Check if your terminal doesn't have automatic contrast changer for WCAG compatibility.
For example in VS Code there is an option
terminal.integrated.minimumContrastRatiothat is set to4.5by default.Contrast: 4.5 Contrast: 1 
-
Why are there black bars on the left/right, top/bottom of the output?
This can happen when output is bigger than Earth bounding box and basemap doesn't cover that far, but image is stretched to the full terminal size.
If you want to contribute, please fork the repository, use pdm tool to install the project.
To run the tests you can use command tox -e python3.12 (or other python version, -e is for the environment) or with simple pytest tests.
Please remember to update CHANGELOG.md with description your changes.