# GeoGraf

[![Build Status](https://travis-ci.org/wimdu/geo_graf.png?branch=master)](https://travis-ci.org/wimdu/geo_graf)

## Overview

This gem computes the relation between multiple polygons (do they overlap and
by how much?), such as Wimdu's GeoLocations.

GeoGraf uses [RGeo](http://dazuma.github.io/rgeo/rdoc/) to perform the
calculations. It uses the
[Mercator projection](http://en.wikipedia.org/wiki/Mercator_projection), which
projects the surface of earth onto a flat surface. This is inaccurate, as
areas appear bigger when they are further away from the equator (have a look at
Greenland and the DR Congo on Google Maps, they both are roughly 2 million
square kilometers big). However, the assumption is that the error of areas that
relate to each other is rather small, as the overlapping area is at the same
latitude. And we're not interested in the correct area calculation, we just need
to know if they overlap, which is the bigger one and roughly how much they
overlap.

The input is expected to be an array of polygon descriptions. Each polygon
description has to be a hash with an `:id` key and `:polygon_coords`, which
itself is an array of coordinates describing the polygon. Each coordinate is
an array of it's latitude and longitude (in this order).

Example:

```ruby
require 'geo_graf'

GeoGraf.intersections_for(
  [
    {
      id: 1,
      polygon_coords: [[-2, -2], [2, -2], [2, 2], [-2, 2], [-2, -2]]
    },
    {
      id: 2,
      polygon_coords: [[-3, -3], [-1, -3], [-1, -1], [-3, -1], [-3, -3]]
    }
  ]
)
```

The output is an array of relation descriptions. Each description is a hash in
the following format:
  * `:id`: The ID of the polygon. It's always the ID of the smaller polygon
    (by area).
  * `:contained_area_percentage`: How much of the area of the smaller polygon
    is contained in the larger one.
  * `:container_id`: The ID of the larger polygon.

If two polygons don't overlap, no relation exists and there will be no
description returned for these two.

For the example above, the following result will be returned:

```ruby
[
  {
    id: 2,
    contained_area_percentage: 25,
    container_id: 1
  }
]
```

This means that 25% of the area of polygon 2 overlap with the area of polygon
1.

## Installation

GeoGraf depends on RGeo with [GEOS](http://trac.osgeo.org/geos/) >= 3.3.3. You
need to install it before installing RGeo.

### MacOs with homebrew

```sh
brew install geos
```

### Ubuntu/Debian

```sh
sudo apt-get install libgeos++-dev
```

## License
Copyright (c) 2013 Wimdu GmbH (MIT License). See LICENSE.txt for details.