tsuga 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3b7231a847c915d67cec25a993f18e479eafaab9
+  data.tar.gz: c75775155ef056b707cf291bfff6bedf8c2ee176
+SHA512:
+  metadata.gz: a7a8011265392a799313b381e7fd2b16efa724d626f4ec0eeb02268c5b33588adfe27d7cb8a947aeb26315aa7e2d42a348b5fd66beb24c18f7fe1c1881ab333b
+  data.tar.gz: f0a71c00014efc2e0b72019488ab472ddaa270e36666130902b3e1efffb1bd540acba79c535891cd0d9e61573da0832553b1daf1b9078cc90562920481ff6635

data/.gitignore

@@ -0,0 +1,5 @@
+.bundle
+coverage
+tmp
+.tags*
+doc/

data/.rspec

@@ -0,0 +1,3 @@
+--color
+#--format d
+--format progress

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p247

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 2.0.0
+script:
+  - bundle exec rspec spec
+branches:
+  only:
+    - master
+
+services:
+  - mongodb
+

data/Gemfile

@@ -0,0 +1,16 @@
+source ENV.fetch('GEM_SOURCE', 'https://rubygems.org')
+
+# Specify your gem's dependencies in tsuga.gemspec
+gemspec
+
+gem 'sqlite3',           :require => false
+gem 'mysql2',            :require => false
+gem 'sequel',            :require => false
+gem 'mongoid',           :require => false
+gem 'activerecord',      :require => false
+gem 'perftools.rb',      :require => false
+
+gem 'travis',            :require => false
+gem 'websocket-native',  :require => false
+
+gem 'ruby-progressbar'

data/Gemfile.lock

@@ -0,0 +1,146 @@
+PATH
+  remote: .
+  specs:
+    tsuga (0.0.1)
+      ruby-progressbar
+
+GEM
+  remote: http://yarp.dev/
+  specs:
+    activemodel (3.2.15)
+      activesupport (= 3.2.15)
+      builder (~> 3.0.0)
+    activerecord (3.2.15)
+      activemodel (= 3.2.15)
+      activesupport (= 3.2.15)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.15)
+      i18n (~> 0.6, >= 0.6.4)
+      multi_json (~> 1.0)
+    addressable (2.3.5)
+    arel (3.0.2)
+    backports (3.3.5)
+    builder (3.0.4)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    coderay (1.0.9)
+    diff-lcs (1.2.4)
+    ethon (0.6.1)
+      ffi (>= 1.3.0)
+      mime-types (~> 1.18)
+    faraday (0.8.8)
+      multipart-post (~> 1.2.0)
+    faraday_middleware (0.9.0)
+      faraday (>= 0.7.4, < 0.9)
+    ffi (1.9.0)
+    formatador (0.2.4)
+    gh (0.13.0)
+      addressable
+      backports
+      faraday (~> 0.8)
+      multi_json (~> 1.0)
+      net-http-persistent (>= 2.7)
+      net-http-pipeline
+    guard (2.1.1)
+      formatador (>= 0.2.4)
+      listen (~> 2.1)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    guard-rspec (4.0.3)
+      guard (>= 2.1.1)
+      rspec (~> 2.14)
+    highline (1.6.20)
+    i18n (0.6.5)
+    launchy (2.3.0)
+      addressable (~> 2.3)
+    listen (2.1.1)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.4)
+    method_source (0.8.2)
+    mime-types (1.25)
+    mongoid (3.1.5)
+      activemodel (~> 3.2)
+      moped (~> 1.4)
+      origin (~> 1.0)
+      tzinfo (~> 0.3.29)
+    moped (1.5.1)
+    multi_json (1.8.2)
+    multipart-post (1.2.0)
+    mysql2 (0.3.13)
+    net-http-persistent (2.9)
+    net-http-pipeline (1.0.1)
+    netrc (0.7.7)
+    origin (1.1.0)
+    perftools.rb (2.0.1)
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    pry-nav (0.2.3)
+      pry (~> 0.9.10)
+    pusher-client (0.3.1)
+      ruby-hmac (~> 0.4.0)
+      websocket (~> 1.0.0)
+    rake (10.1.0)
+    rb-fsevent (0.9.3)
+    rb-inotify (0.9.2)
+      ffi (>= 0.5.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.6)
+    rspec-expectations (2.14.3)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    ruby-hmac (0.4.0)
+    ruby-progressbar (1.2.0)
+    sequel (4.3.0)
+    slop (3.4.6)
+    sqlite3 (1.3.8)
+    terminal-notifier (1.5.1)
+    thor (0.18.1)
+    timers (1.1.0)
+    travis (1.5.5)
+      backports
+      faraday (~> 0.8.7)
+      faraday_middleware (~> 0.9)
+      gh (~> 0.13)
+      highline (~> 1.6)
+      launchy (~> 2.1)
+      netrc (~> 0.7)
+      pry (~> 0.9)
+      pusher-client (~> 0.3, >= 0.3.1)
+      terminal-notifier (>= 1.4.2)
+      typhoeus (~> 0.6)
+    typhoeus (0.6.5)
+      ethon (~> 0.6.1)
+    tzinfo (0.3.38)
+    websocket (1.0.7)
+    websocket-native (1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord
+  bundler (~> 1.3)
+  guard
+  guard-rspec
+  mongoid
+  mysql2
+  perftools.rb
+  pry
+  pry-nav
+  rake
+  rspec
+  ruby-progressbar
+  sequel
+  sqlite3
+  travis
+  tsuga!
+  websocket-native

data/Guardfile

@@ -0,0 +1,8 @@
+require 'bundler/setup'
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/tsuga/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Julien Letessier
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,161 @@
+# Tsuga
+
+[![Build Status](https://travis-ci.org/mezis/tsuga.png?branch=master)](https://travis-ci.org/mezis/tsuga)
+
+<img width="320" style="margin-left:1em;margin-bottom:1em;clear:both;float:right;" src="http://cl.ly/image/251X2b1p1B00/b1.jpg"/>
+<img width="320" style="margin-left:1em;margin-bottom:1em;clear:both;float:right;" src="http://cl.ly/image/1T1U421F1P2G/b2.jpg"/>
+
+A **clustering engine** for geographical data (points of interest) that
+produces a **tree** of clusters, with depths matching zoomlevels on typical
+maps, and source points of interest as leaves.
+
+Makes heavy use of [Geohash](http://en.wikipedia.org/wiki/Geohash)-like and
+[Morton codes](http://en.wikipedia.org/wiki/Morton_number_%28number_theory%29).
+
+Designed with Rails usage in mind, but usable without Rails or even without a database.
+
+Go play with the [live demo](http://tsuga-demo.herokuapp.com/) from which
+the screenshots on the right were taken. Be patient, it's a free Heroku app!
+The [source](http://github.com/mezis/tsuga-demo) of the demo is an example
+of how to use Tsuga.
+
+### Why?
+
+Yes, Google Maps [does this](https://code.google.com/p/google-maps-utility-library-v3/wiki/Libraries#Marker_Clusterer_Plus)... for small datasets.
+
+- **Performance**. If you're handling thousands to millions of points of
+  interest, you cannot rely on client-side clustering anymore, if only because
+  sending the coordinates across would take minutes. <br/>
+  Tsuga gives you millisecond queries to find clusters to display, even when your
+  source dataset is huge.
+
+- **Structure**. Client-side solution cluster the markers you have. If you
+  want to let users drill down into data, you need to preserve a tree
+  structure: zooming in on a cluster should show what's "inside". <br/>
+  Tsuga builds a walkable tree of clusters.
+
+
+# Installation
+
+Add the `tsuga` gem to your `Gemfile`:
+
+    gem 'tsuga'
+
+
+# Usage
+
+Four steps are typically involved:
+
+1. Provide a source of points of interest to cluster
+2. Provide storage for clusters
+3. Run the clusterer
+4. Lookup clusters or a particlar map viewport
+
+
+## Providing source points
+
+Tsuga need to know how to iterate over points of interests.
+Any enumerable will do as long as 
+- it responds to `find_each` or `each`, and
+- it yields records that respond to `id` with an integer, and to `lat` and `lng` with floating-point numbers.
+
+Simply put, anything `ActiveModel`-ish should do.
+
+
+## Providing cluster storage
+
+
+Tsuga also need you to provide storage for the clusters. Currently supported
+are [Mongoid][mongoid], [Sequel][sequel], and [ActiveRecord][active_record] (an in-memory backend is provided, but is
+only useful for testing or extremely small datasets).
+
+
+### ActiveRecord
+
+Example with [ActiveRecord][active_record]. Create a migration:
+
+    require 'tsuga/adapter/active_record/cluster_migration'
+
+    class AddClusters < ActiveRecord::Migration
+      include Tsuga::Adapter::ActiveRecord::Migration
+      self.clusters_table_name = :clusters
+    end
+
+And the matching `Cluster` model:
+
+    # app/models/cluster.rb
+    require 'tsuga/adapter/active_record/cluster_model'
+
+    class Cluster < ActiveRecord::Model
+      include Tsuga::Adapter::ActiveRecord::ClusterModel
+    end
+
+
+### Mongoid
+
+Example with [Mongoid][mongoid].
+
+    # app/models/cluster.rb
+    require 'tsuga/adapter/mongoid/cluster_model'
+
+    class Cluster
+      include Tsuga::Adapter::Mongoid::ClusterModel
+    end
+
+
+### Sequel
+
+Example with [Sequel][sequel].
+
+    # app/models/cluster.rb
+    require 'tsuga/adapter/sequel/cluster_model'
+
+    class Cluster < Sequel::Model(:clusters)
+      include Tsuga::Adapter::Sequel::ClusterModel
+    end
+
+You will have to provide your own migration, respecting the schema in
+`Tsuga::Adapter::ActiveRecord::Migration`.
+
+
+## Running the clusterer service
+
+The clustering engine is `Tsuga::Service::Clusterer`, and running a full
+clustering is as simple as:
+
+    require 'tsuga'
+    Tsuga::Service::Clusterer.new(source: PointOfInterest, adapter: Cluster).run
+
+This will delete all existing clusters, walk the points of interest, and
+rebuild a tree of clusters.
+
+
+## Finding clusters
+
+Tsuga extended your cluster class with helper class methods:
+
+    nw = Tsuga::Point(lat: 45, lng: 1)
+    se = Tsuga::Point(lat: 44, lng: 2)
+    Cluster.in_viewport(nw, se)
+
+will return an enumerable (scopish where possible), that responds to
+`find_each`, `each`, and `count`, and contains clusters within the specified
+viewport.
+
+## Cluster API
+
+Clusters have at least the following accessors:
+
+| method      | description                            |
+|-------------|----------------------------------------|
+| `lat`       | latitude of the cluster's barycenter   |
+| `lng`       | longitude of the cluster's barycenter  |
+| `weight`    | total number of points (leaves) in subtree |
+| `children`  | enumerable of child clusters (or points of interest) |
+| `depth`     | the scale this cluster is relevant at, where 0 is the whole world |
+
+
+[mongoid]:       http://mongoid.org/
+[sequel]:        http://sequel.rubyforge.org/
+[active_record]: http://guides.rubyonrails.org/
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/tsuga.rb

@@ -0,0 +1,11 @@
+module Tsuga
+  MIN_DEPTH = 3
+  MAX_DEPTH = 19
+  
+  def self.Point(*args)
+    require 'tsuga/model/point'
+    Tsuga::Model::Point.new(*args)
+  end
+end
+
+require "tsuga/version"

data/lib/tsuga/adapter.rb

@@ -0,0 +1,4 @@
+require 'tsuga'
+
+module Tsuga::Adapter
+end

data/lib/tsuga/adapter/active_record/base.rb

@@ -0,0 +1,61 @@
+require 'tsuga/errors'
+require 'tsuga/adapter'
+require 'active_record'
+require 'delegate'
+
+module Tsuga::Adapter::ActiveRecord
+  module Base
+    def self.included(by)
+      by.extend DatasetMethods
+    end
+
+    def id
+      @_id ||= super
+    end
+
+    def persist!
+      save!
+    end
+
+    module DatasetMethods
+      def mass_create(new_records)
+        return if new_records.empty?
+
+        # Old SQLite versions (like on Travis) do not support bulk inserts
+        if connection.class.name !~ /sqlite/i || connection.send(:sqlite_version) >= '3.7.11'
+          _bulk_insert(new_records)
+        else
+          new_records.each(&:save!)
+        end
+      end
+
+      def mass_update(records)
+        transaction do
+          records.each(&:save!)
+        end
+      end
+
+      def collect_ids
+        pluck(:id)
+      end
+
+      private
+
+      def _bulk_insert(records)
+        attributes = records.map(&:attributes)
+        keys = attributes.first.keys - ['id']
+        column_names = keys.map { |k| connection.quote_column_name(k) }.join(', ')
+        sql = <<-SQL
+          INSERT INTO #{quoted_table_name} (#{column_names}) VALUES
+        SQL
+        value_template = (["?"] * keys.length).join(', ')
+        value_strings = attributes.map do |attrs|
+          values = keys.map { |k| attrs[k] }
+          sanitize_sql_array([value_template, *values])
+        end
+        full_sql = sql + value_strings.map { |str| "(#{str})"}.join(', ')
+        connection.insert_sql(full_sql)
+      end
+    end
+  end
+end