RubyGems - simpler-tiles - Versions diffs - 0.0.1 - Mend

simpler-tiles 0.0.1

Files changed (56) hide show

data/.gitignore +17 -0
data/Gemfile +2 -0
data/LICENSE +19 -0
data/README +22 -0
data/Rakefile +71 -0
data/doc/SimplerTiles/Bounds.html +506 -0
data/doc/SimplerTiles/Layer.html +593 -0
data/doc/SimplerTiles/Map.html +2081 -0
data/doc/SimplerTiles/PP.html +204 -0
data/doc/SimplerTiles/Query.html +521 -0
data/doc/SimplerTiles/Style.html +577 -0
data/doc/SimplerTiles.html +167 -0
data/doc/_index.html +188 -0
data/doc/class_list.html +47 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +55 -0
data/doc/css/style.css +322 -0
data/doc/file.README.html +89 -0
data/doc/file_list.html +49 -0
data/doc/frames.html +13 -0
data/doc/index.html +89 -0
data/doc/js/app.js +205 -0
data/doc/js/full_list.js +173 -0
data/doc/js/jquery.js +16 -0
data/doc/method_list.html +390 -0
data/doc/top-level-namespace.html +105 -0
data/ext/simpler_tiles/bounds.c +90 -0
data/ext/simpler_tiles/bounds.h +17 -0
data/ext/simpler_tiles/depend +7 -0
data/ext/simpler_tiles/extconf.rb +42 -0
data/ext/simpler_tiles/layer.c +93 -0
data/ext/simpler_tiles/layer.h +16 -0
data/ext/simpler_tiles/map.c +338 -0
data/ext/simpler_tiles/map.h +17 -0
data/ext/simpler_tiles/query.c +87 -0
data/ext/simpler_tiles/query.h +17 -0
data/ext/simpler_tiles/simpler_tiles.c +16 -0
data/ext/simpler_tiles/simpler_tiles.h +25 -0
data/ext/simpler_tiles/style.c +106 -0
data/ext/simpler_tiles/style.h +17 -0
data/index.erb +459 -0
data/index.html +439 -0
data/lib/simpler_tiles/bounds.rb +19 -0
data/lib/simpler_tiles/layer.rb +25 -0
data/lib/simpler_tiles/map.rb +55 -0
data/lib/simpler_tiles/mixins/pp.rb +13 -0
data/lib/simpler_tiles/query.rb +28 -0
data/lib/simpler_tiles/style.rb +19 -0
data/lib/simpler_tiles/version.rb +4 -0
data/lib/simpler_tiles.rb +13 -0
data/simpler-tiles-logo.png +0 -0
data/simpler-tiles.gemspec +30 -0
data/test/helper.rb +8 -0
data/test/test_map.rb +67 -0
data/test/test_simpler_tiles.rb +26 -0
metadata +199 -0

data/ext/simpler_tiles/style.h ADDED Viewed

@@ -0,0 +1,17 @@
+#ifndef _SIMPLER_STYLE_H
+#define _SIMPLER_STYLE_H
+#include "simpler_tiles.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+void init_style();
+extern VALUE cSimplerTilesStyle;
+#ifdef __cplusplus
+}
+#endif
+#endif

data/index.erb ADDED Viewed

@@ -0,0 +1,459 @@
+<%
+  def highlight(lang, code)
+    IO.popen("pygmentize -f html -l #{lang}", 'w+') do |p|
+      p.puts code
+      p.close_write
+      p.read
+    end
+  end
+%>
+<!doctype html>
+<html>
+  <head>
+    <title>Simpler Tiles</title>
+<!--
+  +-----------------------------+
+  |                          / ~|
+  |               ----------   /|
+  |    Simpler  /    ---------  |
+  |            / ~ / **         |
+  |           /   / ****        |
+  |      ----  ~ / ******       |
+  |     / ~~  -- *******        |
+  |    /    /    *****          |
+  |   /    /                    |
+  |  / ~~ /       Tiles         |
+  |-     /                      |
+  | ~~~ /                       |
+  +-----------------------------+
+-->
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+    <style>
+      /* reset */
+      div, html, body {
+        margin: 0;
+        padding: 0;
+        border: 0;
+        vertical-align: baseline;
+      }
+      ul { list-style: none; padding-left: 10px;}
+      li { margin-bottom: 1em; }
+      /* text styles */
+      body {
+        font-family: "Helvetica Nueue", Helvetica, sans-serif;
+        font-size: 14px;
+        line-height: 1.7em;
+        margin-left: auto;
+        margin-right: auto;
+        width: 600px;
+        padding: 20px;
+      }
+      p, li {
+        width: 600px;
+        margin: 0px 0px 1em;
+      }
+      h1, h2, h3 {
+        text-rendering: optimizeLegibility;
+        margin-left: -5px;
+      }
+      h4 {
+        margin: 0px;
+        margin-top: 30px;
+        margin-left: -5px;
+        font-weight: normal;
+      }
+      h4 code {
+        padding: 4px;
+        background-color: #e6f3ff;
+      }
+      ol {
+        padding-left: 0px;
+      }
+      code, pre, tt { font-family: Monaco, monospace; font-size: 12px; }
+      tt { border:1px solid #efefef; padding: 2px;}
+      dd { margin-left: 1em; }
+      a { color: black; }
+      a:hover { text-decoration: none; }
+      pre {
+        padding-left: 10px;
+        font-size: 12px;
+        border-left: 5px solid #efefef;
+        line-height: 1.3;
+      }
+      hr {
+        border: 0;
+        border-top: 1px solid #efefef;
+        height: 1px;
+      }
+      /* styles stolen from docco */
+      body .hll { background-color: #ffffcc }
+      body .c { color: #408080; font-style: italic }  /* Comment */
+      body .err { border: 1px solid #FF0000 }         /* Error */
+      body .k { color: #954121 }                      /* Keyword */
+      body .o { color: #666666 }                      /* Operator */
+      body .cm { color: #408080; font-style: italic } /* Comment.Multiline */
+      body .cp { color: #BC7A00 }                     /* Comment.Preproc */
+      body .c1 { color: #408080; font-style: italic } /* Comment.Single */
+      body .cs { color: #408080; font-style: italic } /* Comment.Special */
+      body .gd { color: #A00000 }                     /* Generic.Deleted */
+      body .ge { font-style: italic }                 /* Generic.Emph */
+      body .gr { color: #FF0000 }                     /* Generic.Error */
+      body .gh { color: #000080; font-weight: bold }  /* Generic.Heading */
+      body .gi { color: #00A000 }                     /* Generic.Inserted */
+      body .go { color: #808080 }                     /* Generic.Output */
+      body .gp { color: #000080; font-weight: bold }  /* Generic.Prompt */
+      body .gs { font-weight: bold }                  /* Generic.Strong */
+      body .gu { color: #800080; font-weight: bold }  /* Generic.Subheading */
+      body .gt { color: #0040D0 }                     /* Generic.Traceback */
+      body .kc { color: #954121 }                     /* Keyword.Constant */
+      body .kd { color: #954121; font-weight: bold }  /* Keyword.Declaration */
+      body .kn { color: #954121; font-weight: bold }  /* Keyword.Namespace */
+      body .kp { color: #954121 }                     /* Keyword.Pseudo */
+      body .kr { color: #954121; font-weight: bold }  /* Keyword.Reserved */
+      body .kt { color: #B00040 }                     /* Keyword.Type */
+      body .m { color: #666666 }                      /* Literal.Number */
+      body .s { color: #219161 }                      /* Literal.String */
+      body .na { color: #7D9029 }                     /* Name.Attribute */
+      body .nb { color: #954121 }                     /* Name.Builtin */
+      body .nc { color: #0000FF; font-weight: bold }  /* Name.Class */
+      body .no { color: #880000 }                     /* Name.Constant */
+      body .nd { color: #AA22FF }                     /* Name.Decorator */
+      body .ni { color: #999999; font-weight: bold }  /* Name.Entity */
+      body .ne { color: #D2413A; font-weight: bold }  /* Name.Exception */
+      body .nf { color: #0000FF }                     /* Name.Function */
+      body .nl { color: #A0A000 }                     /* Name.Label */
+      body .nn { color: #0000FF; font-weight: bold }  /* Name.Namespace */
+      body .nt { color: #954121; font-weight: bold }  /* Name.Tag */
+      body .nv { color: #19469D }                     /* Name.Variable */
+      body .ow { color: #AA22FF; font-weight: bold }  /* Operator.Word */
+      body .w { color: #bbbbbb }                      /* Text.Whitespace */
+      body .mf { color: #666666 }                     /* Literal.Number.Float */
+      body .mh { color: #666666 }                     /* Literal.Number.Hex */
+      body .mi { color: #666666 }                     /* Literal.Number.Integer */
+      body .mo { color: #666666 }                     /* Literal.Number.Oct */
+      body .sb { color: #219161 }                     /* Literal.String.Backtick */
+      body .sc { color: #219161 }                     /* Literal.String.Char */
+      body .sd { color: #219161; font-style: italic } /* Literal.String.Doc */
+      body .s2 { color: #219161 }                     /* Literal.String.Double */
+      body .se { color: #BB6622; font-weight: bold }  /* Literal.String.Escape */
+      body .sh { color: #219161 }                     /* Literal.String.Heredoc */
+      body .si { color: #BB6688; font-weight: bold }  /* Literal.String.Interpol */
+      body .sx { color: #954121 }                     /* Literal.String.Other */
+      body .sr { color: #BB6688 }                     /* Literal.String.Regex */
+      body .s1 { color: #219161 }                     /* Literal.String.Single */
+      body .ss { color: #19469D }                     /* Literal.String.Symbol */
+      body .bp { color: #954121 }                     /* Name.Builtin.Pseudo */
+      body .vc { color: #19469D }                     /* Name.Variable.Class */
+      body .vg { color: #19469D }                     /* Name.Variable.Global */
+      body .vi { color: #19469D }                     /* Name.Variable.Instance */
+      body .il { color: #666666 }                     /* Literal.Number.Integer.Long */
+    </style>
+  </head>
+  <body>
+    <img src="simpler-tiles-logo.png">
+    <p>
+      <a href="http://github.com/propublica/simpler-tiles">Simpler Tiles</a>
+      is a library of ruby bindings for
+      <a href="http://propublica.github.com/simple-tiles/">Simple Tiles</a>, a
+      GIS image generation library. It allows you to generate PNG based map
+      images without having to dip into straight C and easily connects with
+      ActiveRecord. It can display any vector data that
+      <a href="http://www.gdal.org/ogr/ogr_formats.html">OGR</a> can read.
+    </p>
+    <p>
+      The source is at <a href="http://github.com/propublica/simpler-tiles">Github</a>.
+      You can install the gem with:
+<pre>
+$ gem install simpler-tiles
+</pre>
+    </p>
+    <p>
+      The api docs are <a href="doc/index.html">here</a>, and if you have
+      comments or questions head on over to <tt>#newsapps</tt> or <tt>#propublica</tt>
+      on Freenode, or post them in the github issue
+      <a href="https://github.com/propublica/simpler-tiles/issues?sort=created&direction=desc&state=open">tracker</a>.
+    </p>
+    <h2>Dependencies</h2>
+    <p>
+      Simpler Tiles depends on <a href="http://propublica.github.com/simple-tiles/">Simple Tiles</a>, <a href="http://www.gdal.org/ogr/">OGR</a>, <a href="http://cairographics.org/">Cairo</a> and <a href="http://www.pango.org/">Pango</a>. You can find
+      installation instructions for these libraries in the
+      <a href="http://propublica.github.com/simple-tiles/#dependencies">Simple Tiles
+      documentation</a>.
+    </p>
+    <h2>Overview</h2>
+    <p>
+      Simpler Tiles contains a hierarchy of objects:
+    </p>
+    <ul>
+      <li>
+        <tt><a href="doc/SimplerTiles/Map.html">SimplerTiles::Map</a></tt>: wraps
+        the <tt><a href="http://propublica.github.com/simple-tiles/#maps">simplet_map_t</a></tt>
+        C structure and contains projection information, <tt>SimplerTiles::Bounds</tt>
+        and a list of <tt>SimplerTiles::Layer</tt> objects. If you are using ActiveRecord
+        you can connect to and query your database backend by calling the
+        <tt>ar_layer</tt> method.
+      </li>
+      <li>
+        <tt><a href="doc/SimplerTiles/Bounds.html">SimplerTiles::Bounds</a></tt>: wraps
+        the <tt><a href="http://propublica.github.com/simple-tiles/#bounds">simplet_bounds_t</a></tt>
+        C structure and specifies the limit of the map in spatial coordinates.
+      </li>
+      <li>
+        <tt><a href="doc/SimplerTiles/Map.html">SimplerTiles::Layer</a></tt>: wraps
+        the <tt><a href="http://propublica.github.com/simple-tiles/#layers">simplet_layer_t</a></tt>
+        C structure and contains an OGR connection string for a particular data source,
+        and contains a list of <tt>SimplerTiles::Query</tt> objects.
+      </li>
+      <li>
+        <tt><a href="doc/SimplerTiles/Query.html">SimplerTiles::Query</a></tt>: wraps
+        the <tt><a href="http://propublica.github.com/simple-tiles/#queries">simplet_query_t</a></tt>
+        C structure and contains an OGR SQL string to filter its parent layer's
+        data source.
+      </li>
+      <li>
+        <tt><a href="doc/SimplerTiles/Style.html">SimplerTiles::Style</a></tt>: wraps
+        the <tt><a href="http://propublica.github.com/simple-tiles/#style">simplet_style_t</a></tt>
+        C structure and specifies a Simple Tiles
+        <a href="http://propublica.github.com/simple-tiles/#styles">style declaration</a>.
+      </li>
+    </ul>
+    <p>
+      As an example of how this fits together, here is a script that generates
+      the Simpler Tiles logo (full repository
+      <a href="https://github.com/thejefflarson/simpler-tiles-contours">here</a>):
+    </p>
+<%= highlight 'ruby', <<-CODE
+require 'rubygems'
+require 'simpler_tiles'
+ROOT = File.expand_path(File.dirname(__FILE__))
+map = SimplerTiles::Map.new do |m|
+  m.srs     = "EPSG:3083"
+  m.bgcolor = "#ffffff"
+  m.width   = 423
+  m.height  = 260
+  m.set_bounds(-585080.885134, 6849466.721081, 4161303.603672, 9587780.816356)
+  Dir["\#\{ROOT\}/data/*.shp"].each do |shp|
+    m.layer shp do |l|
+      l.query "select * from '\#\{File.basename shp, '.shp'\}'" do |q|
+        q.styles "stroke" => "#111111",
+              "line-join" => "round",
+                 "weight" => "0.1"
+      end
+    end
+  end
+end
+File.open("\#\{ROOT\}/out.png", 'w') {|f| f.write map.to_png }
+CODE
+%>
+    <h2>A Basic Tile Server</h2>
+    <p>
+      Simpler Tiles was designed to make <a href="http://wiki.openstreetmap.org/wiki/Slippy_Map">slippy maps</a>. The following is a basic tile
+      server using <a href="http://sinatrarb.com">Sinatra</a>. It will open display any shapefile on your hard drive
+      by visiting a url like: <a href="">http://localhost:4567/shape/path/to/shapefile.shp</a>
+    </p>
+<%= highlight 'ruby', <<-CODE
+require 'rubygems'
+require 'sinatra'
+require 'simpler_tiles'
+# Grab the user's home directory
+ROOT = File.expand_path("~")
+# Set up a route that will grab the path to a shapefile and render the
+# index template below.
+get '/shape/*' do
+  erb :index
+end
+# Set up the tile url to capture x, y, z coordinates for slippy tile generation
+get '/tiles/*/:x/:y/:z.png' do
+  # Let the browser know we are sending a png
+  content_type 'image/png'
+  # Create a Map object
+  map = SimplerTiles::Map.new do |m|
+    # Set the background color to black
+    m.bgcolor = "#000000"
+    # Set the slippy map parameters from the url
+    m.slippy params[:x].to_i, params[:y].to_i, params[:z].to_i
+    # Add a layer based on the parameters in the URL
+    m.layer File.join(ROOT, params[:splat].first) do |l|
+      # Grab all of the data from the shapefile
+      l.query "select * from '\#\{File.basename(params[:splat].first, '.shp')\}'" do |q|
+        # Add a style for stroke, fill, weight and set the line-join to be round
+        q.styles 'stroke' => '#002240',
+                 'weight' => '1',
+              'line-join' => 'round',
+                   'fill' => '#ffffff'
+      end
+    end
+  end
+  # Finally, render the map and ship it off
+  map.to_png
+end
+# A simple inline template for the map
+__END__
+@@index
+<!doctype html>
+<html>
+<head>
+  <script src="http://leaflet.cloudmade.com/dist/leaflet.js"></script>
+  <link rel="stylesheet"  href="http://leaflet.cloudmade.com/dist/leaflet.css">
+  <style>
+    body, html {
+      margin: 0;
+      padding: 0;
+      background-color: #000000;
+      width: 100%;
+      height: 100%;
+    }
+    #map {
+      width: 100%;
+      height: 100%;
+    }
+  </style>
+</head>
+<body>
+  <div id="map"></div>
+  <script>
+    var map = new L.Map('map');
+    var layer = new L.TileLayer('/tiles/\<\%\= params[:splat] \%\>/{x}/{y}/{z}.png')
+    map.addLayer(layer).setView(new L.LatLng(38, -95), 1);
+  </script>
+</body>
+</html>
+CODE
+%>
+    <p>
+      <strong>That's in no way a safe or secure thing to put on the internet</strong>, but it will
+      do as a simple replacement for QGIS!
+    </p>
+    <h2>Tips and Tricks</h2>
+    <p>
+      Deploying dynamically generated maps is difficult because of the data sizes and
+      processing required to render them. At ProPublica we have been following
+      these best practices:
+    </p>
+    <ol>
+      <li>
+        If you are using a PostGIS backend make sure to limit your queries to
+        the bounds of the image. You will want to add a <tt>where</tt> clause to each
+        trip to the database like so:
+<%= highlight 'ruby', <<-CODE
+layer.query Shape.where("the_geom && SRID=4326;\#\{map.buffered_bounds.reproject(map.srs, 'epsg:4326').to_wkt}'\}").to_sql do |query|
+  # ...
+end
+CODE
+%>
+        This will protect against doing a full table scan in your database.
+      </li>
+      <li>
+        <p>
+          If you are serving images as part of a tiled map, you'll also want to
+          put a proxy in front of your server with far future expiration date. At
+          ProPublica we're using cloudfront to serve this tile:
+        </p>
+        <img src="http://tiles-a.propublica.org/redistricting-maps/tiles/CA/12/330/789/11.png">
+        <p>
+          It will also speed up browser-side rendering if you have multiple domains
+          that proxy the tiles (eg. tiles-a.propublica.org, tiles-b.propublica.org, etc.)
+        </p>
+      </li>
+      <li>
+        Because of the extra time spent in collision detection for labels, you'll
+        probably want to limit the amount of labels you are displaying on a particular
+        tile.
+      </li>
+      <li>
+        If you are displaying labels (cf.
+        <a href="http://propublica.github.com/simple-tiles/#styles">text-field and font styles</a>)
+        you'll want to use a buffer -- usually  a quarter to a half of a tile
+        (i.e. for a 256 tile set the buffer to be 64 to 128 pixels) -- so that
+        the layout isn't clipped at tile boundaries. You can assign a buffer on
+        <tt>SimplerTiles::Map</tt> objects like so:
+<%= highlight 'ruby', <<-CODE
+  map.buffer 128
+CODE
+%>
+      </li>
+      <li>
+        Finally, for truly speedy maps, storing your spatial data in the Web Mercator
+        projection -- <tt>epsg:3785</tt> -- will cut down on response time
+        because each geometry object won't need to be reprojected.
+      </li>
+    </ol>
+    <h2>License</h2>
+<pre>
+Copyright (c) 2012, ProPublica
+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 rights
+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.
+</pre>
+    <p><em>Simpler Tiles is a project of ProPublica.</em></p>
+  </body>
+</html>