tiffany
![GitHub](https://img.shields.io/github/license/thinkingmachines/tiffany.svg?color=blue&style=flat-square)
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](https://github.com/thinkingmachines/tiffany/raw/HEAD/assets/no_reference.png) | ![ref](https://github.com/thinkingmachines/tiffany/raw/HEAD/assets/with_reference.png) | ![lbl](https://github.com/thinkingmachines/tiffany/raw/HEAD/assets/with_labels.png) |
--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:
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.
Generate one and store it inside an .env
file in your project directory:
# .env
API_KEY="<your API key here>"
Getting images
To get images, simply call tiffany
, and pass it your latitude and longitude:
$ tiffany 14.546943935986324 121.01974525389744
This 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