This is the codebase for the user interface for the Terrapattern project.
For information about the project itself, or to try out the project, please see the Terrapattern website at http://www.terrapattern.com.
For technical details about the machine learning and search code, please see the repository at https://www.github.com/CreativeInquiry/terrapattern.
Terrapattern is a project of Golan Levin, David Newbury, Kyle McDonald, Irene Alvarado, Aman Tiwari, and Manzil Zaheer.
Terrapattern was made possible through a Media Innovation Prototype Fund grant from the John S. and James L. Knight Foundation, which supports transformational ideas that promote quality journalism, advance media innovation, engage communities and foster the arts. The Knight Foundation believes that democracy thrives when people and communities are informed and engaged.
This site has been developed using Sinatra, a Ruby library for small websites. It uses the standard conventions of a Sinatra project, and is designed to be hosted on Heroku.
Much of the javascript functionality has been added using the wonderful p5.js library, and also through the Google Maps API.
The site's has also made use of the Bootstrap Framework, and the ????? Theme.
If you're interested in trying to run a version of Terrapattern yourself, note that this project requires a search server from which to request search results. This is a completely separate process, and in our implementation is running on a Google App Engine server out in the cloud. To configure and run your own search server, please see the documentation in the main terrapattern repository.
To run this site locally, you'll need to clone the repo, then run the following commands in your terminal:
gem install bundler
gem install foreman
bundle installThe application also uses memcached for caching and assumes that you have it installed locally for testing. Our production version uses Memcached-Cloud, but for development you should use a locally-hosted version using the default configuration (no username/password, standard port, etc).
On OSX, the easiest way to install this is via homebrew:
brew install memcachedThe Procfile will automatically start up an instance of memcached for running.
You'll need the following environment variables to be set:
SEARCH_SERVER=<URL to the Search Server>
# This is the URL to to the service running the search engine.
GMAPS_KEY=<google api key>
# This is a Google API Browser key authorized to use the Google Maps Javascript API.
If you'd like the project to have a tiny bit of security, you can set these variables. Note that this uses HTTP basic authentication which is not actually secure without using https, but it does prevent random people from stumbling upon things.
TERRAPATTERN_USERNAME=<username>
TERRAPATTERN_PASSWORD=<password>
For testing, it can be helpful to modify your /etc/hosts file by adding the following the lines:
127.0.0.1 www.terrapattern.dev
127.0.0.1 pgh.terrapattern.dev
127.0.0.1 sf.terrapattern.dev
127.0.0.1 nyc.terrapattern.dev
127.0.0.1 detroit.terrapattern.dev
127.0.0.1 berlin.terrapattern.dev
This makes those domains resolve to your local computer and will allow you to test the multi-domain functionality locally.
Note that localhost:5100 will not work. You must have an explicit subdomain set.
The command to run the server locally is
foreman startThe Terrapattern project is designed to allow easy integration of additional cities or regions into the project.
To add a new city, you'll need to do 5 things:
- Add the tiles to the search server. (Note that doing this is outside the scope of this document)
- Add an entry to
cities.yamlfor the new region - Add a geojson file for the new city.
- (optionally) add a geojson file for the water features for the region.
- Add the tile lat/lng pairs into the
lat_lngs.jsonfile
<config/cities.yaml> is the main configuration file for the cities data. Each supported city should have a block of metadata associated with it. To add a new city, you must a new block. There are instructions within the comments within this file, but some additional notes are useful:
The name parameter is used throughout the interface to label the city. It can be anything you like, but if it gets long wrapping may become an issue.
The url_name parameter indicates what subdomain this city will live under. Obviously, it must be unique, and it must conform to standard URL requirements. We recommend a single, lowercase, ascii word.
The search_locale parameter is used to indicate which set of tiles searches are performed against. It must exactly match the index variable set on the search server and is case sensitive.
The center parameters indicate where the map will be centered on initial load. Obviously, it should be within the search region. We recommend finding some distinctive landmark for the region.
The bounding box parameters are used across the project, and should be set to the min and max values of the possible tile center latitude and longitude. If these values are incorrect, the minimap will be distorted and pins will not appear centered in the search results.
the geojson parameter should be the local path to a geojson file containing a single polygon. This should be the polygon used during the data model construction phase to select which tiles were downloaded.
the water parameter is also a geojson file, with a single MultiPolygon containing geometry that will display on the map. We typically use this to help people understand the geography of the object. Note that this will NOT clip to the mini-map boundaries, and that drawing this can be computationally expensive. Use the simplest geometry you can. Also note that this does not use a sophisticated geojson parser, so don't do anything clever with the geojson file—it's just looking for arrays of lat/lng points at the right locations.
<data/lat_lngs.json> is a list of possible latitudes and longitudes for each region. Within this json file, each region has an object, named with the url_name parameter for the region as defined within the cities.yaml file. Each object contains two arrays, one for latitude and one for longitude. These arrays should contain the possible latitude and longitude points for each tile. They should be unique values, and there is no correlation between lat and lng. These are used to make link clicked points with the potential tile ids.
One of the goals of Terrapattern is to provide new capabilites to the public. As such, we are releasing all of the source code and content under permissive licenses that allow both commercial and non-commercial applications. We do ask that if you use our work in your own projects you provide visible credit to the Terrapattern team.
All map data and satellite imagery is provided by third parties and is not subject to these licenses.
Terrapattern by Golan Levin, David Newbury, Kyle McDonald, Irene Alvaredo, Aman Tiwari, and Manzil Zaheer, and the content on the site is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
The underlying software for Terrapattern is made available under the MIT License.
Copyright (c) 2010-2016 Golan Levin, David Newbury, Kyle McDonald, Irene Alvarado, Aman Tiwari, & Manzil Zaheer. http://www.terrapattern.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the right to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.