Skip to content

IIAB Maps

Jump to bottom
A Holt edited this page Jan 28, 2023 · 251 revisions

Internet-in-a-Box (IIAB) Maps

Internet-in-a-Box (IIAB) Maps are like Google Maps but better, for schools especially, as they work offline (including satellite photos!) and avoid all the advertising.

INVITATION: If you can help ongoing efforts to polish maps for children in offline schools in all countries, directly contributing to beautifying OpenStreetMap (VIDEO) thereby bringing Earth to life for all, please get in touch below.

  1. IIAB Map Packs use vector (not bitmap) techniques to display attractive, high-resolution maps for your continent — or similar regions: (most are 6-to-30 GB, older Map Packs at [1] [2] [3])

    • 7 Major "Continents"
    • The Middle East
    • Central America & the Caribbean
    • Spanish-speaking Regions
    • World to Zoom 10 — 3.2 GB
    • The Entire World — 85 GB (Live Demo!)

    Every IIAB Map Pack includes:

    • Zoomable vector maps (15 levels of zoom from 0-14, scaling beautifully to level 18) with detailed resolution to about 1 m, in the bounding box focus area (typically a continent!) This OpenStreetMap content is updated quasi-annually, in 2017 thanks to OpenMapTiles.org and then in September 2019 and again in October/November 2020 thanks to quentar1.
    • Worldwide vector maps (11 levels of zoom, from 0-10).
    • Worldwide satellite photos (10 levels of zoom, from 0-9) from Sentinel, offering pixel resolution of approximately 305 x 305 m.

  2. IIAB Maps also offer High Resolution Satellite Photo Regions, letting you add 4 more levels of zoom (up to zoom level 13, offering pixel resolution of approximately 19 x 19 m) within as many square regions (100x100 km, 300x300 km, or 1000x1000 km) as your community finds useful. Also from Sentinel.

    That's a 16X improvement in linear resolution — which is a 256X improvement in photographic information density!

  3. IIAB Maps let you Search Worldwide for cities/towns/settlements that have more than 1000 people (127,654 are included).

Please see the README just below for more on the state-of-the-art as of May 2022, for IIAB 8.0. For nuts & bolts details as to how this came together, see these sections below: How do I upgrade an IIAB Map Pack?, Where are IIAB Maps stored?, What might future IIAB Maps bring?, Credits, Software (Source Code) and Links & Advanced Topics.

What's New with IIAB Maps?

Please see the new IIAB Maps README accompanying IIAB 8.0.

How do I install Map Pack(s) and Satellite Photo Region(s) on IIAB 8.0+ ?

  1. If you have not yet done so, install Internet-in-a-Box (IIAB) 8.0+ (a pre-release is fine!) from https://download.iiab.io

    • Choose (1) SMALL-sized, (2) MEDIUM-sized, or (3) LARGE-sized — these will install the IIAB Maps software, including 7 levels of zoom (OSM vector maps) just to get things started.
    • Proceed with your IIAB software install (you might need to run sudo iiab several times).
    • You'll know it's complete when you see "INTERNET-IN-A-BOX (IIAB) SOFTWARE INSTALL IS COMPLETE" and "HIT [Enter] TO REBOOT".

  2. OPTION A: Skip all details below, and just install a continent/region!

    OPTION B: Continue following all steps below — if you prefer a deeper understanding...

  3. Browse to your IIAB home page (typically http://box or http://box.lan) and click on Install IIAB Maps (typically that's http://box/osm-vector-maps/installer/) to choose the Map Pack you want — and then later any Hi-Res Satellite Photos Region(s) needed by local communities.

    • A Map Pack provides Hi-Res vector maps (zoom levels 0-14, overzoom to level 18) for an entire continent — or the Caribbean, or the Middle East, or Spanish-speaking regions — or the entire planet!
      • Each Map Pack also provides Lo-Res vectors maps worldwide (zoom levels 0-10).
      • Each Map Pack also provides Lo-Res satellite photos worldwide (zoom levels 0-9).
    • You must install at least 1 Map Pack to begin!
      • Later (after your Map Pack is downloaded and installed) you can return to this page to...pick custom region(s) where you want Hi-Res Satellite Photos (which adds zoom levels 10-13, 4 more than above!) for any square regions (100x100 km, 300x300 km, or 1000x1000 km) of your choosing.

  4. Follow the visual instructions — example screenshot: Screenshot

    • When it asks you to copy and paste into an IIAB Terminal, you have 2 choices: (to get to a Linux command-line, on your IIAB server)
      1. Attach a screen and keyboard to your IIAB.
      2. Run a command like ssh iiab-admin@box.lan to connect to your IIAB. If you're running Windows, consider using Putty instead. Specify your IIAB Host Name (typically box.lan, or sometimes this is a number like 192.168.0.x as provided by your home router, so here are some tips for finding your IIAB IP Address thanks to Raspberry Pi OS and Ubuntu).
    • Either way, log in as user: iiab-admin
    • The default password for iiab-admin is published at http://FAQ.IIAB.IO > "What are the default passwords?"

  5. Copy and Paste the gray line into your IIAB Terminal:

    • Triple-clicking is an easy way to highlight the entire gray textfield before you copy it.
    • After pasting that into your IIAB Terminal, hit [Enter].
    • If necessary, enter iiab-admin's password again (for sudo).

  6. Keep an eye on the downloading progress at the command-line there, every now and then, to make sure it's moving along.

    • Please be patient as this can sometimes take many hours, depending on your Internet connection etc.
    • Very large Map Packs might need to download overnight.

  7. Here's a working example of IIAB Maps in action, so you know roughly what to look forward to: http://iiab.me/maps

    • Browse to http://box/maps on your own IIAB server to test out the IIAB Map Pack(s) and Hi-Res Satellite Photo Region(s) you've downloaded !
    • Beautify your IIAB home page using Admin Console > Content Menus so the local community knows how to begin, in their own language.
    • Click on Content Item List to reorder the Content Packs and Apps on your IIAB home page, equivalent to: /library/www/html/home/menu.json

  8. Help your local community, students and teachers put geographic literacy (http://box/maps) to work — for their environment and their lives:

    1. Sit down with them to explore the Map Pack(s) and Hi-Res Satellite Photos Region(s) you've arranged.
    2. Learn together how to search for any city or town worldwide.
    3. Drag-and-Drop Map Overlays (any relevant GeoJSON file) onto the map in your browser. For example download then try this GeoJSON file, to explore the shape of gerrymandered US Congressional districts: https://eric.clst.org/assets/wiki/uploads/Stuff/gz_2010_us_500_11_20m.json
    4. Ask students to take photos that matter to them in their community — then Right-Click on the map (http://box/maps) to add those photos and descriptions to the map. Choose "Add Data Point" after right-clicking, and then later "Export Points" to share with others.

How do I upgrade an IIAB Map Pack?

Upgrading is not supported — please install IIAB 8.0+ if you want new maps!

ADVANCED: if you want to understand how IIAB Maps are evolving in 2022, keep an eye on:

Finally, if you can help contribute to this important community effort, please do contact us so we can explain more!

In the weeks/months after installing your IIAB Map Pack, you might notice that a new Map Pack is published, e.g. if you monitor this "map catalog" link showing the latest available:

- http://download.iiab.io/content/OSM/vector-tiles/map-catalog.json

See also recent copies of our map catalog (map-catalog.son) within subdirectories like 2020-08-10 here:

- https://github.com/iiab/maps/blob/master/public/

IIAB Maps is beginning to move to "perma_ref" names (see /etc/iiab/map-catalog.json and /etc/iiab/regions.json on your IIAB, with symlinks in /library/www/html/common/assets/) to allow you to upgrade Map Packs more automagically in future.

Note that IIAB Map Packs changed from the .zip format to the .mbtiles format in 2020, as part of the IIAB 7.2 release, so we are in transition, please stay tuned!

_2020-10-12: For a preview of upcoming map catalog changes, see PR iiab/maps#41 and https://github.com/georgejhunt/maps/blob/addbase/public/2020-10-06/modify_catalog.py.

Where are IIAB Maps stored?

IIAB Map Packs (.mbtiles files) are usually published in several places, as outlined here:

After you've downloaded and installed a Map Pack (How do I install Map Pack(s) and Satellite Photo Region(s) on IIAB 8.0+ ?) its 3 files (hi-res vector maps for the "continent" in question, lo-res vector maps = 2.0 GB osm-planet_z0-z10_2020.mbtiles, lo-res satellite photos = 1.2 GB satellite_z0-z9_2020.mbtiles) will be stored in this directory:

  • /library/www/osm-vector-maps/viewer/tiles

In the past (i.e. up to IIAB 7.1) Map Packs contain both program and data, and were unzipped into a subdirectory of:

  • /library/www/osm-vector-maps

An example (generally containing many gigabytes!) would have been:

  • /library/www/osm-vector-maps/en-osm-omt_africa_2017-07-03_v0.2

If you too are a map hacker interested in contributing, please contact us, so we can explain more.

Customizations

  1. Anyone who browses to http://box/maps generally sees the continent/region most recently installed — centered in their browser — at a zoom level suitable for that continent/region.

    If you want to re-center this initial viewport browser experience for all users (e.g. to a different latitude/longitude, and/or to a different zoom level) you can edit this file:

    /library/www/osm-vector-maps/viewer/init.json

  2. Installed continents/regions are outlined in 💚 green rectangles 💚.

    Installed satellite photo regions are outlined in 💛 yellow/orange squares 💛.

    To brighten the yellow/orange squares, change Line 441 of /library/www/osm-vector-maps/viewer/viewer-bundle.js from color: 'rgba(250, 200, 20, .2)', to:

    color: 'rgba(250, 200, 20, 1)',

    To de-emphasize the yellow/orange squares, change it to:

    color: 'rgba(250, 200, 20, .05)',

    Similarly — to adjust green rectangle appearances, change line 456 from color: 'rgba(67, 163, 46, 1)', to any RGB color and opacity/transparency.

  3. You might also want to take a look at the 15 bounding boxes below: (used to display the above green rectangles)

    /library/www/osm-vector-maps/viewer/assets/bboxes.geojson

    Example: 4 of these 15 bounding boxes make up the overall (non-contiguous!) region named "spanish_speaking_regions".

Known Issues

As of May 2022, recent issues included:

  • Teachers want Accents to work when searching for cities in OpenStreetMap #662 (Can multilingual folk confirm this is really/sufficiently fixed?)
  • #3077 (A) "size" erroneous in map-catalog.json (B) NEW OSM dataset from Oct/Nov 2020 (C) Prep for future datasets incl Satellite Photos
  • https://github.com/iiab/iiab/search?q=osm&type=issues

If you get completely stuck, don't hesitate to contact us !

What might future IIAB Maps bring?

INVITATION: If you can help ongoing efforts to polish maps for children in offline schools in all countries, directly contributing to beautifying OpenStreetMap (VIDEO) thereby bringing Earth to life for all, Thank You! Read more at (#877) and please do get in touch to learn more!

Thanks for your help evolving this into a continuously more friendly community product, as Usability Engineering begins right here — thanks to all who can assist! Background: Internet-in-a-Box is a volunteer community that greatly welcomes your suggestions and contributions !

  • Map issues (and pull requests) currently being discussed or worked on: https://github.com/iiab/iiab/issues?q=is%3Aopen+OSM
  • Higher-resolution satellite photos within localized area(s), that George Hunt is working on (mid-2020) to provide 4 more levels of zoom (for any 100x100 km, 300x300 km or 1000x1000 km regions of interest) as summarized under "July 9, 2020" at http://minutes.iiab.io (DONE!)
  • Thematic/Custom maps and/or overlays based on Wikidata (Swapnil Sinha's GSoC project).
  • The extreme slowness of downloads from archive.org (most often as slow as 1-2 mbit/sec since early 2020, but briefly back up to 10-20 mbit/sec in July 2020?) might be mitigated using torrents? As the Internet Archive already seeds. But these would need to be augmented and the endless maintenance hassles of hosting/seeding/monitoring would need to be brought firmly under control: #2553 #3111
  • http://box/maps causes Chrome to crash rather often on Android, and the user experience could use improvement: #1728
  • Individual .mbtiles Map Packs (e.g. smaller map regions, for cities, countries, etc) might in future be directly downloadable to your IIAB, as new ones are published here: https://openmaptiles.com/downloads/planet/
  • Multiple Map Packs might be downloadable to your IIAB, all of them viewable thru the same http://box/maps URL, possibly by combining their .mbtiles files into a single unified .mbtiles file, e.g. using append2region, similar to what Jérôme Gagnon-Voyer proposed in his original design doc (listed at the bottom of this page).
  • Descriptions of Map Packs (on your http://box IIAB Home Page) could offer more tips & tricks for teachers and students, e.g. how to search for cities etc.
  • http://box/maps/maplist/ -> http://box/osm-vector-maps/installer/ visual catalog might update itself, showing IIAB operator the very latest maps available?
  • Magrit 0.8.14 for civic/local mapmaking, with URL box/magrit ? PR #1579
  • Please suggest the highest priority mapmaking needs and/or how you might help!

Credits

Much of the original work on IIAB Maps was coordinated by Braddock Gaskill and Joel Steres in 2012-2015.

More recently George Hunt refined city search, moved to vector-based Map Packs, and added satellite photos — leading to major advances in September 2018 (IIAB 6.6), July 2019 (for IIAB 7.0), June 2020 (IIAB 7.1), October 2020 (for IIAB 7.2) and April 2022 (for IIAB 8.0).

Thank you also to Tim Moody, Jerry Vonau, Adam Holt, Anish Mangal, Avni Khatri, Mir Rodríguez Lombardo, Minh Nguyen, Paul Norman, Jérôme Gagnon-Voyer, Nick Doiron & other volunteer professionals from the OpenStreetMap community who are making this tremendous, ongoing progress possible!

Repos & Source Code

Links & Advanced Topics

In reverse chronological order:

Clone this wiki locally