geotree 1.1.3 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d76fc2dc033f2ce8bcbfd647c63d571f24727a0c
-  data.tar.gz: c08e6cfb67594b35a46bcdab10fac8bf3b10a41a
+  metadata.gz: e27ac7237a87748973d68e8e8ab42fa3fd3de713
+  data.tar.gz: 2d3c2f8fe96472d903d0779b2f998af147c92b3e
 SHA512:
-  metadata.gz: 7fe31727a3a6d8188f467e08c63fda63fe15ec6d5bb5678051ee2364276f3a9dfd54a941be42df578c6defca1ff390eaf08d9cf48d47e7970f4d921581378ce6
-  data.tar.gz: 90b7fd6dbea9a82724ea3307b6361723829e05274356d7eeefe247f22e9e9b5e3b41943818c8b2ae85c3f00d1625e9a545b06bb3448f283729ea73ef8e64a7ae
+  metadata.gz: bd5d7194460709171d65219dbdf19686d24d2b8cf768c3aa5ac5fc4a010157654b4ad3cc44dea7c250ff578cab3b6484a40da57d9f7784740ef998599453ec1a
+  data.tar.gz: 26cc87072057131efa87568e1990a8fd8aa8f2fed43b4f3424bfed117a81eb69d3b0958c7894d03b7a9bee130a0e2d826b35d4d2aeaba8e9466f6f2d8b5556ae

data/CHANGELOG.txt

@@ -10,4 +10,8 @@
 
   * Version 1.1.3
   * Fixed problem with link URL's
-  
+ 
+  * Version 1.1.4
+  * Placed on github
+  * Moved some documentation out of class headers and into README file
+

data/README.md

@@ -0,0 +1,140 @@
+
+geotree
+=======
+GeoTree is a ruby gem that maintains a set of geographical points, reports points lying within a query rectangle,
+and supports multiple levels of detail.
+
+Written by Jeff Sember, April 2013.
+
+[Source code documentation can be found here.](http://rubydoc.info/gems/geotree/frames)
+
+
+
+GeoTree
+-------
+
+A GeoTree  is a variant of a k-d tree (with d = 2), and stores data points that have a latitude 
+and longitude, a unique integer identifier, and an optional 'weight' (e.g., the 
+size of a city).  A GeoTree is capable of efficiently
+reporting all points lying within (axis-aligned) query rectangles.
+GeoTrees are disk-based data structures and can store a very large 
+number of points efficiently.  
+
+[Here's an animation of a GeoTree in action.](http://www.cs.ubc.ca/~jpsember/geo_tree.ps)
+
+   
+Like a B+ tree, a GeoTree has a large branching factor
+and the nodes are large to improve performance when the tree is stored
+on disk.
+   
+A GeoTree is usually stored within a disk file, though it is also possible to
+construct a tree that exists only in memory; see the initialize(...) method.
+   
+    
+Usage:
+   
+ * Open a tree.  If no tree exists, a new, empty one is created:
+   
+         t = GeoTree.open("treepath.bin")
+   
+ * Add datapoints:
+   
+         dp = DataPoint.new(42, 3, Loc.new(120,300))
+         t.add(dp)
+   
+ * Remove datapoints:
+   
+         t.remove(dp)
+   
+ * Find all points within a particular rectangle:
+   
+         b = Bounds.new(x,y,width,height)
+         pts = t.find(b)
+   
+ * Close a tree; flush any changes:
+   
+         t.close()
+   
+   
+One of the problems with k-d trees (including this one) is that they can become
+unbalanced after a number of insertions and deletions.  To deal with this,
+consider these two suggestions:
+ 
+ 1. When constructing the initial tree, if the datapoints are given in a random
+      order, the tree will (with high probability) be constructed in a balanced form.
+      By contrast, consider what happens if the points (1,1), (2,2), (3,3), ... are
+      added in sequence to an initially empty tree.  The tree will be very unbalanced,
+      with poor performance.
+      To address this problem, if you are not confident that the points you initially
+      provide are in a sufficiently random sequence, you can enable 'point buffering':
+ 
+ 
+	       t = GeoTree.open("treepath.bin")
+	 
+	       t.buffering = true     buffering is now active
+	 
+	       t.add(dp1)
+	       t.add(dp2)             these points are stored in a temporary disk file
+	       t.add(dp3)
+	          :
+	 
+	       t.buffering = false    the points will be shuffled into a random sequence and
+	                              added to the tree
+ 
+ 
+ 1. Periodically, you can start with a new tree, and add all of the datapoints using the
+       above buffering technique.  This is easy to do if the datapoints are also stored
+       externally to the GeoTree (for instance, as parts of larger records in some database).
+       Otherwise, (i) the datapoints can be retrieved from the tree to an array
+       (by using a sufficiently large query rectangle), (ii) a new tree can be constructed,
+       and (iii) each of the points in the array can be added to the new tree.
+   
+
+
+MultiTree
+-------
+
+
+The gem includes MultiTree, a GeoTree variant that supports queries at multiple 
+levels of detail. For example, when focusing on a small region it can return points 
+that would be omitted when querying a much larger region.
+
+[Here's an animation of a MultiTree in action.](http://www.cs.ubc.ca/~jpsember/multi_tree.ps)
+
+
+As one use case, consider a map application.  Ideally, it should display approximately 
+the same number of datapoints when the screen displays the entire state of California, as well as
+when it is 'zoomed in' on a particular section of the Los Angeles area.
+
+
+To accomplish this, a MultiTree maintains several GeoTrees, each for a different
+level of detail.  The highest detail tree contains every datapoint that has been
+added to the tree, and lower detail trees will have progressively fewer points.
+
+When querying a MultiTree, the user must specify which level of detail (i.e.,
+which of the contained trees) is to be examined.  
+
+
+Usage:
+
+ * Open a tree.  If no tree exists, a new, empty one is created:
+   
+         detail_levels = 5
+         t = MultiTree.new("treepath.bin", detail_levels)
+   
+ * Adding and removing datapoints are the same as with GeoTrees:
+   
+         dp = DataPoint.new(42, 3, Loc.new(120,300))
+         t.add(dp)
+         t.remove(dp)
+   
+ * Find all points within a particular rectangle (specifying the level of detail):
+   
+         b = Bounds.new(x,y,width,height)
+         pts = t.find(b, 3)
+   
+ * Close a tree; flush any changes:
+   
+         t.close()
+
+ 

data/lib/geotree/geotree.rb

@@ -3,76 +3,8 @@ require_relative 'node'
 req 'diskblockfile ptbuffer'
 
 module GeoTreeModule
-  #
-  # A variant of a kd-tree, it is capable of maintaining sets of 2D points and efficiently
-  # reporting all points lying within (axis-aligned) query rectangles.
-  #
-  # Like a B+ tree, it has a large branching factor
-  # and the nodes are large to improve performance when the tree is stored
-  # on disk.
-  #
-  # A GeoTree is usually stored within a disk file, though it is also possible to
-  # construct a tree that exists only in memory; see the initialize(...) method.
-  #
-  # {An animation of a GeoTree in action.}[link:http://www.cs.ubc.ca/~jpsember/geo_tree.ps]
-  #
-  # Usage:
-  #
-  # [] Open a tree.  If no tree exists, a new, empty one is created.
-  #
-  #      t = GeoTree.open("treepath.bin")
-  #
-  # [] Add datapoints.
-  #
-  #      dp = DataPoint.new(...)
-  #      t.add(dp)
-  #
-  # [] Remove datapoints.
-  #
-  #      t.remove(dp)
-  #
-  # [] Find all points within a particular rectangle.
-  #
-  #      b = Bounds.new(x,y,width,height)
-  #
-  #      pts = t.find(b)
-  #
-  # [] Close tree; flush any changes.
-  #
-  #      t.close()
-  #
-  #
-  # One of the problems with kd-trees (including this one) is that they can become
-  # unbalanced after a number of insertions and deletions.  To deal with this,
-  # consider these two suggestions:
-  #
-  #  1) When constructing the initial tree, if the datapoints are given in a random
-  #     order, the tree will (with high probability) be constructed in a balanced form.
-  #     By contrast, consider what happens if the points (1,1), (2,2), (3,3), ... are
-  #     added in sequence to an initially empty tree.  The tree will be very unbalanced,
-  #     with poor performance.
-  #     To address this problem, if you are not confident that the points you initially
-  #     provide are in a sufficiently random sequence, you can enable 'point buffering':
-  #
-  #      t = GeoTree.open("treepath.bin")
-  #
-  #      t.buffering = true   # buffering is now active
-  #
-  #      t.add(dp1)
-  #      t.add(dp2)           # these points are stored in a temporary disk file
-  #      t.add(dp3)
-  #         :
-  #
-  #      t.buffering = false  # the points will be shuffled into a random sequence and
-  #                           # added to the tree
-  #
-  #
-  #   2) Periodically, you can start with a new tree, and add all of the datapoints using the
-  #      above buffering technique.  This is easy to do if the datapoints are also stored
-  #      externally to the GeoTree (for instance, as parts of larger records in some database).
-  #      Otherwise, (i) the datapoints can be retrieved from the tree to an array
-  #      (by using a sufficiently large query rectangle), (ii) a new tree can be constructed,
-  #      and (iii) each of the points in the array can be added to the new tree.
+  # 
+  # See the README file for a discussion of this class.
   #
   class GeoTree
 

data/lib/geotree/multitree.rb

@@ -2,21 +2,8 @@ require_relative 'tools'
 req 'geotree'
 
 module GeoTreeModule
-  
-  # A variant of GeoTree that supports queries at multiple resolutions.
   #
-  # For example, a map application should return approximately the same number of
-  # datapoints when the screen displays the entire state of California, as well as
-  # when it is 'zoomed in' on a particular section of the Los Angeles area.
-  #
-  # To accomplish this, a MultiTree maintains several GeoTrees, each for a different
-  # level of detail.  The highest detail tree contains every datapoint that has been
-  # added to the tree, and lower detail trees will have progressively fewer points.
-  #
-  # When querying a MultiTree, the user must specify which level of detail (i.e.,
-  # which of the contained trees) is to be examined.   
-  #
-  # {An animation of a MultiTree in action.}[link:http://www.cs.ubc.ca/~jpsember/multi_tree.ps]   
+  # See the README file for a description of this class.
   #
   class MultiTree
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geotree
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 1.1.4
 platform: ruby
 authors:
 - Jeff Sember
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-01 00:00:00.000000000 Z
+date: 2013-04-09 00:00:00.000000000 Z
 dependencies: []
 description: "  \nA GeoTree  is a variant of a k-d tree, and stores data points that
   have a latitude and longitude, \na unique integer identifier, and an optional 'weight'
@@ -37,7 +37,7 @@ files:
 - lib/geotree/ptbuffer.rb
 - lib/geotree/tools.rb
 - CHANGELOG.txt
-- README.txt
+- README.md
 - test/test_blockfile.rb
 - test/test_externalsort.rb
 - test/test_geotree.rb

data/README.txt

@@ -1,29 +0,0 @@
-# @markup markdown
-
-geotree
-=======
-A ruby gem that maintains a set of geographical points, reports points lying within a query rectangle,
-and supports multiple levels of detail.
-
-Written and (c) by Jeff Sember, April 2013.
-
-
-GeoTree
--------
-
-A GeoTree  is a variant of a k-d tree, and stores data points that have a latitude 
-and longitude, a unique integer identifier, and an optional 'weight' (e.g., the 
-size of a city).  GeoTrees are disk-based data structures and can store a very large 
-number of points efficiently.  If desired, for smaller data sets, memory-only trees 
-can be constructed instead.
-
-Here's an animation of a GeoTree in action: <http://www.cs.ubc.ca/~jpsember/geo_tree.ps>
-
-MultiTree
--------
-
-The gem includes MultiTree, a GeoTree variant that supports queries at multiple 
-levels of detail. For example, when focusing on a small region it can return points 
-that would be omitted when querying a much larger region.
-
-Here's an animation of a MultiTree in action: <http://www.cs.ubc.ca/~jpsember/multi_tree.ps>