Help The New York Public Library put New York City’s history on the map!
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

NYC Space/Time Directory - Surveyor

Visit Surveyor!

Help The New York Public Library put New York City’s history on the map!

Surveyor is a geotagging tool designed to enhance the metadata of items within NYPL Digital Collections. It allows you to view and place images on a map of New York City. With each contribution through Surveyor, users create new knowledge about the Library’s collections!

For more information, see Surveyor’s About page, or read the blog post on nypl.org.

Surveyor was created for geotagging NYPL's collections, however, it's easy to adapt Surveyor and use it to geotag any collection of photos. As long as your images are available online and have unique identifiers as well as basic metadata, you can use Surveyor. To find out how, see Other Image Collections below.

Surveyor

NYC Space/Time Directory

Maps by Decade is part of the NYC Space/Time Directory. The goal of this project is to—through a variety of resources—unlock the potential of historical maps and provide opportunities to explore urban history across space and time.

Major support for the NYC Space/Time Directory is provided by the Knight News Challenge, an initiative of the John S. and James L. Knight Foundation.

Technology

Surveyor uses the following open source libraries:

Data

For each image for which users submit data, Surveyor collects geospatial information about the location where the photo was taken, as well as the direction and angle of the view of the image. For example, let's have a look at the screenshot above, showing the geotagging of a photo titled Pike and Henry Streets, Manhattan. The most important part of the screenshot is shown in more detail below:

The photographer stands on the corner of Pike Street and Henry Street in Manhattan, pointing his camera south, towards the Manhattan Bridge and the East River. A user correctly geotagging the photo, would place the camera marker on that street intersection, and point the field of view south, as shown in the screenshot. Submitting this data would have Surveyor send this data to its database as a GeoJSON file of the following form:

{
  "type": "Feature",
  "properties": {
    "angle": 36,
    "bearing": 170,
    "distance": 495
  },
  "geometry": {
    "type": "GeometryCollection",
    "geometries": [
      {
        "type": "Point",
        "coordinates": [
          -73.992533,
          40.7130856
        ]
      },
      {
        "type": "LineString",
        "coordinates": [
          [
            -73.9896355,
            40.7089532
          ],
          [
            -73.9933933,
            40.7084511
          ]
        ]
      }
    ]
  }
}

(Open this GeoJSON object in geojson.io.)

Surveyor uses the field-of-view library to generate this GeoJSON Feature and to compute the angle, bearing and distance. Once a user clicks the Submit button, Surveyor sends the GeoJSON data to brick-by-brick, an API for crowdsourcing tasks and submissions (and part of the NYC Space/Time Directory). Brick-by-brick is explained in more detail below.

When enough locations are submitted for a single image (for now, we require each image to be geotagged by at least five people), an algorithm will remove outliers, and try to determine the best submission. More information about this algorithm will be posted here soon.

All geotagged images will data will eventually be published as a dataset in the NYC Space/Time Directory.

API

Surveyor depends on brick-by-brick, a simple JSON API for requesting and storing crowdsourcing data (and part of the NYC Space/Time Directory project). From brick-by-brick, Surveyor requests a random image to geotag, and when the user has found that image’ location, Surveyor sends this location back to brick-by-brick.

For more information about brick-by-brick, see its GitHub repository.

Other Image Collections

Currently, Surveyor works with images from NYPL’s Digital Collections (see Surveyor’s About page for a list of these collections). However, it’s easy to use Surveyor to geotag your own collections of photos and images!

To do this, follow the following steps:

  • Run your own instance of brick-by-brick
  • Populate its database with your own photo collections:
    • Surveyor uses dc-to-brick to read images from Digital Collections and write data to its brick-by-brick database
    • dc-to-brick, in turn, uses to-brick, a Node.js library to connect to (and write to) any brick-by-brick database
  • Change all NYPL-related images and texts in Surveyor:
  • If you want users to be able to log in, you need to register OAuth Apps at one or more of the following providers (for more information, see brick-by-brick’s README):
    • GitHub
    • Twitter
    • Facebook
    • Google

In case you need help, you can open an issue in this repository, or send an email to spacetime@nypl.org.

Installation

To run Surveyor locally, first clone this GitHub repository:

git clone https://github.com/nypl-spacetime/surveyor.git

Then, install all Node.js dependencies:

cd surveyor
npm install

By default, Surveyor expects brick-by-brick to run on http://brick-by-brick.dev/ (You can use hotel to set up local .dev domains). You can change Surveyor’s default configuration, edit config/default.yml.

To start Surveyor, run:

npm start

To build Surveyor, run:

npm run build