ærialbot

A simple yet highly configurable bot that tweets geotagged aerial imagery of a random location in the world.

In a bit more detail, whenever you run ærialbot, it...

• loads a shapefile from disk,
• generates a random point꙳ within the bounds of this shape,
• figures out which map tiles need to be downloaded to cover a certain area around the point in sufficient꙳ detail,
• downloads those map tiles from a provider of your choice real fast (a threadpool is involved!),
• stitches them together and crops the resulting image to precisely match the configured area,
• saves that to disk,
• and tweets the image, optionally with a geotag.

Check out the following active ærialbot instances run by me...

• 🇺🇸 @americasquared, which tweets a satellite view of a randomly selected square mile of the United States every 6 hours (examples shown below).
• 🇰🇷 @baekmanpyeong, which tweets a square sized one million (백만, baekman) pyeong (평, traditional Korean area unit, roughly 3.3058 m²), i.e. 1.818×1.818 km, somewhere in South Korea every 8 hours.
• 🗾 @nihonmusuukei (Nihon mu sū kei = 日本無数景 ≈ 日本∞景, countless views of Japan), which tweets a square kilometer of Japan every 12 hours.
• 🌍 @placesfromorbit, a "worldwide" instance that tweets a 5×5 km square every 4 hours.

...and others (let me know if you want yours to be included):

• 🇩🇰 @DanskKvadrat (run by @Wegge), which focuses on Denmark and tweets a 2×2 km square every 4 hours.
• 🇷🇴 @AerianRobot (not sure who runs it), which tweets a square-shaped portion of Romania twice each day.
• 🇳🇱 @NL_kwadraat (run by @michelbinkhorst), which tweets a 2×2 km square of the Netherlands three times each day.
• 🇳🇱 @amsUpTop (run by @kns008), which tweets a random square of Amsterdam or its surroundings once a day.

Also check out @earthacrosstime, a "sibling" bot that tweets timelapse videos showcasing how random locations in the world have changed since 1984.

Features

Here's why ærialbot is a Good Bot:

• Configurability: Take a look at config.sample.ini – you can supply your own shapefile (or instead define a fixed point), control output verbosity, set a different map tile provider, define the filenames of the result images, scale them to your preferred size, define the text of the tweet, and more!
• ꙳Correctness: Because neighboring meridians are closer at the poles than at the equator, uniformly sampling the allowable range of latitudes would bias the generated random points toward the poles. Instead, ærialbot makes sure they are distributed with regard to surface area. For the same reason (plus the Mercator projection), the number of map tiles required to cover an area depends on the latitude – ærialbot accounts for this, too.
• ꙳Automatic zoom level determination: Simply define the dimensions of the desired area around the generated point – ærialbot will then take care of dialing in a (more than) sufficient zoom level.
• Comes with batteries included: The shapefiles/ directory contains a number of shapefiles to get you started, along with a guide on preparing further shapefiles for use with ærialbot.
• Tile grabbing performance: Multiple map tiles are downloaded in parallel, and there's a snazzy progress indicator (as you can see in the GIF below) to keep you updated on the download progress.
• Geotagging: Tweets will be geotagged with the precise location – you can disable this, of course.
• Logging: Keeps a log file – whether that's for debugging or reminiscing is your call. Again, you can disable this easily.

Usage

Setup

Being a good Python 3 citizen, ærialbot uses venv to avoid dependency hell. Run the following commands to get it installed on your system:

$ git clone https://github.com/doersino/aerialbot
$ python3 -m venv aerialbot
$ cd aerialbot
$ source bin/activate
$ pip3 install -r requirements.txt

(To deactivate the virtual environment, run deactivate.)

Configuration

Copy config.sample.ini to config.ini, open it and modify it based on the (admittedly wordy) instructions in the comments.

See shapefiles/README.md for advice regarding finding shapefiles of the region you're interested in and preparing them for use with ærialbot.

Running

Once you've set everything up and configured it to your liking, run:

$ python3 aerialbot.py

That's basically it!

If you want your bot to tweet at predefined intervals, use cron, runwhen or a similar tool. To make cron work with venv, you'll need to use bash and execute the activate script before running ærialbot (in this example, it runs every four hours at 30 minutes past the hour):

30 */4 * * * /usr/bin/env bash -c 'cd /PATH/TO/aerialbot && source bin/activate && python3 aerialbot.py'

Pro tip: If you want to host multiple instances of ærialbot, you don't need multiple copies of the code – multiple config files suffice: simply run python3 aerialbot.py one-of-your-config-files.ini.

FAQ

Why the name?

Because it's cute and I like the "æ" ligature.

Why did you make this tool?

Because satellite imagery can be extremely beautiful, and I was looking for a way of regularly receiving high-resolution satellite views of arbitrary locations such as the center pivot irrigation farms of the American heartland or squares of the Jefferson grid in my Twitter timeline.

Note that I've built this tool (along with its predecessor gomati) during the COVID-19 pandemic – when it was, you know, just kinda nice to see the great outdoors somehow.

Does this violate Google's terms of use?

(That's only relevant if you configure ærialbot to download tiles from Google Maps, which is the default source – but other tile providers do exist.)

Probably. I haven't checked. But they haven't banned my IP for downloading tens of thousands of map tiles during development and testing, so you're probably good as long as you don't use this tool for downloading a centimeter-scale map of your country. What's more, I can't think of how an ærialbot-based Twitter bot would compete with or keep revenue from any of Google's products. (And it's always worth keeping in mind that Google is an incredibly profitable company that earns the bulk of its income via folks like you just going about their days surfing the ad-filled web.)

Is there a relevant XKCD?

You bet.

Something is broken – can you fix it?

Possibly. Please feel free to file an issue – I'll be sure to take a look!

Future Work

These are ideas more than anything else – don't expect them to be implemented any time soon.

• Commission @smolrobots to draw a little mascot – maybe a satellite with a camera, or planet earth taking a selfie.
• Maybe split aerialbot.py up into multiple modules, take inspiration from here. This might not be required right now, but would help if any of the ideas listed below are implemented.
• Add an option to use OSM/Nominatim for reverse geocoding. This could go along with a refactor where a ReverseGeocoder interface is introduced, which two classes TwitterReverseGeocoder (with a constructor taking the Twitter credentials) and OsmReverseGeocoder implement. The config file would have to be extended with a reverse geocoder selection option, plus a reverse geocode string template and an explanation of the available variables (which may differ depending on the selected geocoder). This reverse geocode string would then be referencable in the tweet template.
• In addition to GeoShape.random_geopoint, also implement a Shape.random_edge_geopoint function for generating points on the edge of polygons (and polylines), and make it available via a config setting. This would 1. help test whether a given shapefile is accurate (and whether its projection is suitable), and 2. enable tweeting images of coasts or border regions, which might be interesting. Random point selection on polygon outlines would need to be done by randomly picking a segment of the outline via a distribution based on a prefix sum of the haversine distances along the outlines, then uniformly picking a point along the chosen segment (or linearly interpolating).
• Similarly, if a shapefile with (multi)points instead of a polygon or polyline is given, randomly select a location among those points. This could be used to set up a Twitter bot that tweets landmarks belonging to a certain category around the world (if such data is publicly available, that is – I'm sure OSM data could be filtered accordingly).
• Enable ærialbot to generate side views of areas with elevation data using rayshader. This would look super neat, but elevation data is probably not available at the required level of detail for most regions of the world, and I'm not sure if the available satellite imagery is aligned with reality well enough for this to look good. Probably not worth the effort.
• Build an ambient device, probably based around a Raspberry Pi and a square display like this one, that runs a variant of ærialbot that would download and display a new image (plus metadata) every time the user taps the screen or presses a button. It could be called "πinthesky" or something even more terrible. Basically, I envision this device to take the shape of a small wooden box sitting on a shelf or mantle. (I almost certainly won't build this because I've got enough screens in my life – so feel free to steal this idea under the condition of sending me a picture of the end result!)