Welcome to Polycircles documentation!¶

Polygonal circle approximations for KMLs and general use.

Getting started¶

Installing¶

pip install polycircles

Your first KML circle¶

Generates a circle approximation readable by simpleKML.

from polycircles import polycircles

polycircle = polycircles.Polycircle(latitude=40.768085,
                                    longitude=-73.981885,
                                    radius=200,
                                    number_of_vertices=36)
kml = simplekml.Kml()
pol = kml.newpolygon(name="Columbus Circle, Manhattan",
                                         outerboundaryis=polycircle.to_kml())
pol.style.polystyle.color = \
        simplekml.Color.changealphaint(200, simplekml.Color.green)
kml.save("test_kml_polygon_3_manhattan.kml")

Note that a polygon with 36 vertices looks pretty much like a circle:

Polygon circle in Google Earth. Image Credit: Google

A Polycircle above Columbus Square, Columbus Square, Manhattan, NYC, United States

Image: Google Earth, Credit: Google

Sequence of lat-lon points¶

polycircles can simply generate a series of lat-lon tuples, for any non-KML usage.

   import pprint
   from polycircles import polycircles
   polycircle = polycircles.Polycircle(latitude=32.074523,
                                       longitude=34.791469,
                                       radius=20,
                                       number_of_vertices=12)
   pprint.pprint(polycircle.to_lat_lon())
   ((32.07470336197859, 34.791469),
    (32.074679198011374, 34.7915749137218),
...
    (32.074613180857156, 34.79128555218445),
    (32.074679198011374, 34.791363086278196))

Installing and testing¶

Installing¶

The following command:

pip install polycircles

Will install polycircles and all its dependencies.

Testing¶

First, clone the gir repo.

git clone https://github.com/adamatan/polycircles.git

Unit tests¶

python setup.py test

BDD tests¶

I use behave for BDD tests.

pip install -r test_requirements.txt
behave

Travis builds¶

The package is built and tested in travis-ci for every commit.

KML circles¶

Basic KML circle¶

Generates a circle approximation readable by simpleKML.

from polycircles import polycircles

polycircle = polycircles.Polycircle(latitude=40.768085,
                                    longitude=-73.981885,
                                    radius=200,
                                    number_of_vertices=36)
kml = simplekml.Kml()
pol = kml.newpolygon(name="Columbus Circle, Manhattan",
                                         outerboundaryis=polycircle.to_kml())
pol.style.polystyle.color = \
        simplekml.Color.changealphaint(200, simplekml.Color.green)
kml.save("test_kml_polygon_3_manhattan.kml")

Note that a polygon with 36 vertices looks pretty much like a circle:

A Polycircle above Columbus Square, Columbus Square, Manhattan, NYC, United States

Image: Google Earth, Credit: Google

Donut! (Well, Torus)¶

Using the innerboundaryis of simpleKML Polygon object and two polycircles, a donut-shape can be easily created:

outer_polycircle = polycircles.Polycircle(latitude=40.768085,
                                          longitude=-73.981885,
                                          radius=200,
                                          number_of_vertices=36)
inner_polycircle = polycircles.Polycircle(latitude=40.768085,
                                          longitude=-73.981885,
                                          radius=180,
                                          number_of_vertices=36)

kml = simplekml.Kml()
pol = kml.newpolygon(name="Torus around Columbus Circle, Manhattan",
                                         outerboundaryis=outer_polycircle.to_kml(),
                                         innerboundaryis=inner_polycircle.to_kml())
pol.style.polystyle.color = \
        simplekml.Color.changealphaint(200, simplekml.Color.red)
kml.save("test_kml_polygon_2_torus_manhattan.kml")

A Torus made from two Polycircles, Columbus Square, Manhattan, NYC, United States

Image: Google Earth, Credit: Google

Or even:

The Olympic logo made from 5 Torus Pplycircles, Copacabana beach, Rio de Janeiro, Brazil

Image: Google Earth, Credit: Google

Accuracy¶

Distance accuracy¶

Polycircle uses Python’s geographiclib for distance calculations.

Method	Accuracy
Simple trigonometry	Dozens of meters
geographiclib	10^-4 meters

The distance was measured by geopy.

How many vertices?¶

Raising the number of vertices makes the polygon illusion more compelling. On the other side, too many vertices make the KML file larger and Google Earth slower.

In my opinion, 36 edges are the right balance between appearances and file size.

A Polycircle above The Namibian desert, Namibia.

Image: Google Earth, Credit: Google

Development¶

Changelog¶

0.1¶

Circle generation

Tests

Documentation

TODO¶

Command line script, making Polycircles useful for other languages

Ellipses

Simple Torus creation

Known bugs¶

There is no fill color in Google Earth for triangles (polycircles with 3 vertices).

Polygon circle in Google Earth. Map data: Google