Skip to content
This repository has been archived by the owner on May 24, 2021. It is now read-only.
/ tiffany Public archive

A command-line tool for rendering to TIFF any Google Static Maps image

License

Notifications You must be signed in to change notification settings

thinkingmachines/tiffany

Repository files navigation

A command-line tool for rendering to TIFF any image from Google Static Maps

tiffany downloads, georeferences, and labels any satellite image from the Google Static Maps (API). You can use this to prepare labeled data for downstream tasks such as in computer vision (object detection, semantic segmentation, etc.)

Features

  • Download Google Static Maps Images straight from the command-line
  • Automatically georeference downloaded GSM images (SRID: EPSG:4326)
  • Create training labels for the images by clipping an ESRI Shapefile

With a single command,

$ tiffany 14.546943935986324 121.01974525389744

you can generate the following outputs for an image centered at (14.54694524, 121.0197543253). Note that the --with-labels flag requires an input ESRI Shapefile preferably from OpenStreetMap (OSM).

Original image Georeferenced With labels
orig ref lbl
--without-reference default --with-labels

Installation

Getting the binaries

You can obtain the latest binaries from our Releases tab. Make sure to download the one compatible to your system. As of now, we only compile on amd64 architectures:

Linux (amd64) Darwin (amd64) Windows (amd64)
Latest tiffany-latest-linux-amd64 tiffany-latest-darwin-amd64 tiffany-latest-windows-amd64
Nightly tiffany-nightly-linux-amd64 tiffany-nightly-darwin-amd64 tiffany-nightly-windows-amd64

Compiling from source

Alternatively, you can compile tiffany from source. You need go1.11 and GDAL>=2.0.0 to create successful builds. First, clone the repository and enter it:

$ git clone git@github.com:thinkingmachines/tiffany.git
$ cd tiffany

Then get the dependencies and build the project:

$ go get
$ go build .

Optionally, you can also install tiffany inside your system

$ go install

Usage

Authentication

Tiffany requires a Google Static Maps API Key. For large amounts of requests, Tiffany also requires a Secret Key to sign the url. Generate store them inside an .tiffany.env file in your project directory:

# .tiffany.env
API_KEY="<your API key here>"
SECRET_KEY="<your Secret key here"

Getting images

To get images, simply call tiffany, and pass it your latitude and longitude:

$ tiffany 14.546943935986324 121.01974525389744

You can supply the .tiffany.env file by passing the filepath to the --env parameter. By default, it's searched from your project root:

$ tiffany 14.546943935986324 121.01974525389744 --env=path/to/.tiffany.env

The command above will generate a directory, tiffany.out where a *.png and its corresponding *.tiff file is located.

In case you don't want georeferenced images and prefer plain-old PNG images, then simply pass the --without-reference flag:

$ tiffany 14.546943935986324 121.01974525389744 --without-reference

Lastly, you can clip labels for your geo-referenced image from an ESRI Shapefile. This is useful for downstream tasks such as in machine learning:

$ tiffany 14.546943935986324 121.01974525389744 --with-labels=path/to/gis_osm_buildings_free_1.shp

Getting multiple images

Rather than invoking a for-loop, it is also possible to get multiple images by passing a CSV file containing the latitude and longitude of the points-of-interest in the batch command. This method is more efficient and relatively faster:

# coordinates.csv
latitude,longitude
14.546943935986324,121.01974525389744
14.438494843958949,121.84324983413455
14.879847197948529,121.81851791571952

And then,

$ tiffany batch coordinates.csv

Contributing

Simply fork this repository and make a Pull Request! We're open to any kind of contribution, but we'd definitely appreciate:

  • Implementation of new features
  • Writing documentation
  • Testing

Also, we have a CONTRIBUTING.md and a Code of Conduct, so please check that one out!

Acknowledgements

License

MIT License (c) 2019, Thinking Machines Data Science